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

Click here to view the latest version of this page.

The Boost Parameter Library

Boost


Abstract:

Use this library to write functions that accept arguments by name:

new_window("alert", width=10, titlebar=false);

Since named arguments can be passed in any order, they are especially useful when a function has more than one parameter with a useful default value.


Authors:David Abrahams, Daniel Wallin
Contact:dave@boost-consulting.com, dalwan01@student.umu.se
Organization:Boost Consulting
Date:$Date: 2005/07/18 20:34:31 $
Copyright:Copyright David Abrahams, Daniel Wallin 2005. 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)

Table of Contents


1   Introduction

In C++, arguments are normally given meaning by their positions with respect to a parameter list. 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:

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

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

2   Tutorial

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 After laying some groundwork and describing the algorithm's abstract interface, we'll show you how to build a basic implementation with keyword support. Then we'll add support for default arguments and we'll gradually refine the implementation with syntax improvements. Finally we'll show how to streamline the implementation of named parameter interfaces, improve their participation in overload resolution, and optimize their runtime efficiency.

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

depth_first_search Parameters
Parameter Name Dataflow Default Value (if any)
graph in none - this argument is required.
visitor in boost::dfs_visitor<>()
root_vertex in *vertices(graph).first
index_map in get(boost::vertex_index,graph)
color_map out 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 complex default values. For the purposes of this exercise, you don't need to understand what they mean. Also, we'll show you how the default for color_map is computed later in the tutorial; trust us when we say that the complexity of its default will become valuable.

2.3   Defining the Keywords

The point of this exercise is to make it possible to call depth_first_search with keyword 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 with an assignment operator that 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. Since users need access to the keyword objects, but not the tag types, we'll define the keyword objects so they're acceessible through graphs, and we'll hide the tag types away in a tested namespace, graphs::tag. The library provides a convenient macro for that purpose (MSVC6.x users see this note):

#include <boost/parameter/keyword.hpp>

namespace graphs
{
  BOOST_PARAMETER_KEYWORD(tag, graph)    // Note: no semicolon
  BOOST_PARAMETER_KEYWORD(tag, visitor)
  BOOST_PARAMETER_KEYWORD(tag, root_vertex)
  BOOST_PARAMETER_KEYWORD(tag, index_map)
  BOOST_PARAMETER_KEYWORD(tag, color_map)
}

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

namespace graphs 
{
  namespace tag { struct visitor; }
  namespace { 
    boost::parameter::keyword<tag::visitor>& visitor
    = boost::parameter::keyword<tag::visitor>::get();
  }
}

This “fancy dance” involving the 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.

2.4   Defining the Implementation Function

Next we can write the skeleton of the function that implements the core of depth_first_search:

namespace graphs { namespace core
{
  template <class ArgumentPack>
  void depth_first_search(ArgumentPack const& args)
  {
      // algorithm implementation goes here
  }
}}

core::depth_first_search has an ArgumentPack parameter: a bundle of references to the arguments that the caller passes to the algorithm, tagged with their keywords. To extract each parameter, just pass its keyword object to the ArgumentPack's subscript operator. Just to get a feel for how things work, let's add some temporary code to print the arguments:

namespace graphs { namespace core
{
  template <class ArgumentPack>
  void depth_first_search(ArgumentPack const& args)
  {
      std::cout << "graph:\t" << args[graph] << std::endl;
      std::cout << "visitor:\t" << args[visitor] << std::endl;
      std::cout << "root_vertex:\t" << args[root_vertex] << std::endl;
      std::cout << "index_map:\t" << args[index_map] << std::endl;
      std::cout << "color_map:\t" << args[color_map] << std::endl;
  }
}} // graphs::core

It's unlikely that many of the arguments the caller will eventually pass to depth_first_search can be printed, but for now the code above will give us something to experiment with. To see the keywords in action, we can write a little test driver:

int main()
{
    using namespace graphs;

    core::depth_first_search((
      graph = 'G', visitor = 2, root_vertex = 3.5, 
      index_map = "hello, world", color_map = false));
}

An overloaded comma operator (operator,) combines the results of assigning to each keyword object into a single ArgumentPack object that gets passed on to core::depth_first_search. The extra set of parentheses you see in the example above are required: without them, each assignment would be interpreted as a separate function argument and the comma operator wouldn't take effect. We'll show you how to get rid of the extra parentheses later in this tutorial.

Of course, we can pass the arguments in any order:

int main()
{
    using namespace graphs;

    core::depth_first_search((
      root_vertex = 3.5, graph = 'G', color_map = false, 
      index_map = "hello, world", visitor = 2));
}

either of the two programs above will print:

graph:       G
visitor:     2
root_vertex: 3.5
index_map:   hello, world
color_map:   false

2.5   Adding Defaults

Currently, all the arguments to depth_first_search are required. If any parameter can't be found, there will be a compilation error where we try to extract it from the ArgumentPack using the subscript operator. To make it legal to omit an argument we need to give it a default value.

2.5.1   Syntax

We can make any of the parameters optional by following its keyword with the | operator and the parameter's default value within the square brackets. In the following example, we've given root_vertex a default of 42 and color_map a default of "hello, world".

namespace graphs { namespace core
{
  template <class ArgumentPack>
  void depth_first_search(ArgumentPack const& args)
  {
      std::cout << "graph:\t" << args[graph] << std::endl;
      std::cout << "visitor:\t" << args[visitor] << std::endl;
      std::cout << "root_vertex:\t" << args[root_vertex|42] << std::endl;
      std::cout << "index_map:\t" << args[index_map] << std::endl;
      std::cout << "color_map:\t" << args[color_map|"hello, world"] << std::endl;
  }
}} // graphs::core

Now we can invoke the function without supplying color_map or root_vertex:

core::depth_first_search((
  graph = 'G', index_map = "index", visitor = 6));

The call above would print:

graph:       G
visitor:     6
root_vertex: 42
index_map:   index
color_map:   hello, world

Important

The index expression args[…] always yields a reference that is bound either to the actual argument passed by the caller or, if no argument is passed explicitly, to the specified default value.

2.5.2   Getting More Realistic

Now it's time to put some more realistic defaults in place. We'll have to give up our print statements—at least if we want to see the defaults work—since, the default values of these parameters generally aren't printable.

Instead, we'll connect local variables to the arguments and use those in our algorithm:

namespace graphs { namespace core
{
  template <class ArgumentPack>
  void depth_first_search(ArgumentPack const& args)
  {
      Graph   g = args[graph];
      Visitor v = args[visitor|default-expression1];
      Vertex  s = args[root_vertex|default-expression2];
      Index   i = args[index_map|default-expression3];
      Color   c = args[visitor|default-expression4];

      …use g, v, s, i, and c to implement the algorithm…
  }
}} // graphs::core

We'll insert the default expressions in a moment, but first we need to come up with the types Graph, Visitor, Vertex, Index, and Color.

2.5.3   The binding Metafunction

To compute the type of a parameter we can use a Metafunction called binding:

binding<ArgumentPack, Keyword, Default = void>
{ typedef see text type; };

where Default is the type of the default argument, if any.

For example, to declare and initialize g above, we could write:

typedef typename parameter::binding<
  ArgumentPack,tag::graph
>::type Graph;

Graph g = args[graph];

As shown in the parameter table, graph has no default, so the binding invocation for Graph takes only two arguments. The default visitor is boost::dfs_visitor<>(), so the binding invocation for Visitor takes three arguments:

typedef typename parameter::binding<
  ArgumentPack,tag::visitor,boost::dfs_visitor<>
>::type Visitor;

Visitor v = args[visitor|boost::dfs_visitor<>()];

Note that the default visitor is supplied as a temporary instance of dfs_visitor. Because args[…] always yields a reference, making v a reference would cause it to bind to that temporary, and immediately dangle. Therefore, it's crucial that we passed dfs_visitor<>, and not dfs_visitor<> const&, as the last argument to binding.

Important

Never pass binding a reference type as the default unless you know that the default value passed to the ArgumentPack's indexing operator will outlive the reference you'll bind to it.

Sometimes there's no need to use binding at all. The root_vertex argument is required to be of the graph's vertex_descriptor type,3 so we can just use that knowledge to bypass binding altogether.

typename boost::graph_traits<Graph>::vertex_descriptor
  s = args[root_vertex|*vertices(g).first];

2.5.4   Beyond Ordinary Default Arguments

Here's how you might write the declaration for the index_map parameter:

typedef typename parameter::binding<
    ArgumentPack
  , tag::index_map
  , typename boost::property_map<Graph, vertex_index_t>::const_type
>::type Index;

Index i = args[index_map|get(boost::vertex_index,g)];

Notice two capabilities we've gained over what plain C++ default arguments provide:

  1. The default value of the index parameter depends on the value of the graph parameter. That's illegal in plain C++:

    void f(int graph, int index = graph + 1); // error
    
  2. The index parameter has a useful default, yet it is templated and its type can be deduced when an index argument is explicitly specified by the caller. In plain C++, you can specify a default value for a parameter with deduced type, but it's not very useful:

    template <class Index>
    int f(Index index = 42);  // OK
    int y = f();                // error; can't deduce Index
    

2.6   Syntactic Refinement

In this section we'll describe how you can allow callers to invoke depth_first_search with just one pair of parentheses, and to omit keywords where appropriate.

2.6.1   Describing the Positional Argument Order

First, we'll need to build a type that describes the allowed parameters and their ordering when passed positionally. This type is known as a ParameterSpec (MSVC6.x users see this note):

namespace graphs
{
  typedef parameter::parameters<
      tag::graph
    , tag::visitor
    , tag::root_vertex
    , tag::index_map
    , tag::color_map
  > dfs_params;
}

The parameters template supplies a function-call operator that groups all its arguments into an ArgumentPack. Any arguments passed to it without a keyword label will be associated with a parameter according to its position in the ParameterSpec. So for example, given an object p of type dfs_params,

p('G', index_map=1)

yields an ArgumentPack whose graph parameter has a value of 'G', and whose index_map parameter has a value of 1.

2.6.2   Forwarding Functions

Next we need a family of overloaded depth_first_search function templates that can be called with anywhere from one to five arguments. These forwarding functions will invoke an instance of dfs_params as a function object, passing their parameters to its operator() and forwarding the result on to core::depth_first_search:

namespace graphs
{
  template <class A0>
  void depth_first_search(A0 const& a0)
  {
     core::depth_first_search(dfs_params()(a0));
  }

  template <class A0, class A1>
  void depth_first_search(A0 const& a0, A1 const& a1)
  {
     core::depth_first_search(dfs_params()(a0,a1));
  } 
  .
  .
  .
 
  template <class A0, class A1, …class A4>
  void depth_first_search(A0 const& a0, A1 const& a1, …A4 const& a4)
  {
     core::depth_first_search(dfs_params()(a0,a1,a2,a3,a4));
  }
}

That's it! We can now call graphs::depth_first_search with from one to five arguments passed positionally or via keyword.

2.6.3   “Out” Parameters

Well, that's not quite it. When passing arguments by keyword, the keyword object's assignment operator yields a temporary ArgumentPack object. A conforming C++ compiler will refuse to bind a non-const reference to a temporary, so to support a keyword interface for all arguments, the overload set above must take its arguments by const reference. On the other hand—as you may recall from the parameter tablecolor_map is an “out” parameter, so it really should be passed by non-const reference.

A keyword object has a pair of operator= overloads that ensure we can pass anything—temporary or not, const or not—by name, while preserving the mutability of non-temporaries:

template <class A>                  // handles non-const, 
ArgumentPack operator=(A&);       // non-temporary objects

template <class A>                  // handles const objects
ArgumentPack operator=(A const&); // and temporaries

However, when an “out” parameter is passed positionally, there's no keyword object involved. With our depth_first_search overload set above, the color_map will be passed by const reference, and compilation will fail when mutating operations are used on it. The simple solution is to add another overload that takes a non-const reference in the position of the “out” parameter:

template <class A0, class A1, …class A4>
void depth_first_search(A0 const& a0, A1 const& a1, …A4& a4)
{
    core::depth_first_search(dfs_params()(a0,a1,a2,a3,a4));
}

That approach works nicely because there is only one “out” parameter and it is in the last position. If color_map had been the first parameter, we would have needed ten overloads. In the worst case—where the function has five “out” parameters—25 or 32 overloads would be required. This “forwarding problem” is well-known to generic library authors, and the C++ standard committee is working on a proposal to address it. In the meantime, you might consider using Boost.Preprocessor to generate the overloads you need.

If it is impractical for you to generate or write the overloads that would be required for positional “out” arguments to be passed directly, you still have the option to ask users to pass them through boost::ref, which will ensure that the algorithm implementation sees a non-const reference:

depth_first_search(g, v, s, i, boost::ref(c));

2.6.4   Generating Forwarding Functions with Macros

To remove some of the tedium of writing overloaded forwarding functions, the library supplies a macro, suitably located in boost/parameter/macros.hpp, that will generate free function overloads for you:

BOOST_PARAMETER_FUN(void, depth_first_search, 1, 5, dfs_params);

will generate a family of five depth_first_search overloads, in the current scope, that pass their arguments through dfs_params. Instead of core::depth_first_search, these overloads will forward the ArgumentPack on to a function called depth_first_search_with_named_params, also in the current scope. It's up to you to implement that function. You could simply transplant the body of core::depth_first_search into depth_first_search_with_named_params if you were going to use this approach.

Note that BOOST_PARAMETER_FUN only takes arguments by const reference, so you will have to add any additional overloads required to handle positional “out” parameters yourself. We are looking into providing a more sophisticated set of macros to address this problem and others, for an upcoming release of Boost.

2.7   Controlling Overload Resolution

The parameters of our templated forwarding functions are completely general; in fact, they're a perfect match for any argument type whatsoever. The problems with exposing such general function templates have been the subject of much discussion, especially in the presence of unqualified calls. Probably the safest thing to do is to isolate the forwarding functions in a namespace containing no types5, but often we'd like our functions to play nicely with argument-dependent lookup and other function overloads. In that case, it's neccessary to remove the functions from the overload set when the passed argument types aren't appropriate.

2.7.1   Updating the ParameterSpec

This sort of overload control can be accomplished in C++ by taking advantage of the SFINAE (Substitution Failure Is Not An Error) rule.6 You can take advantage of the Parameter library's built-in SFINAE support by using the following class templates in your ParameterSpec:

template< class KeywordTag, class Predicate = unspecified >
struct required;

template< class KeywordTag, class Predicate = unspecified >
struct optional;

Instead of using keyword tags directly, we can wrap them in required and optional to indicate which function parameters are required, and optionally pass Predicates to describe the type requirements for each function parameter. The Predicate argument must be a unary MPL lambda expression that, when applied to the actual type of the argument, indicates whether that argument type meets the function's requirements for that parameter position.

For example, let's say we want to restrict depth_first_search() so that the graph parameter is required and the root_vertex parameter is convertible to int. We might write:

#include <boost/type_traits/is_convertible.hpp>
#include <boost/mpl/placeholders.hpp>
namespace graphs
{
  using namespace boost::mpl::placeholders;

  struct dfs_params
    : parameter::parameters<
          parameter::required<tag::graph>
        , parameter::optional<tag::visitor>
        , parameter::optional<
              tag::root_vertex, boost::is_convertible<_,int>
          >
        , parameter::optional<tag::index_map>
        , parameter::optional<tag::color_map>
      >
  {};
}

2.7.2   Applying SFINAE to the Overload Set

Now we add a special defaulted argument to each of our depth_first_search overloads:

namespace graphs
{
  template <class A0>
  void depth_first_search(
      A0 const& a0
    , typename dfs_params::match<A0>::type p = dfs_params())
  {
     core::depth_first_search(p(a0));
  }

  template <class A0, class A1>
  void depth_first_search(
      A0 const& a0, A1 const& a1
    , typename dfs_params::match<A0,A1>::type p = dfs_params())
  {
     core::depth_first_search(p(a0,a1));
  } 
  .
  .
  .
 
  template <class A0, class A1, …class A4>
  void depth_first_search(
      A0 const& a0, A1 const& a1, …A4 const& A4
    , typename dfs_params::match<A0,A1,A2,A3,A4>::type p = dfs_params())
  {
     core::depth_first_search(p(a0,a1,a2,a3,a4));
  }
}

These additional parameters are not intended to be used directly by callers; they merely trigger SFINAE by becoming illegal types when the name argument is not convertible to const char*. The BOOST_PARAMETER_FUN macro described earlier adds these extra function parameters for you (Borland users see this note).

2.7.3   Reducing Boilerplate With Macros

The library provides a macro you can use to eliminate some of the repetetiveness of the declaring the optional parameters. BOOST_PARAMETER_MATCH takes three arguments: the ParameterSpec, a Boost.Preprocessor sequence of the function argument types, and a name for the defaulted function parameter (p, above), and it generates the appropriate defaulted argument. So we could shorten the overload set definition as follows:

namespace graphs
{
  template <class A0>
  void depth_first_search(
      A0 const& a0
    , BOOST_PARAMETER_MATCH(dfs_params, (A0), p))
  {
     core::depth_first_search(p(a0));
  }

  template <class A0, class A1>
  void depth_first_search(
      A0 const& a0, A1 const& a1
    , BOOST_PARAMETER_MATCH(dfs_params, (A0)(A1), p))
  {
     core::depth_first_search(p(a0,a1));
  } 
  .
  .
  .
 
  template <class A0, class A1, …class A4>
  void depth_first_search(
      A0 const& a0, A1 const& a1, …A4 const& A4
    , BOOST_PARAMETER_MATCH(dfs_params, (A0)(A1)…(A4), p))
  {
     core::depth_first_search(p(a0,a1,a2,a3,a4));
  }
}

2.8   Efficiency Issues

The color_map parameter gives us a few efficiency issues to consider. Here's a first cut at extraction and binding:

typedef 
  vector_property_map<boost::default_color_type, Index>
default_color_map;

typename parameter::binding<
    ArgumentPack
  , tag::color_map
  , default_color_map
>::type color = args[color_map|default_color_map(num_vertices(g),i)];

2.8.1   Eliminating Copies

The library has no way to know whether an explicitly-supplied argument is expensive to copy (or even if it is copyable at all), so binding<…,k,…>::type is always a reference type when the k parameter is supplied by the caller. Since args[…] yields a reference to the actual argument, color will be bound to the actual color_map argument and no copying will be done.

As described above, because the default is a temporary, it's important that color be a non-reference when the default is used. In that case, the default value will be copied into color. If we store the default in a named variable, though, color can be a reference, thereby eliminating the copy:

default_color_map default_color(num_vertices(g),i);

typename parameter::binding<
    ArgumentPack
  , tag::color_map
  , default_color_map&
>::type color = args[color_map|default_color];

Hint

To avoid making needless copies, pass a reference to the default type as the third argument to binding.

2.8.2   Lazy Default Computation

Of course it's nice to avoid copying default_color, but the more important cost is that of constructing it in the first place. A vector_property_map is cheap to copy, since it holds its elements via a shared_ptr. On the other hand, construction of default_color costs at least two dynamic memory allocations and num_vertices(g) copies; it would be better to avoid doing this work when the default value won't be needed.

To that end, the library allows us to supply a callable object that—if no argument was supplied by the caller—will be invoked to construct the default value. Instead of following the keyword with the | operator, we'll use || and follow it with a nullary (zero-argument) function object that constructs a default_color_map. Here, we build the function object using Boost.Lambda:4

// After #include <boost/lambda/construct.hpp>
typename parameter::binding<
    ArgumentPack
  , tag::color_map
  , default_color_map
>::type color = args[
  color_map
  || boost::lambda::construct<default_color_map>(num_vertices(g),i)
];

2.8.3   Default Forwarding

Types that are expensive to construct yet cheap to copy aren't all that typical, and even copying the color map is more expensive than we might like. It might be nice to avoid both needless construction and needless copying of the default color map. The simplest way to achieve that is to avoid naming it altogether, at least not in core::depth_first_search. Instead, we'll introduce another function template to implement the actual algorithm:

namespace graphs { namespace core
{
  template <class G, class V, class S, class I, class C>
  void dfs_impl(G& g, V& v, S& s, I& i, C& c)
  {
      …actual algorithm implementation…
  }
}}

Then, in core::depth_first_search, we'll simply forward the result of indexing args to core::dfs_impl:

core::dfs_impl( 
    g,v,s,i
  , args[
      color_map
      || boost::lambda::construct<default_color_map>(num_vertices(g),i)
    ]);

In real code, after going to the trouble to write dfs_impl, we'd probably just forward all the arguments.

2.8.4   Dispatching Based on the Presence of a Default

In fact, the Graph library itself constructs a slightly different color_map, to avoid even the overhead of initializing a shared_ptr:

std::vector<boost::default_color_type> 
  color_vec(num_vertices(g));

boost::iterator_property_map<
    typename std::vector<
       boost::default_color_type
    >::iterator
  , Index
> c(color_vec.begin(), i);

To avoid instantiating that code when it isn't needed, we'll have to find a way to select different function implementations, at compile time, based on whether a color_map argument was supplied. By using tag dispatching on the presence of a color_map argument, we can do just that:

#include <boost/type_traits/is_same.hpp>
#include <boost/mpl/bool.hpp>

namespace graphs { namespace core {

  template <class ArgumentPack>
  void dfs_dispatch(ArgumentPack& args, mpl::true_)
  {
      …use the color map computed in the previous example…
  }
  
  template <class ArgumentPack>
  void dfs_dispatch(ArgumentPack& args, mpl::false_)
  {
      …use args[color]…
  }
  
  template <class ArgumentPack>
  void depth_first_search(ArgumentPack& args)
  {
      typedef typename binding<args,tag::color>::type color_;
      core::dfs_dispatch(args, boost::is_same<color_,void>());
  }
}}

We've used the fact that the default for binding's third argument is void: because specializations of is_same are bool-valued MPL Integral Constants derived either from mpl::true_ or mpl::false_, the appropriate dfs_dispatch implementation will be selected.

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

3.1   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 uses of parameters<…>::match and BOOST_PARAMETER_MATCH will be harmless, but will have no effect.

3.2   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().

3.3   Can't Declare ParameterSpec via typedef

In principle you can declare a ParameterSpec as a typedef for a specialization of parameters<…>, but Microsoft Visual C++ 6.x has been seen to choke on that usage. The workaround is to use inheritance and declare your ParameterSpec as a class:

struct dfs_parameters
  : parameter::parameters<
      tag::graph, tag::visitor, tag::root_vertex
    , tag::index_map, tag::color_map
> {};

3.4   Default Arguments Unsupported on Nested Templates

As of this writing, Borland compilers don't support the use of default template arguments on member class templates. As a result, you have to supply BOOST_PARAMETER_MAX_ARITY arguments to every use of parameters<…>::match. Since the actual defaults used are unspecified, the workaround is to use BOOST_PARAMETER_MATCH to declare default arguments for SFINAE.

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

4   Reference

Follow this link to the Boost.Parameter reference documentation.

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

The Lambda library is known not to work on some less-conformant compilers. When using one of those you could define

  template <class T>
  struct construct2
  {
      typedef T result_type;

      template <class A1, class A2>
      T operator()(A1 a1, A2 a2) { return T(a1,a2); }
  };

and use `Boost.Bind`_ to generate the function object::

  boost::bind(construct2<default_color_map>(),num_vertices(g),i)
[5]

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;  
[6]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, whether or not an overload is considered during overload resolution can be controlled. The technique is formalized in the enable_if utility. See http://www.semantics.org/once_weakly/w02_SFINAE.pdf for more information on SFINAE.