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
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
| 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
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:
Since an argument's meaning is given by its position, we have to choose an (often arbitrary) order for parameters with default values, making some combinations of defaults unusable:
window* new_window(
char const* name,
int border_width = default_border_width,
bool movable = true,
bool initially_visible = true
);
const bool movability = false;
window* w = new_window("alert box", movability);
In the example above we wanted to make an unmoveable window with a default border_width, but instead we got a moveable window with a border_width of zero. To get the desired effect, we'd need to write:
window* w = new_window( "alert box", default_border_width, movability);
It can become difficult for readers to understand the meaning of arguments at the call site:
window* w = new_window("alert", 1, true, false);
Is this window moveable and initially invisible, or unmoveable and initially visible? The reader needs to remember the order of arguments to be sure.
The author of the call may not remember the order of the arguments either, leading to hard-to-find bugs.
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!
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.
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;
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.
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
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.
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 <
class Graph, class DFSVisitor, class Index, class 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.
| Parameter Name | Dataflow | 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. | an 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.
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 { struct graph; } // keyword tag type
namespace // unnamed
{
// A reference to the keyword object
boost::parameter::keyword<tag::graph>& _graph
= boost::parameter::keyword<tag::graph>::get();
}
}
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).
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))
(in_out(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:
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.
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 asterisk 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.
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))
(in_out(color_map), *,
default_color_map(num_vertices(graph), index_map) )
)
Within the function body, a parameter name such as visitor is a C++ reference, bound either to an actual argument passed by the caller or to the result of evaluating a default expression. In most cases, parameter types are of the form T const& for some T. Parameters whose values are expected to be modified, however, must be passed by reference to non-const. To indicate that color_map is both read and written, we wrap its name in in_out(…):
(optional
(visitor, *, boost::dfs_visitor<>())
(root_vertex, *, *vertices(graph).first)
(index_map, *, get(boost::vertex_index,graph))
(in_out(color_map), *,
default_color_map(num_vertices(graph), index_map) )
)
If color_map were strictly going to be modified but not examined, we could have written out(color_map). There is no functional difference between out and in_out; the library provides both so you can make your interfaces more self-documenting.
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.
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))
(in_out(color_map), *,
default_color_map(num_vertices(graph), index_map) )
)
A default expression is evaluated in the context of all preceding parameters, so you can use any of their values by name.
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(
(void), depth_first_search, tag
…signature goes here…
)
{
std::cout << "graph=" << graph << std::endl;
std::cout << "visitor=" << visitor << std::endl;
std::cout << "root_vertex=" << root_vertex << std::endl;
std::cout << "index_map=" << index_map << std::endl;
std::cout << "color_map=" << color_map << std::endl;
}
int main()
{
depth_first_search(1, 2, 3, 4, 5);
depth_first_search(
"1", '2', _color_map = '5',
_index_map = "4", _root_vertex = "3");
}
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.
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.
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");
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 need to tell the library about this requirement by replacing the * element of the signature with the required type, in parentheses:
(root_vertex,
(typename boost::graph_traits<graph_type>::vertex_descriptor),
*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.
Note
The type of the graph argument is available in the signature—and in the function body—as graph_type. In general, to access the type of any parameter foo, write foo_type.
The requirements on other arguments are a bit more interesting than those on root_vertex; they can't be described in terms of simple type matching. Instead, they must be described in terms of MPL Metafunctions. There's no space to give a complete description of metafunctions or of graph library details here, but we'll show you the complete signature with maximal checking, just to give you a feel for how it's done. Each predicate metafunction is enclosed in parentheses and preceded by an asterisk, as follows:
BOOST_PARAMETER_FUNCTION(
(void), depth_first_search, graphs
, (required
(graph
, *(boost::mpl::and_<
boost::is_convertible<
boost::graph_traits<_>::traversal_category
, boost::incidence_graph_tag
>
, boost::is_convertible<
boost::graph_traits<_>::traversal_category
, boost::vertex_list_graph_tag
>
>) ))
(optional
(visitor, *, boost::dfs_visitor<>()) // not checkable
(root_vertex
, (typename boost::graph_traits<graphs::graph::_>::vertex_descriptor)
, *vertices(graph).first)
(index_map
, *(boost::mpl::and_<
boost::is_integral<
boost::property_traits<_>::value_type
>
, boost::is_same<
typename boost::graph_traits<graphs::graph::_>::vertex_descriptor
, boost::property_traits<_>::key_type
>
>)
, get(boost::vertex_index,graph))
(in_out(color_map)
, *(boost::is_same<
typename boost::graph_traits<graphs::graph::_>::vertex_descriptor
, boost::property_traits<_>::key_type
>)
, default_color_map(num_vertices(graph), index_map) )
)
)
We acknowledge that this signature is pretty hairy looking. Fortunately, it usually isn't necessary to so completely encode the type requirements on arguments to generic functions. However, it is usally worth the effort to do so: your code will be more self-documenting and will often provide a better user experience. You'll also have an easier transition to an upcoming C++ standard with language support for concepts.
To illustrate deduced parameter support we'll have to leave behind our example from the Graph library. Instead, consider the example of the def function from Boost.Python. Its signature is roughly as follows:
template <
class Function, Class KeywordExpression, class 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:
namespace mpl = boost::mpl;
BOOST_PARAMETER_FUNCTION(
(void), def, tag,
(required (name,(char const*)) (func,*) ) // nondeduced
(deduced
(optional
(docstring, (char const*), "")
(keywords
, *(is_keyword_expression<mpl::_>) // see5
, no_keywords())
(policies
, *(mpl::not_<
mpl::or_<
boost::is_convertible<mpl::_, char const*>
, is_keyword_expression<mpl::_> // see5
>
>)
, 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:
def("f", &f, some_policies, "Documentation for f");
def("f", &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", &f
, _policies = some_policies, "Documentation for f");
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::endl;
}
};
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.
};
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;
}
};
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 a base class.
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 <class ArgumentPack>
myclass_impl(ArgumentPack const& args)
{
std::cout << "name = " << args[_name]
<< "; index = " << args[_index | 42]
<< 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.
In this section we'll use Boost.Parameter to build Boost.Python's class_ template, whose “signature” is:
template class<
ValueType, BaseList = bases<>
, HeldType = ValueType, Copyable = void
>
class class_;
Only the first argument, ValueType, is required.
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> >
> …;
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 <class 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.
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 <
class A0
, class A1 = parameter::void_
, class A2 = parameter::void_
, class A3 = parameter::void_
>
struct class_
{
…
};
}}
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;
}}
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 <
class A0
, class A1 = parameter::void_
, class A2 = parameter::void_
, class A3 = parameter::void_
>
struct class_
{
// Create ArgumentPack
typedef typename
class_signature::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;
};
}}
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>));
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 <class A0 = void, class A1 = void, class 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;
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.
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.
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.
The simplest ArgumentPack is the result of assigning into a keyword object:
BOOST_PARAMETER_NAME(index)
template <class ArgumentPack>
int print_index(ArgumentPack const& args)
{
std::cout << "index = " << args[_index] << 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 <class ArgumentPack>
int print_name_and_index(ArgumentPack const& args)
{
std::cout << "name = " << args[_name] << "; ";
return print_index(args);
}
int y = print_name_and_index((_index = 3, _name = "jones"));
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")
);
Note that because of the forwarding problem, parameter::parameters::operator() can't accept non-const rvalues.
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 <class Name, class Index>
int deduce_arg_types_impl(Name& name, Index& index)
{
Name& n2 = name; // we know the types
Index& i2 = index;
return index;
}
template <class 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 <class ArgumentPack>
typename parameter::value_type<ArgumentPack, tag::index, int>::type
twice_index(ArgumentPack const& args)
{
return 2 * args[_index|42];
}
int six = twice_index(_index = 3);
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.
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 <class 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.
using boost::bind;
using boost::ref;
typename parameter::binding<
ArgumentPack, tag::s3, std::string
>::type s3 = args[_s3 || bind(std::plus<std::string>(), ref(s1), ref(s2)) ];
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.
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.
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; struct age; }
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)
{
.
.
.
g(age = 3); // whoops!
}
}
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 that 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.
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::endl;
return index;
}
}
Users of these functions have a few choices:
int x = lib::f(lib::_name = "jill", lib::_index = 1);This approach is more verbose than many users would like.
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.
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::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);
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.
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.
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.
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().
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;
}
Follow this link for documentation on how to expose Boost.Parameter-enabled functions to Python with Boost.Python.
Follow this link to the Boost.Parameter reference documentation.
| Argument (or “actual argument”): | |
|---|---|
| the value actually passed to a function or class template | |
| 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);
|
|
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 ConceptC++. |
| [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 E rror. 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. |