reference.rst

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

This template is used to wrap the *keyword tag* argument to
``optional`` or ``required``.

:Defined in: `boost/parameter/parameters.hpp`__

__ ../../../../boost/parameter/parameters.hpp

.. parsed-literal::

    template <class Tag>
    struct deduced;


//////////////////////////////////////////////////////////////////////////////

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]_


``value_type``
--------------

Returns the result type of indexing an argument pack with a
|keyword tag type| or with a |tagged default|.

:Defined n: `boost/parameter/value_type.hpp`__

__ ../../../../boost/parameter/value_type.hpp

.. parsed-literal::

    template <class A, class K, class D = void>
    struct value_type
    {
        typedef … type;
    };

:Requires: ``A`` is a model of |ArgumentPack|_.

:Returns: the type of the |tagged reference| in ``A``
  having |keyword tag type| ``K``, if any.  If no such |tagged
  reference| exists, returns ``D``. Equivalent to::

    typename remove_reference<
      typename binding<A, K, D>::type
    >::type

  … when ``D`` is not a reference type.


//////////////////////////////////////////////////////////////////////////////

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_FUNCTION(result,name,tag_namespace,arguments)``
-----------------------------------------------------------------

:Defined in: `boost/parameter/preprocessor.hpp`__

__ ../../../../boost/parameter/preprocessor.hpp

:Requires: ``result`` is the parenthesized return type of the function.
  ``name`` is the base name of the function, this is the name of the
  generated forwarding functions. ``tag_namespace`` is the namespace in
  which the keywords used by the function resides. ``arguments`` is
  a list of *argument specifiers*, as defined below.


:Argument specifiers syntax:
  .. parsed-literal::

    argument-specifiers ::= *specifier-group* {*specifier-group*}

    specifier-group0 ::= *specifier-group1* |
                         ( '**(**' '**deduced**' *specifier-group1* {*specifier-group1*} '**)**' )

    specifier-group1 ::= ( '**(**' '**optional**' *optional-specifier* {*optional-specifier*} '**)**' ) |
                         ( '**(**' '**required**' *required-specifier* {*required-specifier*} '**)**' )

    optional-specifier ::= '**(**' *name* '**,**' *restriction* '**,**' *default-value* ')'
    required-specifier ::= '**(**' *name* '**,**' *restriction* ')'

    restriction ::= ('*****' '**(**' *lambda-expression* '**)**' ) |
                    ( '**(**' *typename* '**)**' ) |
                    '*****'

  ``name`` is any valid C++ identifier. ``default-value`` is any valid
  C++ expression. ``typename`` is the name of a type.
  ``lambda-expression`` is an `MPL lambda expression`_.

.. _`MPL lambda expression`: ../../../mpl/doc/refmanual/lambda-expression.html

:Generated names in enclosing scope:
  * ``boost_param_result_ ## __LINE__ ## name``
  * ``boost_param_params_ ## __LINE__ ## name``
  * ``boost_param_parameters_ ## __LINE__ ## name``
  * ``boost_param_impl ## name``
  * ``boost_param_default_ ## __LINE__ ## name``


Approximate expansion:
  **Where**:

  * ``n`` denotes the *minimum* arity, as determined from ``arguments``.
  * ``m`` denotes the *maximum* arity, as determined from ``arguments``.

  .. parsed-literal::

    template <class T>
    struct boost_param_result\_ ## __LINE__ ## **name**
    {
        typedef **result** type;
    };

    struct boost_param_params\_ ## __LINE__ ## **name**
      : boost::parameter::parameters<
            *list of parameter specifications, based on arguments*
        >
    {};

    typedef boost_param_params\_ ## __LINE__ ## **name** 
      boost_param_parameters\_ ## __LINE__ ## **name**;

    template <class A0, …, class A\ **n**>
    *result type* **name**\ (
        A0 *cv*\ & a0, …, A\ **n** *cv*\ & a\ **n**
      , typename boost_param_parameters\_ ## __LINE__ ## **name**::match<
          A0 *cv*, …, A\ **n** *cv*
        >::type = boost_param_parameters\_ ## __LINE__ ## **name**\ ()
    )
    {
        *… forward to implementation …*
    }

    :vellipsis:`⋮`

    template <class A0, …, class A\ **m**>
    *result type* **name**\ (
        A0 *cv*\ & a0, …, A\ **m** *cv*\ & a\ **m**
      , typename boost_param_parameters\_ ## __LINE__ ## **name**::match<
          A0 *cv*, …, A\ **m** *cv*
        >::type = boost_param_parameters\_ ## __LINE__ ## **name**\ ()
    )
    {
        *… forward to implementation …*
    }

    template <
        class ResultType
      , class *argument name*\ **0** ## _type
        …
      , class *argument name*\ **m** ## _type
    >
    ResultType boost_param_default\_ ## __LINE__ ## **name**\ (
        (ResultType(*)())
      , *argument name*\ **0** ## _type& *argument name*\ **0**
        …
      , *argument name*\ **m** ## _type& *argument name*\ **m**
    )



``BOOST_PARAMETER_MEMBER_FUNCTION(result,name,tag_namespace,arguments)``
------------------------------------------------------------------------

:Defined in: `boost/parameter/preprocessor.hpp`__

__ ../../../../boost/parameter/preprocessor.hpp

See ``BOOST_PARAMETER_FUNCTION(result,name,tag_namespace,arguments)``



``BOOST_PARAMETER_CONSTRUCTOR(cls, impl, tag_namespace, arguments)``
--------------------------------------------------------------------

:Defined in: `boost/parameter/preprocessor.hpp`__

__ ../../../../boost/parameter/preprocessor.hpp

:Requires: ``cls`` is the name of this class. ``impl`` is the 
  parenthesized implementation base class for ``cls``.
  ``tag_namespace`` is the namespace in which the keywords 
  used by the function resides. ``arguments`` is
  a list of *argument specifiers*, as defined in 
  ``BOOST_PARAMETER_FUNCTION(result,name,tag_namespace,arguments)``.

:Generated names in enclosing scope:
  * ``boost_param_params_ ## __LINE__ ## ctor``
  * ``constructor_parameters ## __LINE__``

Approximate expansion:
  **Where**:

  * ``n`` denotes the *minimum* arity, as determined from ``arguments``.
  * ``m`` denotes the *maximum* arity, as determined from ``arguments``.

  .. parsed-literal::

    struct boost_param_params\_ ## __LINE__ ## ctor
      : boost::parameter::parameters<
            *list of parameter specifications, based on arguments*
        >
    {};

    typedef boost_param_params\_ ## __LINE__ ## **name** 
      constructor_parameters ## __LINE__;

    template <class A0, …, class A\ **n**>
    *cls*\ (A0 const& a0, …, A\ **n** const& a\ **n**)
      : *impl*\ (constructor_parameters ## __LINE__(a0, …, a\ **n**))
    {}

    :vellipsis:`⋮`

    template <class A0, …, class A\ **m**>
    *cls*\ (A0 const& a0, …, A\ **n** const& a\ **m**)
      : *impl*\ (constructor_parameters ## __LINE__(a0, …, a\ **m**))
    {}


``BOOST_PARAMETER_NAME(name)``
------------------------------

Declares a tag-type and keyword object.

Expands to:

**If** *name* is of the form:

.. parsed-literal::

  (*tag-name*, *namespace-name*) *object-name*

**then**

.. parsed-literal::

  namespace *namespace-name* 
  {
    struct *tag-name*
    {
        static char const* keyword_name()
        {
            return ##\ *tag-name*;
        }

        typedef *unspecified* _;
        typedef *unspecified* _1;
    };
  }

  ::boost::parameter::keyword<*tag-namespace*\ ::\ *tag-name*\ > const& *object-name*
      = ::boost::parameter::keyword<*tag-namespace*\ ::\ *tag-name*\ >::instance;

**Else**

.. parsed-literal::

  namespace tag
  {
    struct *name*
    {
        static char const* keyword_name()
        {
            return ##\ *name*;
        }

        typedef *unspecified* _;
        typedef *unspecified* _1;
    };
  }

  ::boost::parameter::keyword<tag::\ *name*\ > const& _\ *name*
      = ::boost::parameter::keyword<tag::\ *name*\ >::instance;


``BOOST_PARAMETER_TEMPLATE_KEYWORD(name)``
------------------------------------------

Expands to:

.. parsed-literal::

  namespace tag
  {
    struct *name*;
  }

  template <class T>
  struct *name* 
    : ::boost::parameter::template_keyword<tag::\ *name*, T>
  {};


``BOOST_PARAMETER_FUN(r,n,l,h,p)``
----------------------------------

.. admonition:: Deprecated

  This macro has been deprecated in favor of
  ``BOOST_PARAMETER_FUNCTION``.

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)``
--------------------------------

.. admonition:: Deprecated

  This macro has been deprecated in favor of
  ``BOOST_PARAMETER_NAME``.

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