Date: 2005-07-17

# The Boost Parameter Library Reference Documentation

Authors: | David Abrahams Daniel Wallin
Contact: | dave@boost-consulting.com, daniel@boostpro.com
Organization: | BoostPro Computing
Date: | 2005-07-17
Copyright: | Copyright David Abrahams, Daniel Wallin 2005-2009. 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)

Contents

# 1 Preliminaries

This section covers some basic information you'll need to know in order to understand this reference

## 1.1 Namespaces

In this document, all unqualified identifiers should be assumed to be defined in namespace `boost::parameter` unless otherwise specified.

## 1.2 Exceptions

No operation described in this document throws an exception unless otherwise specified.

## 1.3 Thread Safety

All components of this library can be used safely from multiple threads without synchronization.1

## 1.4 Typography

Names written in 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`.

# 2 Terminology

keyword
  The name of a function parameter.

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 argument
  An argument passed with no explicit keyword. Its parameter is determined in the usual C++ way: by position with respect to a parameter list.

tag type
  Shorthand for “keyword tag type.”

keyword object
  An instance of `keyword` `<T>` for some tag type `T`.

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
  A tagged reference whose value represents the value of a default argument.

tagged lazy default
  A tagged reference whose value, when invoked with no arguments, computes a default argument value.

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.

# 3 Concepts

This section describes the generic type concepts used by the Parameter library.

## 3.1 ArgumentPack

An ArgumentPack is a collection of tagged references to the actual arguments passed to a function. Every ArgumentPack is also a valid MPL Forward Sequence consisting of the keyword tag types in its tagged references.

### 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.

ArgumentPack requirements
Expression | Type | Requirements | Semantics/Notes
--- | --- | --- | ---
`x[u]` | `binding<A,K>::type` | `x` contains an element b whose keyword is `K` | Returns b's value (by reference).
`x[u]` | `binding<A,L,D>::type` | none | If `x` contains an element b whose keyword 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 keyword 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`.

## 3.2 ParameterSpec

A ParameterSpec describes the type requirements for arguments corresponding to a given keyword 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,

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

ParameterSpec allowed forms and conditions of satisfaction
Type | `A` required | Condition `A` must satisfy
--- | --- | ---
`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.

# 4 Class Templates

## 4.1 `keyword`

The type of every keyword object is a specialization of `keyword`.

Defined in: | boost/parameter/keyword.hpp

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

      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 keyword `Tag`

`operator|`

      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 keyword `Tag`.

`operator||`

      template <class F> tagged lazy default operator||(F const& g) const;

  Requires: | `g()` is valid, with type `boost::``result_of``<F()>::type`.2
  Returns: | a tagged lazy default with value `g` and keyword `Tag`.

`get`

      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.

## 4.2 `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`.

Defined in: | boost/parameter/parameters.hpp

    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& a0) const;

        template <class A0, class A1>
        ArgumentPack operator()(A0& a0, A1& a1) const;

        ⋮

        template <class A0, class A1, …class Aβ>
        ArgumentPack operator()(A0& a0, A1& a1, …Aβ& 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:

> let `D0` the set [d0, …, dj] of all deduced parameter specs in [`P0`, …, `P`β]
> `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
> if some `A`j where j≤i is a result type of `keyword<T>::``operator=`
> or some `P`j in j≤i is deduced
> then
> if some parameter spec `d`j in `D`i matches `A`i
> then
> `K`i is `d`j's keyword tag type.
> `D`i+1 is `D`i - [`d`j]
> else
> `K`i is `P`i's keyword tag type.

`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 keyword tag type
  - 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()`

      template <class A0> ArgumentPack operator()(A0 const& a0) const;

      ⋮

      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 keyword `K`i and value `a`i

## 4.3 `optional`, `required`

These templates describe the requirements on a function parameter.

Defined in: | boost/parameter/parameters.hpp

Specializations model:
| ParameterSpec

    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.

## 4.4 `deduced`

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

Defined in: | boost/parameter/parameters.hpp

    template <class Tag>
    struct deduced;

# 5 Metafunctions

A Metafunction is conceptually a function that operates on, and returns, C++ types.

## 5.1 `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

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

## 5.2 `lazy_binding`

Returns the result type of indexing an argument pack with a tagged lazy default.

Defined in: | boost/parameter/binding.hpp

    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`.2

## 5.3 `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

    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.

# 6 Code Generation Macros

Macros in this section can be used to ease the writing of code using the Parameter libray by eliminating repetitive boilerplate.

## 6.1 `BOOST_PARAMETER_FUNCTION(result,name,tag_namespace,arguments)`

Defined in: | 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:
    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.

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

      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 An>
      result type name(
          A0 cv& a0, …, An cv& an
        , typename boost_param_parameters_ ## __LINE__ ## name::match<
            A0 cv, …, An cv
          >::type = boost_param_parameters_ ## __LINE__ ## name()
      )
      {
          … forward to implementation …
      }

      ⋮

      template <class A0, …, class Am>
      result type name(
          A0 cv& a0, …, Am cv& am
        , typename boost_param_parameters_ ## __LINE__ ## name::match<
            A0 cv, …, Am cv
          >::type = boost_param_parameters_ ## __LINE__ ## name()
      )
      {
          … forward to implementation …
      }

      template <
          class ResultType
        , class argument name0 ## _type
          …
        , class argument namem ## _type
      >
      ResultType boost_param_default_ ## __LINE__ ## name(
          (ResultType(*)())
        , argument name0 ## _type& argument name0
          …
        , argument namem ## _type& argument namem
      )

## 6.2 `BOOST_PARAMETER_MEMBER_FUNCTION(result,name,tag_namespace,arguments)`

Defined in: | boost/parameter/preprocessor.hpp

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

## 6.3 `BOOST_PARAMETER_CONSTRUCTOR(cls, impl, tag_namespace, arguments)`

Defined in: | 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`.

      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 An>
      cls(A0 const& a0, …, An const& an)
        : impl(constructor_parameters ## __LINE__(a0, …, an))
      {}

      ⋮

      template <class A0, …, class Am>
      cls(A0 const& a0, …, An const& am)
        : impl(constructor_parameters ## __LINE__(a0, …, am))
      {}

## 6.4 `BOOST_PARAMETER_NAME(name)`

Declares a tag-type and keyword object.

Expands to:

If name is of the form:

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

then

    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

    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;

## 6.5 `BOOST_PARAMETER_TEMPLATE_KEYWORD(name)`

Expands to:

    namespace tag
    {
      struct name;
    }

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

## 6.6 `BOOST_PARAMETER_FUN(r,n,l,h,p)`

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

Requires: | `l` and `h` are nonnegative integer tokens such that `l` < `h`

Generates

      template <class A1, class A2, …class A##l>
      r name(
          A1 const& a1, A2 const& a2, …Al const& xl
        , typename p::match<A1,A2,…Al>::type p = p())
      {
         return name_with_named_params(p(x1,x2,…xl));
      }

      template <class A1, class A2, …class Al, class A##BOOST_PP_INC(l)>
      r name(
          A1 const& a1, A2 const& a2, …Al const& xl
        , A##BOOST_PP_INC(l) const& x##BOOST_PP_INC(l)
        , typename p::match<A1,A2,…Al,A##BOOST_PP_INC(l)>::type p = p())
      {
         return name_with_named_params(p(x1,x2,…xl,x##BOOST_PP_INC(l)));
      }

      ⋮

      template <class A1, class A2, …class Ah>
      r name(
          A1 const& a1, A2 const& a2, …Ah const& xh
        , typename p::match<A1,A2,…Ah>::type p = p())
      {
         return name_with_named_params(p(a1,a2,…ah));
      }

## 6.7 `BOOST_PARAMETER_KEYWORD(n,k)`

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

Generates

      namespace n { struct k; }
      namespace {
        boost::parameter::keyword<tag-namespace::k>& k
        = boost::parameter::keyword<tag-namespace::k>::get();
      }

## 6.8 `BOOST_PARAMETER_MATCH(p,a,x)`

Generates a defaulted parameter declaration for a forwarding function.

Defined in: | boost/parameter/match.hpp

Requires: | `a` is a Boost.Preprocessor sequence of the form
    (A0)(A1)…(An)

Generates

      typename p::match<A0,A1…,An>::type x = p()

# 7 Configuration Macros

## 7.1 `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`.

Defined in: | boost/parameter/config.hpp

Default Value: | `8`

# 8 Tutorial

Follow this link to the Boost.Parameter tutorial documentation.

[1] | 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.

[2] | (1, 2) Where `BOOST_NO_RESULT_OF` is `#defined`, `boost::``result_of``<F()>::type` is replaced by `F::result_type`.