boost/parameter
2
0
Fork 0
mirror of https://github.com/boostorg/parameter.git synced 2026-01-26 18:52:22 +00:00
Code Issues Projects Releases Wiki Activity
Files
boost-1.33.1
parameter/doc/reference.rst
Dave Abrahams 43f2424a56 merged from trunk 
[SVN r30489]
2005-08-05 15:02:14 +00:00

689 lines
21 KiB
ReStructuredText
Executable File
Raw Permalink Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
The Boost Parameter Library Reference Documentation
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|(logo)|__
.. |(logo)| image:: ../../../../boost.png
:alt: Boost
__ ../../../../index.htm
:Authors: David Abrahams, Daniel Wallin
:Contact: dave@boost-consulting.com, dalwan01@student.umu.se
:organization: `Boost Consulting`_
:date: $Date: 2005/07/17 19:53:01 $
:copyright: Copyright David Abrahams, Daniel Wallin
2005. Distributed under the Boost Software License,
Version 1.0. (See accompanying file LICENSE_1_0.txt
or copy at http://www.boost.org/LICENSE_1_0.txt)
.. _`Boost Consulting`: http://www.boost-consulting.com
//////////////////////////////////////////////////////////////////////////////
.. contents::
:depth: 2
//////////////////////////////////////////////////////////////////////////////
.. role:: class
:class: class
.. role:: concept
:class: concept
.. role:: function
:class: function
.. |ArgumentPack| replace:: :concept:`ArgumentPack`
.. |ParameterSpec| replace:: :concept:`ParameterSpec`
.. role:: vellipsis
:class: vellipsis
.. section-numbering::
:depth: 2
Preliminaries
=============
This section covers some basic information you'll need to know in
order to understand this reference
Namespaces
----------
In this document, all unqualified identifiers should be assumed to
be defined in namespace ``boost::parameter`` unless otherwise
specified.
Exceptions
----------
No operation described in this document
throws an exception unless otherwise specified.
Thread Safety
-------------
All components of this library can be used safely from multiple
threads without synchronization. [#thread]_
Typography
----------
Names written in :concept:`sans serif type` represent concepts_.
In code blocks, *italic type* represents unspecified text that
satisfies the requirements given in the detailed description that
follows the code block.
In a specification of the tokens generated by a macro, **bold
type** is used to highlight the position of the expanded macro
argument in the result.
The special character β represents the value of |BOOST_PARAMETER_MAX_ARITY|_.
//////////////////////////////////////////////////////////////////////////////
Terminology
===========
.. |kw| replace:: keyword
.. _kw:
keyword
The name of a function parameter.
.. _keyword tag type:
.. |keyword tag type| replace:: `keyword tag type`_
keyword tag type
A type used to uniquely identify a function parameter. Typically
its name will be the same as that of the parameter.
.. _positional:
.. |positional| replace:: `positional`_
positional argument
An argument passed with no explicit |kw|. Its parameter is
determined in the usual C++ way: by position with respect to a
parameter list.
.. _tag type:
.. |tag type| replace:: `tag type`_
tag type
Shorthand for “\ |keyword tag type|.”
.. _keyword object:
.. |keyword object| replace:: `keyword object`_
keyword object
An instance of |keyword|_ ``<T>`` for some |tag
type| ``T``.
.. _tagged reference:
.. |tagged reference| replace:: `tagged reference`_
tagged reference
An object whose type is associated with a |keyword tag type| (the
object's *keyword*), and that holds a reference (to the object's
*value*).
As a shorthand, a “tagged reference to ``x``\ ” means a tagged
reference whose *value* is ``x``.
.. _tagged default:
.. |tagged default| replace:: `tagged default`_
tagged default
A |tagged reference| whose *value* represents the value of a
default argument.
.. _tagged lazy default:
.. |tagged lazy default| replace:: `tagged lazy default`_
tagged lazy default
A |tagged reference| whose *value*, when invoked with no
arguments, computes a default argument value.
.. _intended argument type:
.. |intended argument type| replace:: `intended argument type`_
intended argument type
The *intended argument type* of a single-element |ArgumentPack|_ is the
type of its element's *value*. The intended argument type of any other
type ``X`` is ``X`` itself.
.. Note::
In this reference, we will use concept names (and other names)
to describe both types and objects, depending on context. So
for example, “an |ArgumentPack|_\ ” can refer to a type that
models |ArgumentPack|_ *or* an object of such a type.
//////////////////////////////////////////////////////////////////////////////
Concepts
========
This section describes the generic type concepts_ used by the Parameter library.
.. _concepts: ../../../../more/generic_programming.html#concept
|ArgumentPack|
--------------
An |ArgumentPack| is a collection of |tagged reference|\ s to the
actual arguments passed to a function.
Requirements
............
In the table below,
* ``A`` is a model of |ArgumentPack|
* ``x`` is an instance of ``A``
* ``u`` is a |keyword object| of type ``K``
* ``v`` is a |tagged default| with |tag type| ``L`` and *value* of type ``D``
* ``w`` is a |tagged lazy default| with |tag type| ``M`` and *value* of type ``E const``
* ``z`` is an |ArgumentPack| containing a single element (as created by |keyword|_\ ``<…>::operator=``)
Any exceptions are thrown from the invocation of ``w``\ 's *value*
will be propagated to the caller.
.. table:: |ArgumentPack| requirements
+----------+-----------------------------+------------------+--------------------------------------+
|Expression| Type |Requirements |Semantics/Notes |
+==========+=============================+==================+======================================+
|``x[u]`` |``binding<A,K>::type`` |``x`` contains an |Returns *b*\ 's *value* (by |
| | |element *b* whose |reference). |
| | ||kw|_ is ``K`` | |
+----------+-----------------------------+------------------+--------------------------------------+
|``x[u]`` |``binding<A,L,D>::type`` |*none* |If ``x`` contains an element *b* whose|
| | | ||kw|_ is the same as ``u``\ 's, |
| | | |returns *b*\ 's *value* (by |
| | | |reference). Otherwise, returns ``u``\|
| | | |'s *value*. |
+----------+-----------------------------+------------------+--------------------------------------+
|``x[w]`` |``lazy_binding<A,M,E>::type``|*none* |If ``x`` contains an element *b* whose|
| | | ||kw|_ is the same as ``w``\ 's, |
| | | |returns *b*\ 's *value* (by |
| | | |reference). Otherwise, invokes ``w``\|
| | | |'s *value* and returns the result. |
+----------+-----------------------------+------------------+--------------------------------------+
|``x, z`` |Model of |ArgumentPack| |*none* |Returns an |ArgumentPack|_ containing |
| | | |all the elements of both ``x`` and |
| | | |``z``. |
+----------+-----------------------------+------------------+--------------------------------------+
.. _parameterspec:
|ParameterSpec|
---------------
A |ParameterSpec| describes the type requirements for arguments
corresponding to a given |kw|_ and indicates whether the argument
is optional or required. The table below details the allowed forms
and describes their condition for satisfaction by an actual
argument type. In each row,
.. _conditions:
* ``K`` is the |ParameterSpec|\ 's |keyword tag type|
* ``A`` is an |intended argument type| associated with ``K``, if any
* ``F`` is a unary `MPL lambda expression`_
.. _`MPL lambda expression`: ../../../mpl/doc/refmanual/lambda-expression.html
.. table:: |ParameterSpec| allowed forms and conditions of satisfaction
+----------------------+--------------+--------------------------------+
|Type |``A`` required|Condition ``A`` must satisfy |
+======================+==============+================================+
||keyword|_\ ``<K>`` |no |*n/a* |
+----------------------+--------------+--------------------------------+
||optional|_\ ``<K,F>``|no |``mpl::apply<F,A>::type::value``|
| | |is ``true``. |
+----------------------+--------------+--------------------------------+
||required|_\ ``<K,F>``|yes |``mpl::apply<F,A>::type::value``|
| | |is ``true``. |
+----------------------+--------------+--------------------------------+
The information in a |ParameterSpec| is used to `limit`__ the
arguments that will be matched by `forwarding functions`_.
__ overloadcontrol_
.. _overloadcontrol: index.html#controlling-overload-resolution
.. _forwarding functions: index.html#forwarding-functions
//////////////////////////////////////////////////////////////////////////////
Class Templates
===============
.. |keyword| replace:: ``keyword``
.. _keyword:
``keyword``
-----------
The type of every |keyword object| is a specialization of |keyword|.
:Defined in: `boost/parameter/keyword.hpp`__
__ ../../../../boost/parameter/keyword.hpp
.. parsed-literal::
template <class Tag>
struct keyword
{
template <class T> |ArgumentPack|_ `operator=`_\(T& value) const;
template <class T> |ArgumentPack|_ `operator=`_\(T const& value) const;
template <class T> *tagged default* `operator|`_\(T& x) const;
template <class T> *tagged default* `operator|`_\(T const& x) const;
template <class F> *tagged lazy default* `operator||`_\(F const&) const;
static keyword<Tag>& get_\();
};
.. |operator=| replace:: ``operator=``
.. _operator=:
``operator=``
.. parsed-literal::
template <class T> |ArgumentPack|_ operator=(T& value) const;
template <class T> |ArgumentPack|_ operator=(T const& value) const;
:Requires: nothing
:Returns:
an |ArgumentPack|_ containing a single |tagged reference| to
``value`` with |kw|_ ``Tag``
.. _operator|:
``operator|``
.. parsed-literal::
template <class T> *tagged default* operator|(T& x) const;
template <class T> *tagged default* operator|(T const& x) const;
:Returns: a |tagged default| with *value* ``x`` and |kw|_ ``Tag``.
.. _operator||:
``operator||``
.. parsed-literal::
template <class F> *tagged lazy default* operator||(F const& g) const;
:Requires: ``g()`` is valid, with type ``boost::``\ |result_of|_\
``<F()>::type``. [#no_result_of]_
:Returns: a |tagged lazy default| with *value* ``g`` and |kw|_ ``Tag``.
.. _get:
``get``
.. parsed-literal::
static keyword<Tag>& get\();
:Returns: a “singleton instance”: the same object will be
returned on each invocation of ``get()``.
:Thread Safety: ``get()`` can be called from multiple threads
simultaneously.
``parameters``
--------------
Provides an interface for assembling the actual arguments to a
`forwarding function` into an |ArgumentPack|, in which any
|positional| arguments will be tagged according to the
corresponding template argument to ``parameters``.
.. _forwarding function: `forwarding functions`_
:Defined in: `boost/parameter/parameters.hpp`__
__ ../../../../boost/parameter/parameters.hpp
.. parsed-literal::
template <class P0 = *unspecified*, class P1 = *unspecified*, …class P\ β = *unspecified*>
struct parameters
{
template <class A0, class A1 = *unspecified*, …class A\ β = *unspecified*>
struct `match`_
{
typedef … type;
};
template <class A0>
|ArgumentPack|_ `operator()`_\(A0 const& a0) const;
template <class A0, class A1>
|ArgumentPack|_ `operator()`_\(A0 const& a0, A1 const& a1) const; :vellipsis:`\
.
.
.
 `
template <class A0, class A1, …class A\ β>
|ArgumentPack|_ `operator()`_\(A0 const& a0, A1 const& a1, …A\ β const& a\ β) const;
};
:Requires: ``P0``, ``P1``, … ``P``\ β are models of |ParameterSpec|_.
.. Note::
In this section, ``R``\ *i* and ``K``\ *i* are defined as
follows, for any argument type ``A``\ *i*:
| ``R``\ *i* is ``A``\ *i*\ 's |intended argument type|
|
| if ``A``\ *i* is a result type of ``keyword<T>::``\ |operator=|_
| then
| ``K``\ *i* is ``T``
| else
| ``K``\ *i* is ``P``\ *i*\ 's |keyword tag type|.
.. _match:
``match``
A |Metafunction|_ used to remove a `forwarding function`_ from overload resolution.
:Returns: if ``P0``, ``P1``, …\ ``P``\ β are *satisfied* (see
below), then ``parameters<P0,P1,…Pβ>``. Otherwise,
``match<A0,A1,…Aβ>::type`` is not defined.
``P0``, ``P1``, …\ ``P``\ β are **satisfied** if, for
every *j* in 0…β, either:
* ``P``\ *j* is the *unspecified* default
* **or**, ``P``\ *j* is a specialization of |keyword|_,
* **or**, ``P``\ *j* is |optional|_ ``<X,F>`` and either
- ``X`` is not ``K``\ *i* for any *i*,
- **or** ``X`` is some ``K``\ *i* and ``mpl::apply<F,R``\ *i*\
``>::type::value`` is ``true``
* **or**, ``P``\ *j* is |required|_ ``<X,F>``, and
- ``X`` is some ``K``\ *i*, **and**
- ``mpl::apply<F,R``\ *i*\ ``>::type::value`` is ``true``
.. _operator():
``operator()``
.. parsed-literal::
template <class A0> |ArgumentPack|_ operator()(A0 const& a0) const; :vellipsis:`\
.
.
.
 `
template <class A0, …class A\ β> |ArgumentPack|_ `operator()`_\(A0 const& a0, …A\ β const& a\ β) const;
:Returns:
An |ArgumentPack|_ containing, for each ``a``\ *i*,
- if ``a``\ *i*, is a single-element |ArgumentPack|, its element
- Otherwise, a |tagged reference| with |kw|_ ``K``\ *i* and *value* ``a``\ *i*
.. |optional| replace:: ``optional``
.. |required| replace:: ``required``
.. _optional:
.. _required:
``optional``, ``required``
--------------------------
These templates describe the requirements on a function parameter.
:Defined in: `boost/parameter/parameters.hpp`__
__ ../../../../boost/parameter/parameters.hpp
:Specializations model: |ParameterSpec|_
.. parsed-literal::
template <class Tag, class Predicate = *unspecified*>
struct optional;
template <class Tag, class Predicate = *unspecified*>
struct required;
The default value of ``Predicate`` is an unspecified |Metafunction|_ that returns
``mpl::true_`` for any argument.
.. |Metafunction| replace:: :concept:`Metafunction`
.. _Metafunction: ../../../mpl/doc/refmanual/metafunction.html
//////////////////////////////////////////////////////////////////////////////
Metafunctions
=============
A |Metafunction|_ is conceptually a function that operates on, and
returns, C++ types.
``binding``
-----------
Returns the result type of indexing an argument pack with a
|keyword tag type| or with a |tagged default|.
:Defined n: `boost/parameter/binding.hpp`__
__ ../../../../boost/parameter/binding.hpp
.. parsed-literal::
template <class A, class K, class D = void>
struct binding
{
typedef … type;
};
:Requires: ``A`` is a model of |ArgumentPack|_.
:Returns: the reference type of the |tagged reference| in ``A``
having |keyword tag type| ``K``, if any. If no such |tagged
reference| exists, returns ``D``.
``lazy_binding``
----------------
Returns the result type of indexing an argument pack with a |tagged
lazy default|.
:Defined in:
`boost/parameter/binding.hpp`__
__ ../../../../boost/parameter/binding.hpp
.. parsed-literal::
template <class A, class K, class F>
struct lazy_binding
{
typedef … type;
};
:Requires: ``A`` is a model of |ArgumentPack|_.
:Returns: the reference type of the |tagged reference| in ``A``
having |keyword tag type| ``K``, if any. If no such |tagged
reference| exists, returns ``boost::``\ |result_of|_\ ``<F()>::type``. [#no_result_of]_
//////////////////////////////////////////////////////////////////////////////
Code Generation Macros
======================
Macros in this section can be used to ease the writing of code
using the Parameter libray by eliminating repetitive boilerplate.
``BOOST_PARAMETER_FUN(r,n,l,h,p)``
----------------------------------
Generates a sequence of `forwarding function`_ templates named
``n``, with arities ranging from ``l`` to ``h`` , returning ``r``,
and using ``p`` to control overload resolution and assign tags to
positional arguments.
:Defined in: `boost/parameter/macros.hpp`__
__ ../../../../boost/parameter/macros.hpp
:Requires: ``l`` and ``h`` are nonnegative integer tokens such
that ``l`` < ``h``
Generates
.. parsed-literal::
template <class A1, class A2, …class A##\ **l**>
r name(
A1 const& a1, A2 const& a2, …A\ **l** const& x\ **l**
, typename **p**::match<A1,A2,…A\ **l**>::type p = **p**\ ())
{
return **name**\ _with_named_params(**p**\ (x1,x2,…x\ **l**));
}
template <class A1, class A2, …class A\ **l**, class A\ ##\ BOOST_PP_INC_\ (**l**)>
r name(
A1 const& a1, A2 const& a2, …A\ **l** const& x\ **l**
, A\ ##\ BOOST_PP_INC_\ (**l**) const& x\ ##\ BOOST_PP_INC_\ (**l**)
, typename **p**::match<A1,A2,…A\ **l**,A\ ##\ BOOST_PP_INC_\ (**l**)>::type p = **p**\ ())
{
return **name**\ _with_named_params(**p**\ (x1,x2,…x\ **l**,x\ ##\ BOOST_PP_INC_\ (**l**)));
} :vellipsis:`\
.
.
.
 `
template <class A1, class A2, …class A\ **h**>
r name(
A1 const& a1, A2 const& a2, …A\ **h** const& x\ **h**
, typename **p**::match<A1,A2,…A\ **h**>::type p = **p**\ ())
{
return **name**\ _with_named_params(**p**\ (a1,a2,…a\ **h**));
}
.. _BOOST_PP_INC: ../../../preprocessor/doc/ref/inc.html
``BOOST_PARAMETER_KEYWORD(n,k)``
--------------------------------
Generates the declaration of a |keyword tag type| named ``k`` in
namespace ``n``, and a corresponding |keyword object| definition in
the enclosing namespace.
:Defined in: `boost/parameter/keyword.hpp`__
__ ../../../../boost/parameter/keyword.hpp
Generates
.. parsed-literal::
namespace **n** { struct **k**; }
namespace {
boost::parameter::keyword<*tag-namespace*::**k**>& **k**
= boost::parameter::keyword<*tag-namespace*::**k**>::get();
}
``BOOST_PARAMETER_MATCH(p,a,x)``
--------------------------------
Generates a defaulted parameter declaration for a `forwarding
function`_.
:Defined in: `boost/parameter/match.hpp`__
__ ../../../../boost/parameter/match.hpp
:Requires: ``a`` is a `Boost.Preprocessor sequence`__
of the form
.. parsed-literal::
(A0)(A1)…(A\ *n*)
__ http://www.boost.org/libs/preprocessor/doc/data.html
Generates
.. parsed-literal::
typename **p**::match<**A0**\ ,\ **A1**\ …,\ **A**\ *n*>::type **x** = **p**\ ()
Configuration Macros
====================
``BOOST_PARAMETER_MAX_ARITY``
-----------------------------
Determines the maximum number of arguments supported by the
library. Will only be ``#defined`` by the library if it is not
already ``#defined``.
.. |BOOST_PARAMETER_MAX_ARITY| replace:: ``BOOST_PARAMETER_MAX_ARITY``
:Defined in: `boost/parameter/config.hpp`__
__ ../../../../boost/parameter/config.hpp
:Default Value: ``5``
Tutorial
========
Follow `this link`__ to the Boost.Parameter tutorial
documentation.
__ index.html#tutorial
//////////////////////////////////////////////////////////////
.. [#thread] References to tag objects may be initialized multiple
times. This scenario can only occur in the presence of
threading. Because the C++ standard doesn't consider threading,
it doesn't explicitly allow or forbid multiple initialization of
references. That said, it's hard to imagine an implementation
where it could make a difference.
.. [#no_result_of] Where |BOOST_NO_RESULT_OF|_ is ``#defined``,
``boost::``\ |result_of|_\ ``<F()>::type`` is replaced by
``F::result_type``.
.. |result_of| replace:: ``result_of``
.. _result_of: ../../../utility/utility.htm#result_of
.. |BOOST_NO_RESULT_OF| replace:: ``BOOST_NO_RESULT_OF``
.. _BOOST_NO_RESULT_OF: ../../../utility/utility.htm#BOOST_NO_RESULT_OF
Reference in New Issue View Git Blame Copy Permalink