Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. — Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.

The Boost Parameter Library

Boost

Abstract:Use this library to write functions and class templates that can accept arguments by name: 
new_window(
    "alert"
  , _width=10
  , _titlebar=false
);

smart_ptr<
    Foo
  , deleter<Deallocate<Foo> >
  , copy_policy<DeepCopy>
> p(new Foo);

Since named arguments can be passed in any order, they are especially useful when a function or template has more than one parameter with a useful default value. The library also supports deduced parameters: that is to say, parameters whose identity can be deduced from their types.

Authors:David Abrahams, Daniel Wallin
Contact:dave@boost-consulting.com, daniel@boostpro.com
organization:BoostPro Computing
date:$Date: 2005/07/17 19:53:01 $
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)

[Note: this tutorial does not cover all details of the library. Please see also the reference documentation]

Table of Contents

1   Motivation

In C++, arguments are normally given meaning by their positions with respect to a parameter list: the first argument passed maps onto the first parameter in a function's definition, and so on. That protocol is fine when there is at most one parameter with a default value, but when there are even a few useful defaults, the positional interface becomes burdensome:

1.1   Named Function Parameters

This library addresses the problems outlined above by associating each parameter name with a keyword object. Now users can identify arguments by name, rather than by position:

window* w = new_window(
    "alert box"
  , movable_=false
); // OK!

1.2   Deduced Function Parameters

A deduced parameter can be passed in any position without supplying an explicit parameter name. It's not uncommon for a function to have parameters that can be uniquely identified based on the types of arguments passed. The name parameter to new_window is one such example. None of the other arguments, if valid, can reasonably be converted to a char const*. With a deduced parameter interface, we could pass the window name in any argument position without causing ambiguity:

window* w = new_window(
    movable_=false
  , "alert box"
); // OK!
window* w = new_window(
    "alert box"
  , movable_=false
); // OK!

Appropriately used, a deduced parameter interface can free the user of the burden of even remembering the formal parameter names.

1.3   Class Template Parameter Support

The reasoning we've given for named and deduced parameter interfaces applies equally well to class templates as it does to functions. Using the Parameter library, we can create interfaces that allow template arguments (in this case shared and Client) to be explicitly named, like this:

smart_ptr<
    ownership<shared>
  , value_type<Client>
> p;

The syntax for passing named template arguments is not quite as natural as it is for function arguments (ideally, we'd be able to write smart_ptr<ownership = shared, …>). This small syntactic deficiency makes deduced parameters an especially big win when used with class templates:

// p and q could be equivalent, given a deduced
// parameter interface.
smart_ptr<shared, Client> p;
smart_ptr<Client, shared> q;

2   Tutorial

This tutorial shows all the basics—how to build both named- and deduced-parameter interfaces to function templates and class templates—and several more advanced idioms as well.

2.1   Parameter-Enabled Functions

In this section we'll show how the Parameter library can be used to build an expressive interface to the Boost Graph library's depth_first_search algorithm.1

2.1.1   Headers And Namespaces

Most components of the Parameter library are declared in a header named for the component. For example,

#include <boost/parameter/keyword.hpp>

will ensure boost::parameter::keyword is known to the compiler. There is also a combined header, boost/parameter.hpp, that includes most of the library's components. For the the rest of this tutorial, unless we say otherwise, you can use the rule above to figure out which header to #include to access any given component of the library.

Also, the examples below will also be written as if the namespace alias

namespace parameter = boost::parameter;

has been declared: we'll write parameter::xxx instead of boost::parameter::xxx.

2.1.2   The Abstract Interface to depth_first_search

The Graph library's depth_first_search algorithm is a generic function accepting from one to four arguments by reference. If all arguments were required, its signature might be as follows:

template <
    typename Graph
  , typename DFSVisitor
  , typename Index
  , typename ColorMap
>
void
    depth_first_search(
        Graph const& graph
      , DFSVisitor visitor
      , typename graph_traits<g>::vertex_descriptor root_vertex
      , IndexMap index_map
      , ColorMap& color
    );

However, most of the parameters have a useful default value, as shown in the table below.

depth_first_search Parameters
Parameter Name Data Flow Type Default Value (if any)
graph in Model of Incidence Graph and Vertex List Graph none - this argument is required.
visitor in Model of DFS Visitor boost::dfs_visitor<>()
root_vertex in graph's vertex descriptor type. *vertices(graph).first
index_map in Model of Readable Property Map with key type := graph's vertex descriptor and value type an integer type. get(boost::vertex_index,graph)
color_map in / out Model of Read/Write Property Map with key type := graph's vertex descriptor type. a boost::iterator_property_map created from a std::vector of default_color_type of size num_vertices(graph) and using index_map for the index map.

Don't be intimidated by the information in the second and third columns above. For the purposes of this exercise, you don't need to understand them in detail.

2.1.3   Defining the Keywords

The point of this exercise is to make it possible to call depth_first_search with named arguments, leaving out any arguments for which the default is appropriate:

graphs::depth_first_search(g, color_map_=my_color_map);

To make that syntax legal, there needs to be an object called “color_map_” whose assignment operator can accept a my_color_map argument. In this step we'll create one such keyword object for each parameter. Each keyword object will be identified by a unique keyword tag type.

We're going to define our interface in namespace graphs. The library provides a convenient macro for defining keyword objects:

#include <boost/parameter/name.hpp>

namespace graphs {

    BOOST_PARAMETER_NAME(graph)    // Note: no semicolon
    BOOST_PARAMETER_NAME(visitor)
    BOOST_PARAMETER_NAME(root_vertex)
    BOOST_PARAMETER_NAME(index_map)
    BOOST_PARAMETER_NAME(color_map)
}

The declaration of the graph keyword you see here is equivalent to:

namespace graphs {
    namespace tag {

        // keyword tag type
        struct graph
        {
            typedef boost::parameter::forward_reference qualifier;
        };
    }

    namespace // unnamed
    {
        // A reference to the keyword object
        boost::parameter::keyword<tag::graph> const& _graph
            = boost::parameter::keyword<tag::graph>::instance;
    }
}

It defines a keyword tag type named tag::graph and a keyword object reference named _graph.

This “fancy dance” involving an unnamed namespace and references is all done to avoid violating the One Definition Rule (ODR)2 when the named parameter interface is used by function templates that are instantiated in multiple translation units (MSVC6.x users see this note).

2.1.4   Writing the Function

Now that we have our keywords defined, the function template definition follows a simple pattern using the BOOST_PARAMETER_FUNCTION macro:

#include <boost/parameter/preprocessor.hpp>

namespace graphs {

    BOOST_PARAMETER_FUNCTION(
        (void),                 // 1. parenthesized return type
        depth_first_search,     // 2. name of the function template
        tag,                    // 3. namespace of tag types
        (required (graph, *) )  // 4. one required parameter, and
        (optional               //    four optional parameters,
                                //    with defaults
            (visitor,     *, boost::dfs_visitor<>())
            (root_vertex, *, *vertices(graph).first)
            (index_map,   *, get(boost::vertex_index,graph))
            (color_map,   *,
                default_color_map(num_vertices(graph), index_map)
            )
        )
    )
    {
        // ... body of function goes here...
        // use graph, visitor, index_map, and color_map
    }
}

The arguments to BOOST_PARAMETER_FUNCTION are:

  1. The return type of the resulting function template. Parentheses around the return type prevent any commas it might contain from confusing the preprocessor, and are always required.
  2. The name of the resulting function template.
  3. The name of a namespace where we can find tag types whose names match the function's parameter names.
  4. The function signature.

2.1.5   Function Signatures

Function signatures are described as one or two adjacent parenthesized terms (a Boost.Preprocessor sequence) describing the function's parameters in the order in which they'd be expected if passed positionally. Any required parameters must come first, but the (required … ) clause can be omitted when all the parameters are optional.

2.1.5.1   Required Parameters

Required parameters are given first—nested in a (required … ) clause—as a series of two-element tuples describing each parameter name and any requirements on the argument type. In this case there is only a single required parameter, so there's just a single tuple:

(required (graph, *) )

Since depth_first_search doesn't require any particular type for its graph parameter, we use an asterix to indicate that any type is allowed. Required parameters must always precede any optional parameters in a signature, but if there are no required parameters, the (required … ) clause can be omitted entirely.

2.1.5.2   Optional Parameters

Optional parameters—nested in an (optional … ) clause—are given as a series of adjacent three-element tuples describing the parameter name, any requirements on the argument type, and and an expression representing the parameter's default value:

(optional
    (visitor,     *, boost::dfs_visitor<>())
    (root_vertex, *, *vertices(graph).first)
    (index_map,   *, get(boost::vertex_index,graph))
    (color_map,   *,
        default_color_map(num_vertices(graph), index_map)
    )
)

2.1.5.3   Handling “In”, “Out”, “Consume / Move-From”, and “Forward” Parameters

By default, Boost.Parameter treats all parameters as if they were forward parameters, which functions would take in by rvalue reference and only std::forward or boost::forward to other functions. Such parameters can be const lvalues, mutable lvalues, const rvalues, or mutable rvalues. Therefore, the default configuration grants the most flexibility to user code. However:

  • Users can configure one or more parameters to be in parameters, which can fall into the same categories as forward parameters but are now passed by const lvalue reference and so must only be read from. Continuing from the previous example, to indicate that root_vertex and index_map are read-only, we wrap their names in in(…).
  • Users can configure one or more parameters to be either out parameters, which functions would strictly write to, or in-out parameters, which functions would both read from and write to. Such parameters can only be mutable lvalues. In the example, to indicate that color_map is read-write, we wrap its name in in_out(…). Note that Boost.Parameter sees no functional difference between out(…) and in_out(…), so you may choose whichever makes your interfaces more self-documenting.
  • Users can configure one or more parameters to be consume or move-from parameters, which functions would take in by mutable rvalue reference and std::move or boost::move as the last access step. Such parameters can only be mutable rvalues. Boost.Parameter supports wrapping the corresponding names in consume(…) or move_from(…).
BOOST_PARAMETER_NAME(graph)
BOOST_PARAMETER_NAME(visitor)
BOOST_PARAMETER_NAME(in(root_vertex))
BOOST_PARAMETER_NAME(in(index_map))
BOOST_PARAMETER_NAME(in_out(color_map))

In order to see what happens when parameters are bound to arguments that violate their category constraints, attempt to compile the compose.cpp test program with either the LIBS_PARAMETER_TEST_COMPILE_FAILURE_0 macro or the LIBS_PARAMETER_TEST_COMPILE_FAILURE_1 macro #defined. You should encounter a compiler error caused by a specific constraint violation.

2.1.5.4   Positional Arguments

When arguments are passed positionally (without the use of keywords), they will be mapped onto parameters in the order the parameters are given in the signature, so for example in this call

graphs::depth_first_search(x, y);

x will always be interpreted as a graph and y will always be interpreted as a visitor.

2.1.5.5   Default Expression Evaluation

Note that in our example, the value of the graph parameter is used in the default expressions for root_vertex, index_map, and color_map.

(required (graph, *) )
(optional
    (visitor,     *, boost::dfs_visitor<>())
    (root_vertex, *, *vertices(graph).first)
    (index_map,   *, get(boost::vertex_index, graph))
    (color_map,   *,
        default_color_map(num_vertices(graph), index_map)
    )
)

A default expression is never evaluated—or even instantiated—if an actual argument is passed for that parameter. We can actually demonstrate that with our code so far by replacing the body of depth_first_search with something that prints the arguments:

#include <boost/graph/depth_first_search.hpp>  // for dfs_visitor

BOOST_PARAMETER_FUNCTION(
    (bool), depth_first_search, tag
    …signature goes here…
)
{
    std::cout << "graph=" << graph;
    std::cout << std::endl;
    std::cout << "visitor=" << visitor;
    std::cout << std::endl;
    std::cout << "root_vertex=" << root_vertex;
    std::cout << std::endl;
    std::cout << "index_map=" << index_map;
    std::cout << std::endl;
    std::cout << "color_map=" << color_map;
    std::cout << std::endl;
    return true;
}

#include <boost/core/lightweight_test.hpp>

int main()
{
    char const* g = "1";
    depth_first_search(1, 2, 3, 4, 5);
    depth_first_search(
        g, '2', _color_map = '5',
        _index_map = "4", _root_vertex = "3"
    );
    return boost::report_errors();
}

Despite the fact that default expressions such as vertices(graph).first are ill-formed for the given graph arguments, both calls will compile, and each one will print exactly the same thing.

2.1.5.6   Signature Matching and Overloading

In fact, the function signature is so general that any call to depth_first_search with fewer than five arguments will match our function, provided we pass something for the required graph parameter. That might not seem to be a problem at first; after all, if the arguments don't match the requirements imposed by the implementation of depth_first_search, a compilation error will occur later, when its body is instantiated.

There are at least three problems with very general function signatures.

  1. By the time our depth_first_search is instantiated, it has been selected as the best matching overload. Some other depth_first_search overload might've worked had it been chosen instead. By the time we see a compilation error, there's no chance to change that decision.
  2. Even if there are no overloads, error messages generated at instantiation time usually expose users to confusing implementation details. For example, users might see references to names generated by BOOST_PARAMETER_FUNCTION such as graphs::detail::depth_first_search_with_named_params (or worse—think of the kinds of errors you get from your STL implementation when you make a mistake).4
  3. The problems with exposing such permissive function template signatures have been the subject of much discussion, especially in the presence of unqualified calls. If all we want is to avoid unintentional argument-dependent lookup (ADL), we can isolate depth_first_search in a namespace containing no types6, but suppose we want it to found via ADL?

It's usually a good idea to prevent functions from being considered for overload resolution when the passed argument types aren't appropriate. The library already does this when the required graph parameter is not supplied, but we're not likely to see a depth first search that doesn't take a graph to operate on. Suppose, instead, that we found a different depth first search algorithm that could work on graphs that don't model Incidence Graph? If we just added a simple overload, it would be ambiguous:

// new overload
BOOST_PARAMETER_FUNCTION((void), depth_first_search, (tag),
    (required (graph,*))( … )
)
{
    // new algorithm implementation
}

…

// ambiguous!
depth_first_search(boost::adjacency_list<>(), 2, "hello");
2.1.5.6.1   Predicate Requirements

We really don't want the compiler to consider the original version of depth_first_search because the root_vertex argument, "hello", doesn't meet the requirement that it match the graph parameter's vertex descriptor type. Instead, this call should just invoke our new overload. To take the original depth_first_search overload out of contention, we first encode this requirement as follows:

struct vertex_descriptor_predicate
{
    template <typename T, typename Args>
    struct apply
      : boost::mpl::if_<
            boost::is_convertible<
                T
              , typename boost::graph_traits<
                    typename boost::parameter::value_type<
                        Args
                      , graphs::graph
                    >::type
                >::vertex_descriptor
            >
          , boost::mpl::true_
          , boost::mpl::false_
        >
    {
    };
};

This encoding is an MPL Binary Metafunction Class, a type with a nested apply metafunction that takes in two template arguments. For the first template argument, Boost.Parameter will pass in the type on which we will impose the requirement. For the second template argument, Boost.Parameter will pass in the entire argument pack, making it possible to extract the type of each of the other depth_first_search parameters via the value_type metafunction and the corresponding keyword tag type. The result type of the apply metafunction will be equivalent to boost::mpl::true_ if T fulfills our requirement as imposed by the boost::is_convertible statement; otherwise, the result will be equivalent to boost::mpl::false_.

At this point, we can append the name of our metafunction class, in parentheses, to the appropriate * element of the function signature.

(root_vertex
  , *(vertex_descriptor_predicate)
  , *vertices(graph).first
)

Now the original depth_first_search will only be called when the root_vertex argument can be converted to the graph's vertex descriptor type, and our example that was ambiguous will smoothly call the new overload.

We can encode the requirements on other arguments using the same concept; only the implementation of the nested apply metafunction needs to be tweaked for each argument. There's no space to give a complete description of graph library details here, but suffice it to show that the next few metafunction classes provide the necessary checks.

struct graph_predicate
{
    template <typename T, typename Args>
    struct apply
      : boost::mpl::eval_if<
            boost::is_convertible<
                typename boost::graph_traits<T>::traversal_category
              , boost::incidence_graph_tag
            >
          , boost::mpl::if_<
                boost::is_convertible<
                    typename boost::graph_traits<T>::traversal_category
                  , boost::vertex_list_graph_tag
                >
              , boost::mpl::true_
              , boost::mpl::false_
            >
        >
    {
    };
};

struct index_map_predicate
{
    template <typename T, typename Args>
    struct apply
      : boost::mpl::eval_if<
            boost::is_integral<
                typename boost::property_traits<T>::value_type
            >
          , boost::mpl::if_<
                boost::is_same<
                    typename boost::property_traits<T>::key_type
                  , typename boost::graph_traits<
                        typename boost::parameter::value_type<
                            Args
                          , graphs::graph
                        >::type
                    >::vertex_descriptor
                >
              , boost::mpl::true_
              , boost::mpl::false_
            >
        >
    {
    };
};

struct color_map_predicate
{
    template <typename T, typename Args>
    struct apply
      : boost::mpl::if_<
            boost::is_same<
                typename boost::property_traits<T>::key_type
              , typename boost::graph_traits<
                    typename boost::parameter::value_type<
                        Args
                      , graphs::graph
                    >::type
                >::vertex_descriptor
            >
          , boost::mpl::true_
          , boost::mpl::false_
        >
    {
    };
};

Likewise, computing the default value for the color_map parameter is no trivial matter, so it's best to factor the computation out to a separate function template.

template <typename Size, typename IndexMap>
boost::iterator_property_map<
    std::vector<boost::default_color_type>::iterator
  , IndexMap
  , boost::default_color_type
  , boost::default_color_type&
>&
    default_color_map(Size num_vertices, IndexMap const& index_map)
{
    static std::vector<boost::default_color_type> colors(num_vertices);
    static boost::iterator_property_map<
        std::vector<boost::default_color_type>::iterator
      , IndexMap
      , boost::default_color_type
      , boost::default_color_type&
    > m(colors.begin(), index_map);
    return m;
}

The signature encloses each predicate metafunction in parentheses preceded by an asterix, as follows:

BOOST_PARAMETER_FUNCTION((void), depth_first_search, graphs,
(required
    (graph, *(graph_predicate))
)
(optional
    (visitor
      , *  // not easily checkable
      , boost::dfs_visitor<>()
    )
    (root_vertex
      , (vertex_descriptor_predicate)
      , *vertices(graph).first
    )
    (index_map
      , *(index_map_predicate)
      , get(boost::vertex_index, graph)
    )
    (color_map
      , *(color_map_predicate)
      , default_color_map(num_vertices(graph), index_map)
    )
)
)

It usually isn't necessary to so completely encode the type requirements on arguments to generic functions. However, doing so is worth the effort: your code will be more self-documenting and will often provide a better user experience. You'll also have an easier transition to the C++20 standard with language support for constraints and concepts.

2.1.5.6.2   More on Type Requirements

Encoding type requirements onto a function's parameters is essential for enabling the function to have deduced parameter interface. Let's revisit the new_window example for a moment:

window* w = new_window(
    movable_=false
  , "alert box"
);
window* w = new_window(
    "alert box"
  , movable_=false
);

The goal this time is to be able to invoke the new_window function without specifying the keywords. For each parameter that has a required type, we can enclose that type in parentheses, then replace the * element of the parameter signature:

BOOST_PARAMETER_NAME((name_, keywords) name)
BOOST_PARAMETER_NAME((movable_, keywords) movable)

BOOST_PARAMETER_FUNCTION((window*), new_window, keywords,
    (deduced
        (required
            (name, (char const*))
            (movable, (bool))
        )
    )
)
{
    // ...
}

The following statements will now work and are equivalent to each other as well as the previous statements:

window* w = new_window(false, "alert box");
window* w = new_window("alert box", false);

2.1.5.7   Deduced Parameters

To further illustrate deduced parameter support, consider the example of the def function from Boost.Python. Its signature is roughly as follows:

template <
    typename Function
  , typename KeywordExpression
  , typename CallPolicies
>
void def(
    // Required parameters
    char const* name, Function func

    // Optional, deduced parameters
  , char const* docstring = ""
  , KeywordExpression keywords = no_keywords()
  , CallPolicies policies = default_call_policies()
);

Try not to be too distracted by the use of the term “keywords” in this example: although it means something analogous in Boost.Python to what it means in the Parameter library, for the purposes of this exercise you can think of it as being completely different.

When calling def, only two arguments are required. The association between any additional arguments and their parameters can be determined by the types of the arguments actually passed, so the caller is neither required to remember argument positions or explicitly specify parameter names for those arguments. To generate this interface using BOOST_PARAMETER_FUNCTION, we need only enclose the deduced parameters in a (deduced …) clause, as follows:

char const*& blank_char_ptr()
{
    static char const* larr = "";
    return larr;
}

BOOST_PARAMETER_FUNCTION(
    (bool), def, tag,

    (required (name, (char const*)) (func,*) )  // nondeduced

    (deduced
        (optional
            (docstring, (char const*), "")

            (keywords
                // see5
              , *(is_keyword_expression<boost::mpl::_>)
              , no_keywords()
            )

            (policies
              , *(
                    boost::mpl::eval_if<
                        boost::is_convertible<boost::mpl::_,char const*>
                      , boost::mpl::false_
                      , boost::mpl::if_<
                            // see5
                            is_keyword_expression<boost::mpl::_>
                          , boost::mpl::false_
                          , boost::mpl::true_
                        >
                    >
                )
              , default_call_policies()
            )
        )
    )
)
{
    …
}

Syntax Note

A (deduced …) clause always contains a (required …) and/or an (optional …) subclause, and must follow any (required …) or (optional …) clauses indicating nondeduced parameters at the outer level.

With the declaration above, the following two calls are equivalent:

char const* f_name = "f";
def(
    f_name
  , &f
  , some_policies
  , "Documentation for f"
);
def(
    f_name
  , &f
  , "Documentation for f"
  , some_policies
);

If the user wants to pass a policies argument that was also, for some reason, convertible to char const*, she can always specify the parameter name explicitly, as follows:

def(
    f_name
  , &f
  , _policies = some_policies
  , "Documentation for f"
);

The deduced.cpp and deduced_dependent_predicate.cpp test programs demonstrate additional usage of deduced parameter support.

2.1.5.8   Parameter-Dependent Return Types

For some algorithms, the return type depends on at least one of the argument types. However, there is one gotcha to avoid when encoding this return type while using BOOST_PARAMETER_FUNCTION or other code generation macros. As an example, given the following definitions:

BOOST_PARAMETER_NAME(x)
BOOST_PARAMETER_NAME(y)
BOOST_PARAMETER_NAME(z)

Let our algorithm simply return one of its arguments. If we naïvely implement its return type in terms of parameter::value_type:

BOOST_PARAMETER_FUNCTION(
    (typename parameter::value_type<Args,tag::y>::type), return_y, tag,
    (deduced
        (required
            (x, (std::map<char const*,std::string>))
            (y, (char const*))
        )
        (optional
            (z, (int), 4)
        )
    )
)
{
    return y;
}

Then using return_y in any manner other than with positional arguments will result in a compiler error:

std::map<char const*,std::string> k2s;
assert("foo" == return_y(2, k2s, "foo"));  // error!

The problem is that even though y is a required parameter, BOOST_PARAMETER_FUNCTION will generate certain overloads for which the argument pack type Args does not actually contain the keyword tag type tag::y. The solution is to use SFINAE to preclude generation of those overloads. Since parameter::value_type is a metafunction, our tool for the job is lazy_enable_if:

BOOST_PARAMETER_FUNCTION(
    (
        // Whenever using 'enable_if', 'disable_if', and so on,
        // do not add the 'typename' keyword in front.
        boost::lazy_enable_if<
            typename mpl::has_key<Args,tag::y>::type
          , parameter::value_type<Args,tag::y>
        >
        // Whenever using 'enable_if', 'disable_if', and so on,
        // do not add '::type' here.
    ), return_y, tag,
    (deduced
        (required
            (x, (std::map<char const*,std::string>))
            (y, (char const*))
        )
        (optional
            (z, (int), 4)
        )
    )
)
{
    return y;
}

For a working demonstration, see preprocessor_deduced.cpp.

2.2   Parameter-Enabled Member Functions

The BOOST_PARAMETER_MEMBER_FUNCTION and BOOST_PARAMETER_CONST_MEMBER_FUNCTION macros accept exactly the same arguments as BOOST_PARAMETER_FUNCTION, but are designed to be used within the body of a class:

BOOST_PARAMETER_NAME(arg1)
BOOST_PARAMETER_NAME(arg2)

struct callable2
{
    BOOST_PARAMETER_CONST_MEMBER_FUNCTION(
        (void), call, tag, (required (arg1,(int))(arg2,(int)))
    )
    {
        std::cout << arg1 << ", " << arg2;
        std::cout << std::endl;
    }
};

#include <boost/core/lightweight_test.hpp>

int main()
{
    callable2 c2;
    callable2 const& c2_const = c2;
    c2_const.call(1, 2);
    return boost::report_errors();
}

These macros don't directly allow a function's interface to be separated from its implementation, but you can always forward arguments on to a separate implementation function:

struct callable2
{
    BOOST_PARAMETER_CONST_MEMBER_FUNCTION(
        (void), call, tag, (required (arg1,(int))(arg2,(int)))
    )
    {
        call_impl(arg1, arg2);
    }

 private:
    void call_impl(int, int);  // implemented elsewhere.
};

2.2.1   Static Member Functions

To expose a static member function, simply insert the keyword “static” before the function name:

BOOST_PARAMETER_NAME(arg1)

struct somebody
{
    BOOST_PARAMETER_MEMBER_FUNCTION(
        (void), static f, tag, (optional (arg1,(int),0))
    )
    {
        std::cout << arg1 << std::endl;
    }
};

#include <boost/core/lightweight_test.hpp>

int main()
{
    somebody::f();
    somebody::f(4);
    return boost::report_errors();
}

2.3   Parameter-Enabled Function Call Operators

The BOOST_PARAMETER_FUNCTION_CALL_OPERATOR and BOOST_PARAMETER_CONST_FUNCTION_CALL_OPERATOR macros accept the same arguments as the BOOST_PARAMETER_MEMBER_FUNCTION and BOOST_PARAMETER_CONST_MEMBER_FUNCTION macros except for the function name, because these macros allow instances of the enclosing classes to be treated as function objects:

BOOST_PARAMETER_NAME(first_arg)
BOOST_PARAMETER_NAME(second_arg)

struct callable2
{
    BOOST_PARAMETER_CONST_FUNCTION_CALL_OPERATOR(
        (void), tag, (required (first_arg,(int))(second_arg,(int)))
    )
    {
        std::cout << first_arg << ", ";
        std::cout << second_arg << std::endl;
    }
};

#include <boost/core/lightweight_test.hpp>

int main()
{
    callable2 c2;
    callable2 const& c2_const = c2;
    c2_const(1, 2);
    return boost::report_errors();
}

2.4   Parameter-Enabled Constructors

The lack of a “delegating constructor” feature in C++ (http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1986.pdf) limits somewhat the quality of interface this library can provide for defining parameter-enabled constructors. The usual workaround for a lack of constructor delegation applies: one must factor the common logic into one or more base classes.

Let's build a parameter-enabled constructor that simply prints its arguments. The first step is to write a base class whose constructor accepts a single argument known as an ArgumentPack: a bundle of references to the actual arguments, tagged with their keywords. The values of the actual arguments are extracted from the ArgumentPack by indexing it with keyword objects:

BOOST_PARAMETER_NAME(name)
BOOST_PARAMETER_NAME(index)

struct myclass_impl
{
    template <typename ArgumentPack>
    myclass_impl(ArgumentPack const& args)
    {
        std::cout << "name = " << args[_name];
        std::cout << "; index = " << args[_index | 42];
        std::cout << std::endl;
    }
};

Note that the bitwise or (“|”) operator has a special meaning when applied to keyword objects that are passed to an ArgumentPack's indexing operator: it is used to indicate a default value. In this case if there is no index parameter in the ArgumentPack, 42 will be used instead.

Now we are ready to write the parameter-enabled constructor interface:

struct myclass : myclass_impl
{
    BOOST_PARAMETER_CONSTRUCTOR(
        myclass, (myclass_impl), tag
      , (required (name,*)) (optional (index,*))
    ) // no semicolon
};

Since we have supplied a default value for index but not for name, only name is required. We can exercise our new interface as follows:

myclass x("bob", 3);                      // positional
myclass y(_index = 12, _name = "sally");  // named
myclass z("june");                        // positional/defaulted

For more on ArgumentPack manipulation, see the Advanced Topics section.

2.5   Parameter-Enabled Class Templates

In this section we'll use Boost.Parameter to build Boost.Python's class_ template, whose “signature” is:

template <
    ValueType, BaseList = bases<>
  , HeldType = ValueType, Copyable = void
>
class class_;

Only the first argument, ValueType, is required.

2.5.1   Named Template Parameters

First, we'll build an interface that allows users to pass arguments positionally or by name:

struct B
{
    virtual ~B() = 0;
};

struct D : B
{
    ~D();
};

class_<
    class_type<B>
  , copyable<boost::noncopyable>
> …;

class_<
    D
  , held_type<std::auto_ptr<D> >
  , base_list<bases<B> >
> …;

2.5.1.1   Template Keywords

The first step is to define keywords for each template parameter:

namespace boost { namespace python {

    BOOST_PARAMETER_TEMPLATE_KEYWORD(class_type)
    BOOST_PARAMETER_TEMPLATE_KEYWORD(base_list)
    BOOST_PARAMETER_TEMPLATE_KEYWORD(held_type)
    BOOST_PARAMETER_TEMPLATE_KEYWORD(copyable)
}}

The declaration of the class_type keyword you see here is equivalent to:

namespace boost { namespace python {
    namespace tag {

        struct class_type;  // keyword tag type
    }

    template <typename T>
    struct class_type
      : parameter::template_keyword<tag::class_type,T>
    {
    };
}}

It defines a keyword tag type named tag::class_type and a parameter passing template named class_type.

2.5.1.2   Class Template Skeleton

The next step is to define the skeleton of our class template, which has three optional parameters. Because the user may pass arguments in any order, we don't know the actual identities of these parameters, so it would be premature to use descriptive names or write out the actual default values for any of them. Instead, we'll give them generic names and use the special type boost::parameter::void_ as a default:

namespace boost { namespace python {

    template <
        typename A0
      , typename A1 = boost::parameter::void_
      , typename A2 = boost::parameter::void_
      , typename A3 = boost::parameter::void_
    >
    struct class_
    {
        …
    };
}}

2.5.1.3   Class Template Signatures

Next, we need to build a type, known as a ParameterSpec, describing the “signature” of boost::python::class_. A ParameterSpec enumerates the required and optional parameters in their positional order, along with any type requirements (note that it does not specify defaults -- those will be dealt with separately):

namespace boost { namespace python {

    using boost::mpl::_;

    typedef parameter::parameters<
        required<tag::class_type, boost::is_class<_> >
      , parameter::optional<tag::base_list, mpl::is_sequence<_> >
      , parameter::optional<tag::held_type>
      , parameter::optional<tag::copyable>
    > class_signature;
}}

2.5.1.4   Argument Packs and Parameter Extraction

Next, within the body of class_ , we use the ParameterSpec's nested ::bind< … > template to bundle the actual arguments into an ArgumentPack type, and then use the library's value_type< … > metafunction to extract “logical parameters”. value_type< … > is a lot like binding< … >, but no reference is added to the actual argument type. Note that defaults are specified by passing it an optional third argument:

namespace boost { namespace python {

    template <
        typename A0
      , typename A1 = boost::parameter::void_
      , typename A2 = boost::parameter::void_
      , typename A3 = boost::parameter::void_
    >
    struct class_
    {
        // Create ArgumentPack
        typedef typename class_signature::template bind<
            A0, A1, A2, A3
        >::type args;

        // Extract first logical parameter.
        typedef typename parameter::value_type<
            args, tag::class_type
        >::type class_type;

        typedef typename parameter::value_type<
            args, tag::base_list, bases<>
        >::type base_list;

        typedef typename parameter::value_type<
            args, tag::held_type, class_type
        >::type held_type;

        typedef typename parameter::value_type<
            args, tag::copyable, void
        >::type copyable;
    };
}}

2.5.2   Exercising the Code So Far

Revisiting our original examples,

typedef boost::python::class_<
    class_type<B>, copyable<boost::noncopyable>
> c1;

typedef boost::python::class_<
    D
  , held_type<std::auto_ptr<D> >
  , base_list<bases<B> >
> c2;

we can now examine the intended parameters:

BOOST_MPL_ASSERT((boost::is_same<c1::class_type, B>));
BOOST_MPL_ASSERT((boost::is_same<c1::base_list, bases<> >));
BOOST_MPL_ASSERT((boost::is_same<c1::held_type, B>));
BOOST_MPL_ASSERT((
    boost::is_same<c1::copyable, boost::noncopyable>
));

BOOST_MPL_ASSERT((boost::is_same<c2::class_type, D>));
BOOST_MPL_ASSERT((boost::is_same<c2::base_list, bases<B> >));
BOOST_MPL_ASSERT((
    boost::is_same<c2::held_type, std::auto_ptr<D> >
));
BOOST_MPL_ASSERT((boost::is_same<c2::copyable, void>));

2.5.3   Deduced Template Parameters

To apply a deduced parameter interface here, we need only make the type requirements a bit tighter so the held_type and copyable parameters can be crisply distinguished from the others. Boost.Python does this by requiring that base_list be a specialization of its bases< … > template (as opposed to being any old MPL sequence) and by requiring that copyable, if explicitly supplied, be boost::noncopyable. One easy way of identifying specializations of bases< … > is to derive them all from the same class, as an implementation detail:

namespace boost { namespace python {
    namespace detail {

        struct bases_base
        {
        };
    }

    template <
        typename A0 = void, typename A1 = void, typename A2 = void …
    >
    struct bases : detail::bases_base
    {
    };
}}

Now we can rewrite our signature to make all three optional parameters deducible:

typedef parameter::parameters<
    required<tag::class_type, is_class<_> >

  , parameter::optional<
        deduced<tag::base_list>
      , is_base_and_derived<detail::bases_base,_>
    >

  , parameter::optional<
        deduced<tag::held_type>
      , mpl::not_<
            mpl::or_<
                is_base_and_derived<detail::bases_base,_>
              , is_same<noncopyable,_>
            >
        >
    >

  , parameter::optional<
        deduced<tag::copyable>
      , is_same<noncopyable,_>
    >

> class_signature;

It may seem like we've added a great deal of complexity, but the benefits to our users are greater. Our original examples can now be written without explicit parameter names:

typedef boost::python::class_<B, boost::noncopyable> c1;

typedef boost::python::class_<
    D, std::auto_ptr<D>, bases<B>
> c2;

3   Advanced Topics

At this point, you should have a good grasp of the basics. In this section we'll cover some more esoteric uses of the library.

3.1   Fine-Grained Name Control

If you don't like the leading-underscore naming convention used to refer to keyword objects, or you need the name tag for something other than the keyword type namespace, there's another way to use BOOST_PARAMETER_NAME:

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

Here is a usage example:

BOOST_PARAMETER_NAME(
    (
        pass_foo, keywords
    ) foo
)

BOOST_PARAMETER_FUNCTION(
    (int), f,
    keywords, (required (foo, *))
)
{
    return foo + 1;
}

int x = f(pass_foo = 41);

Before you use this more verbose form, however, please read the section on best practices for keyword object naming.

3.2   More ArgumentPacks

We've already seen ArgumentPacks when we looked at parameter-enabled constructors and class templates. As you might have guessed, ArgumentPacks actually lie at the heart of everything this library does; in this section we'll examine ways to build and manipulate them more effectively.

3.2.1   Building ArgumentPacks

The simplest ArgumentPack is the result of assigning into a keyword object:

BOOST_PARAMETER_NAME(index)

template <typename ArgumentPack>
int print_index(ArgumentPack const& args)
{
    std::cout << "index = " << args[_index];
    std::cout << std::endl;
    return 0;
}

int x = print_index(_index = 3);  // prints "index = 3"

Also, ArgumentPacks can be composed using the comma operator. The extra parentheses below are used to prevent the compiler from seeing two separate arguments to print_name_and_index:

BOOST_PARAMETER_NAME(name)

template <typename ArgumentPack>
int print_name_and_index(ArgumentPack const& args)
{
    std::cout << "name = " << args[_name];
    std::cout << "; ";
    return print_index(args);
}

int y = print_name_and_index((_index = 3, _name = "jones"));

The compose.cpp test program shows more examples of this feature.

To build an ArgumentPack with positional arguments, we can use a ParameterSpec. As introduced described in the section on Class Template Signatures, a ParameterSpec describes the positional order of parameters and any associated type requirements. Just as we can build an ArgumentPack type with its nested ::bind< … > template, we can build an ArgumentPack object by invoking its function call operator:

parameter::parameters<
    required<tag::name, is_convertible<_,char const*> >
  , optional<tag::index, is_convertible<_,int> >
> spec;

char const sam[] = "sam";
int twelve = 12;

int z0 = print_name_and_index(
    spec( sam, twelve )
);

int z1 = print_name_and_index(
    spec( _index=12, _name="sam" )
);

3.2.2   Extracting Parameter Types

If we want to know the types of the arguments passed to print_name_and_index, we have a couple of options. The simplest and least error-prone approach is to forward them to a function template and allow it to do type deduction:

BOOST_PARAMETER_NAME(name)
BOOST_PARAMETER_NAME(index)

template <typename Name, typename Index>
int deduce_arg_types_impl(Name&& name, Index&& index)
{
    // we know the types
    Name&& n2 = boost::forward<Name>(name);
    Index&& i2 = boost::forward<Index>(index);
    return index;
}

template <typename ArgumentPack>
int deduce_arg_types(ArgumentPack const& args)
{
    return deduce_arg_types_impl(args[_name], args[_index | 42]);
}

Occasionally one needs to deduce argument types without an extra layer of function call. For example, suppose we wanted to return twice the value of the index parameter? In that case we can use the value_type< … > metafunction introduced earlier:

BOOST_PARAMETER_NAME(index)

template <typename ArgumentPack>
typename boost::parameter::value_type<ArgumentPack,tag::index,int>::type
    twice_index(ArgumentPack const& args)
{
    return 2 * args[_index | 42];
}

Note that if we had used binding< … > rather than value_type< … >, we would end up returning a reference to the temporary created in the 2 * … expression.

3.2.3   Lazy Default Computation

When a default value is expensive to compute, it would be preferable to avoid it until we're sure it's absolutely necessary. BOOST_PARAMETER_FUNCTION takes care of that problem for us, but when using ArgumentPacks explicitly, we need a tool other than operator|:

BOOST_PARAMETER_NAME(s1)
BOOST_PARAMETER_NAME(s2)
BOOST_PARAMETER_NAME(s3)

template <typename ArgumentPack>
std::string f(ArgumentPack const& args)
{
    std::string const& s1 = args[_s1];
    std::string const& s2 = args[_s2];
    typename parameter::binding<
        ArgumentPack,tag::s3,std::string
    >::type s3 = args[_s3 | (s1 + s2)];  // always constructs s1 + s2
    return s3;
}

std::string x = f((
    _s1="hello,", _s2=" world", _s3="hi world"
));

In the example above, the string "hello, world" is constructed despite the fact that the user passed us a value for s3. To remedy that, we can compute the default value lazily (that is, only on demand), by using boost::bind() to create a function object.

typename parameter::binding<
    ArgumentPack,tag::s3,std::string
>::type s3 = args[
    _s3 || boost::bind(
        std::plus<std::string>(), boost::ref(s1), boost::ref(s2)
    )
];

Mnemonics

To remember the difference between | and ||, recall that || normally uses short-circuit evaluation: its second argument is only evaluated if its first argument is false. Similarly, in color_map[param || f], f is only invoked if no color_map argument was supplied.

The expression bind(std::plus<std::string>(), ref(s1), ref(s2)) yields a function object that, when invoked, adds the two strings together. That function will only be invoked if no s3 argument is supplied by the caller.

4   Best Practices

By now you should have a fairly good idea of how to use the Parameter library. This section points out a few more-marginal issues that will help you use the library more effectively.

4.1   Keyword Naming

BOOST_PARAMETER_NAME prepends a leading underscore to the names of all our keyword objects in order to avoid the following usually-silent bug:

namespace people
{
    namespace tag
    {
        struct name
        {
            typedef boost::parameter::forward_reference qualifier;
        };

        struct age
        {
            typedef boost::parameter::forward_reference qualifier;
        };
    }

    namespace // unnamed
    {
        boost::parameter::keyword<tag::name>& name
            = boost::parameter::keyword<tag::name>::instance;
        boost::parameter::keyword<tag::age>& age
            = boost::parameter::keyword<tag::age>::instance;
    }

    BOOST_PARAMETER_FUNCTION(
        (void), g, tag, (optional (name, *, "bob")(age, *, 42))
    )
    {
        std::cout << name << ":" << age;
    }

    void f(int age)
    {
        :vellipsis:`        .
        .
        .
        `
        g(age = 3);  // whoops!
    }
}

System Message: WARNING/2 (/root/project/libs/parameter/doc/index.rst, line 2472); backlink

Inline interpreted text or phrase reference start-string without end-string.

Although in the case above, the user was trying to pass the value 3 as the age parameter to g, what happened instead was that f's age argument got reassigned the value 3, and was then passed as a positional argument to g. Since g's first positional parameter is name, the default value for age is used, and g prints 3:42. Our leading underscore naming convention makes this problem less likely to occur.

In this particular case, the problem could have been detected if f's age parameter had been made const, which is always a good idea whenever possible. Finally, we recommend that you use an enclosing namespace for all your code, but particularly for names with leading underscores. If we were to leave out the people namespace above, names in the global namespace beginning with leading underscores—which are reserved to your C++ compiler—might become irretrievably ambiguous with those in our unnamed namespace.

4.2   Namespaces

In our examples we've always declared keyword objects in (an unnamed namespace within) the same namespace as the Boost.Parameter-enabled functions using those keywords:

namespace lib {

    BOOST_PARAMETER_NAME(name)
    BOOST_PARAMETER_NAME(index)

    BOOST_PARAMETER_FUNCTION(
        (int), f, tag,
        (optional (name,*,"bob")(index,(int),1))
    )
    {
        std::cout << name << ":" << index;
        std::cout << std::endl;
        return index;
    }
}

Users of these functions have a few choices:

  1. Full qualification:

    int x = lib::f(
    lib::_name = "jill"
  , lib::_index = 1
);

    This approach is more verbose than many users would like.

  1. Make keyword objects available through using-declarations:

    using lib::_name;
using lib::_index;

int x = lib::f(_name = "jill", _index = 1);

    This version is much better at the actual call site, but the using-declarations themselves can be verbose and hard to manage.

  1. Bring in the entire namespace with a using-directive:

    using namespace lib;
int x = f(_name = "jill", _index = 3);

    This option is convenient, but it indiscriminately makes the entire contents of lib available without qualification.

If we add an additional namespace around keyword declarations, though, we can give users more control:

namespace lib {
    namespace keywords {

        BOOST_PARAMETER_NAME(name)
        BOOST_PARAMETER_NAME(index)
    }

    BOOST_PARAMETER_FUNCTION(
        (int), f, keywords::tag,
        (optional (name,*,"bob")(index,(int),1))
    )
    {
        std::cout << name << ":" << index;
        std::cout << std::endl;
        return index;
    }
}

Now users need only a single using-directive to bring in just the names of all keywords associated with lib:

using namespace lib::keywords;
int y = lib::f(_name = "bob", _index = 2);

4.3   Documentation

The interface idioms enabled by Boost.Parameter are completely new (to C++), and as such are not served by pre-existing documentation conventions.

Note

This space is empty because we haven't settled on any best practices yet. We'd be very pleased to link to your documentation if you've got a style that you think is worth sharing.

5   Portability Considerations

Use the regression test results for the latest Boost release of the Parameter library to see how it fares on your favorite compiler. Additionally, you may need to be aware of the following issues and workarounds for particular compilers.

5.1   Perfect Forwarding Support

If your compiler supports perfect forwarding, then the Parameter library will #define the macro BOOST_PARAMETER_HAS_PERFECT_FORWARDING unless you disable it manually. If your compiler does not provide this support, then parameter::parameters::operator() will treat rvalue references as lvalue const references to work around the forwarding problem, so in certain cases you must wrap boost::ref or std::ref around any arguments that will be bound to out parameters. The evaluate_category.cpp and preprocessor_eval_category.cpp test programs demonstrate this support.

5.2   Boost.MP11 Support

If your compiler is sufficiently compliant with the C++11 standard, then the Parameter library will #define the macro BOOST_PARAMETER_CAN_USE_MP11 unless you disable it manually. The singular.cpp, compose.cpp, optional_deduced_sfinae.cpp, and deduced_dependent_predicate.cpp test programs demonstrate support for Boost.MP11.

5.3   No SFINAE Support

Some older compilers don't support SFINAE. If your compiler meets that criterion, then Boost headers will #define the preprocessor symbol BOOST_NO_SFINAE, and parameter-enabled functions won't be removed from the overload set based on their signatures. The sfinae.cpp and optional_deduced_sfinae.cpp test programs demonstrate SFINAE support.

5.4   No Support for result_of

Lazy default computation relies on the result_of class template to compute the types of default arguments given the type of the function object that constructs them. On compilers that don't support result_of, BOOST_NO_RESULT_OF will be #defined, and the compiler will expect the function object to contain a nested type name, result_type, that indicates its return type when invoked without arguments. To use an ordinary function as a default generator on those compilers, you'll need to wrap it in a class that provides result_type as a typedef and invokes the function via its operator().

5.5   Compiler Can't See References In Unnamed Namespace

If you use Microsoft Visual C++ 6.x, you may find that the compiler has trouble finding your keyword objects. This problem has been observed, but only on this one compiler, and it disappeared as the test code evolved, so we suggest you use it only as a last resort rather than as a preventative measure. The solution is to add using-declarations to force the names to be available in the enclosing namespace without qualification:

namespace graphs {

    using graphs::graph;
    using graphs::visitor;
    using graphs::root_vertex;
    using graphs::index_map;
    using graphs::color_map;
}

6   Python Binding

Follow this link for documentation on how to expose Boost.Parameter-enabled functions to Python with Boost.Python.

7   Reference

Follow this link to the Boost.Parameter reference documentation.

8   Glossary

8.1   Argument (or “actual argument”)

the value actually passed to a function or class template.

8.2   Parameter (or “formal parameter”)

the name used to refer to an argument within a function or class template. For example, the value of f's parameter x is given by the argument 3:

int f(int x) { return x + 1; }
int y = f(3);

9   Acknowledgements

The authors would like to thank all the Boosters who participated in the review of this library and its documentation, most especially our review manager, Doug Gregor.

[1]As of Boost 1.33.0 the Graph library was still using an older named parameter mechanism, but there are plans to change it to use Boost.Parameter (this library) in an upcoming release, while keeping the old interface available for backward-compatibility.
[2]The One Definition Rule says that any given entity in a C++ program must have the same definition in all translation units (object files) that make up a program.
[3]If you're not familiar with the Boost Graph Library, don't worry about the meaning of any Graph-library-specific details you encounter. In this case you could replace all mentions of vertex descriptor types with int in the text, and your understanding of the Parameter library wouldn't suffer.
[4]This is a major motivation behind C++20 constraints.
[5](1, 2) Here we're assuming there's a predicate metafunction is_keyword_expression that can be used to identify models of Boost.Python's KeywordExpression concept.
[6]

You can always give the illusion that the function lives in an outer namespace by applying a using-declaration:

namespace foo_overloads {

    // foo declarations here
    void foo() { ... }
    ...
}
using foo_overloads::foo;

This technique for avoiding unintentional argument-dependent lookup is due to Herb Sutter.
[7]This capability depends on your compiler's support for SFINAE. SFINAE: Substitution Failure Is Not An Error. If type substitution during the instantiation of a function template results in an invalid type, no compilation error is emitted; instead the overload is removed from the overload set. By producing an invalid type in the function signature depending on the result of some condition, we can decide whether or not an overload is considered during overload resolution. The technique is formalized in the enable_if utility. Most recent compilers support SFINAE; on compilers that don't support it, the Boost config library will #define the symbol BOOST_NO_SFINAE. See http://www.semantics.org/once_weakly/w02_SFINAE.pdf for more information on SFINAE.
Generated on: 2023-04-10 13:50 UTC. Generated by Docutils from reStructuredText source.