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

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.

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

The information in a ParameterSpec is used to limit the arguments that will be matched by forwarding functions.

4.1   keyword

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

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.

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;
};

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:

• Pj is the unspecified default
• or, Pj is a keyword tag type
• or, Pj is optional <X,F> and either
  • X is not Ki for any i,
  • or X is some Ki and mpl::apply<F,Ri>::type::value is true
• or, Pj is required <X,F>, and
  • X is some Ki, and
  • mpl::apply<F,Ri>::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 ai, if ai, is a single-element ArgumentPack, its element Otherwise, a tagged reference with keyword Ki and value ai

4.3   optional, required

These templates describe the requirements on a function parameter.

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.

template <class Tag>
struct deduced;

5.1   binding

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

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

5.2   lazy_binding

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

template <class A, class K, class F>
struct lazy_binding
{
    typedef … type;
};

5.3   value_type

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

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

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

6.1   BOOST_PARAMETER_FUNCTION(result,name,tag_namespace,arguments)

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 ')' ) |
                '*'

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)

See BOOST_PARAMETER_FUNCTION(result,name,tag_namespace,arguments)

6.3   BOOST_PARAMETER_CONSTRUCTOR(cls, impl, tag_namespace, arguments)

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 implementation defined _;
      typedef implementation defined _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 implementation defined _;
      typedef implementation defined _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)

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.

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)

Generates the declaration of a keyword tag type named k in namespace n, and a corresponding keyword object definition in the enclosing namespace.

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.

(A0)(A1)…(An)

Generates

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

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.