mirror of
https://github.com/boostorg/parameter.git
synced 2026-01-28 07:22:28 +00:00
1177 lines
64 KiB
HTML
Executable File
1177 lines
64 KiB
HTML
Executable File
<?xml version="1.0" encoding="utf-8" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
|
|
<title>The Boost Parameter Library</title>
|
|
<link rel="stylesheet" href="rst.css" type="text/css" />
|
|
</head>
|
|
<body>
|
|
<div class="document" id="the-boost-parameter-library">
|
|
<h1 class="title">The Boost Parameter Library</h1>
|
|
<p><a class="reference" href="../../../../index.htm"><img alt="Boost" src="../../../../boost.png" /></a></p>
|
|
<hr class="docutils" />
|
|
<table class="docutils field-list" frame="void" rules="none">
|
|
<col class="field-name" />
|
|
<col class="field-body" />
|
|
<tbody valign="top">
|
|
<tr class="field"><th class="field-name">Abstract:</th><td class="field-body"><p class="first">Use this library to write functions and class templates
|
|
that can accept arguments by name:</p>
|
|
<pre class="literal-block">
|
|
new_window("alert", <strong>width=10</strong>, <strong>titlebar=false</strong>);
|
|
|
|
smart_ptr<
|
|
Foo
|
|
, <strong>deleter_is<Deallocate<Foo> ></strong>
|
|
, <strong>copy_policy_is<DeepCopy></strong>> p(new Foo);
|
|
</pre>
|
|
<p class="last">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
|
|
<em>unnamed</em> parameters; that is to say, parameters whose identity
|
|
can be deduced from their types.</p>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<hr class="docutils" />
|
|
<table class="docutils field-list" frame="void" rules="none">
|
|
<col class="field-name" />
|
|
<col class="field-body" />
|
|
<tbody valign="top">
|
|
<tr class="field"><th class="field-name">Authors:</th><td class="field-body">David Abrahams, Daniel Wallin</td>
|
|
</tr>
|
|
<tr class="field"><th class="field-name">Contact:</th><td class="field-body"><a class="reference" href="mailto:dave@boost-consulting.com">dave@boost-consulting.com</a>, <a class="reference" href="mailto:dalwan01@student.umu.se">dalwan01@student.umu.se</a></td>
|
|
</tr>
|
|
<tr class="field"><th class="field-name">Organization:</th><td class="field-body"><a class="reference" href="http://www.boost-consulting.com">Boost Consulting</a></td>
|
|
</tr>
|
|
<tr class="field"><th class="field-name">Date:</th><td class="field-body">$Date: 2005/07/18 20:34:31 $</td>
|
|
</tr>
|
|
<tr class="field"><th class="field-name">Copyright:</th><td class="field-body">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 <a class="reference" href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<hr class="docutils" />
|
|
<div class="contents topic">
|
|
<p class="topic-title first"><a id="table-of-contents" name="table-of-contents"><strong>Table of Contents</strong></a></p>
|
|
<ul class="auto-toc simple">
|
|
<li><a class="reference" href="#motivation" id="id16" name="id16">1 Motivation</a></li>
|
|
<li><a class="reference" href="#tutorial" id="id17" name="id17">2 Tutorial</a><ul class="auto-toc">
|
|
<li><a class="reference" href="#headers-and-namespaces" id="id18" name="id18">2.1 Headers And Namespaces</a></li>
|
|
<li><a class="reference" href="#the-abstract-interface-to-dfs" id="id19" name="id19">2.2 The Abstract Interface to <tt class="docutils literal"><span class="pre">depth_first_search</span></tt></a></li>
|
|
<li><a class="reference" href="#defining-the-keywords" id="id20" name="id20">2.3 Defining the Keywords</a></li>
|
|
<li><a class="reference" href="#a-bare-bones-function-interface" id="id21" name="id21">2.4 A Bare Bones Function Interface</a><ul class="auto-toc">
|
|
<li><a class="reference" href="#the-signature" id="id22" name="id22">2.4.1 The Signature</a></li>
|
|
<li><a class="reference" href="#exercising-the-interface" id="id23" name="id23">2.4.2 Exercising the Interface</a></li>
|
|
<li><a class="reference" href="#signature-matching-and-overloading" id="id24" name="id24">2.4.3 Signature Matching and Overloading</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#filling-in-the-body" id="id25" name="id25">2.5 Filling in the Body</a></li>
|
|
<li><a class="reference" href="#adding-defaults" id="id26" name="id26">2.6 Adding Defaults</a><ul class="auto-toc">
|
|
<li><a class="reference" href="#syntax" id="id27" name="id27">2.6.1 Syntax</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#deducing-parameter-types" id="id28" name="id28">2.7 Deducing Parameter Types</a><ul class="auto-toc">
|
|
<li><a class="reference" href="#forwarding-to-an-implementation-function" id="id29" name="id29">2.7.1 Forwarding to an Implementation Function</a></li>
|
|
<li><a class="reference" href="#the-binding-metafunction" id="id30" name="id30">2.7.2 The <tt class="docutils literal"><span class="pre">binding</span></tt> <span class="concept">Metafunction</span></a></li>
|
|
<li><a class="reference" href="#binding-with-defaults" id="id31" name="id31">2.7.3 <tt class="docutils literal"><span class="pre">binding</span></tt> With Defaults</a></li>
|
|
<li><a class="reference" href="#binding-safely" id="id32" name="id32">2.7.4 <tt class="docutils literal"><span class="pre">binding</span></tt> Safely</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#beyond-ordinary-default-arguments" id="id33" name="id33">2.8 Beyond Ordinary Default Arguments</a></li>
|
|
<li><a class="reference" href="#more-restrictive-signatures" id="id34" name="id34">2.9 More Restrictive Signatures</a><ul class="auto-toc">
|
|
<li><a class="reference" href="#checking-for-convertibility-to-specific-types" id="id35" name="id35">2.9.1 Checking for Convertibility to Specific Types</a></li>
|
|
<li><a class="reference" href="#signature-restriction-predicates" id="id36" name="id36">2.9.2 Signature Restriction Predicates</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#efficiency-issues" id="id37" name="id37">2.10 Efficiency Issues</a><ul class="auto-toc">
|
|
<li><a class="reference" href="#eliminating-copies" id="id38" name="id38">2.10.1 Eliminating Copies</a></li>
|
|
<li><a class="reference" href="#lazy-default-computation" id="id39" name="id39">2.10.2 Lazy Default Computation</a></li>
|
|
<li><a class="reference" href="#dispatching-based-on-the-presence-of-a-default" id="id40" name="id40">2.10.3 Dispatching Based on the Presence of a Default</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#portability-considerations" id="id41" name="id41">3 Portability Considerations</a><ul class="auto-toc">
|
|
<li><a class="reference" href="#no-sfinae-support" id="id42" name="id42">3.1 No SFINAE Support</a></li>
|
|
<li><a class="reference" href="#no-support-for-result-of" id="id43" name="id43">3.2 No Support for <tt class="docutils literal"><span class="pre">result_of</span></tt></a></li>
|
|
<li><a class="reference" href="#compiler-can-t-see-references-in-unnamed-namespace" id="id44" name="id44">3.3 Compiler Can't See References In Unnamed Namespace</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#reference" id="id45" name="id45">4 Reference</a></li>
|
|
<li><a class="reference" href="#acknowledgements" id="id46" name="id46">5 Acknowledgements</a></li>
|
|
</ul>
|
|
</div>
|
|
<hr class="docutils" />
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id16" id="motivation" name="motivation">1 Motivation</a></h1>
|
|
<p>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:</p>
|
|
<ul>
|
|
<li><p class="first">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:</p>
|
|
<pre class="literal-block">
|
|
window* new_window(
|
|
char const* name,
|
|
<strong>int border_width = default_border_width,</strong>
|
|
bool movable = true,
|
|
bool initially_visible = true
|
|
);
|
|
|
|
const bool movability = false;
|
|
window* w = new_window("alert box", movability);
|
|
</pre>
|
|
<p>In the example above we wanted to make an unmoveable window
|
|
with a default <tt class="docutils literal"><span class="pre">border_width</span></tt>, but instead we got a moveable
|
|
window with a <tt class="docutils literal"><span class="pre">border_width</span></tt> of zero. To get the desired
|
|
effect, we'd need to write:</p>
|
|
<pre class="literal-block">
|
|
window* w = new_window(
|
|
"alert box", <strong>default_border_width</strong>, movability);
|
|
</pre>
|
|
</li>
|
|
<li><p class="first">It can become difficult for readers to understand the meaning of
|
|
arguments at the call site:</p>
|
|
<pre class="literal-block">
|
|
window* w = new_window("alert", 1, true, false);
|
|
</pre>
|
|
<p>Is this window moveable and initially invisible, or unmoveable
|
|
and initially visible? The reader needs to remember the order
|
|
of arguments to be sure.</p>
|
|
</li>
|
|
<li><p class="first">The author of the call may not remember the order of the
|
|
arguments either, leading to hard-to-find bugs.</p>
|
|
</li>
|
|
</ul>
|
|
<p>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:</p>
|
|
<pre class="literal-block">
|
|
window* w = new_window("alert box", <strong>movable=</strong>false); // OK!
|
|
</pre>
|
|
<p>It's not uncommon for a function to have parameters that can be
|
|
uniquely identified based on the types of arguments passed. The
|
|
<tt class="docutils literal"><span class="pre">name</span></tt> parameter to <tt class="docutils literal"><span class="pre">new_window</span></tt> is one such example. None of
|
|
the other arguments, if valid, can reasonably be converted to a
|
|
<tt class="docutils literal"><span class="pre">char</span> <span class="pre">const*</span></tt>, so in theory a user could pass the window name in
|
|
<em>any</em> argument position without causing ambiguity. The Parameter
|
|
library's <strong>unnamed parameter</strong> facility can be employed to allow
|
|
that usage:</p>
|
|
<pre class="literal-block">
|
|
window* w = new_window(movable=false, <strong>"alert box"</strong>); // OK!
|
|
</pre>
|
|
<p>Appropriately used, an unnamed parameter interface can free the
|
|
user of the burden of even remembering the formal parameter names.</p>
|
|
<p>The reasoning we've given for named and unnamed parameter
|
|
interfaces applies equally well to class templates as it does to
|
|
functions. The syntax for passing named template parameters is not
|
|
quite as natural as it is for named function parameters:</p>
|
|
<pre class="literal-block">
|
|
// <em>The ideal would be</em>
|
|
// <em>smart_ptr<ownership=shared, value_type=Client> p;</em>
|
|
//
|
|
// <em>but instead we must write something like:</em>
|
|
smart_ptr<<strong>ownership<shared></strong>, <strong>value_type<Client></strong> > p;
|
|
</pre>
|
|
<p>This small syntactic deficiency makes unnamed parameters an
|
|
especially big win when used with class templates:</p>
|
|
<pre class="literal-block">
|
|
// <em>p and q could be equivalent, given an unnamed</em>
|
|
// <em>parameter interface.</em>
|
|
smart_ptr<<strong>shared</strong>, <strong>Client</strong>> p;
|
|
smart_ptr<<strong>Client</strong>, <strong>shared</strong>> q;
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id17" id="tutorial" name="tutorial">2 Tutorial</a></h1>
|
|
<p>In this section we'll show how the Parameter library can be used to
|
|
build an expressive interface to the <a class="reference" href="../../../graph/index.html">Boost Graph library</a>'s
|
|
<a class="reference" href="../../../graph/doc/depth_first_search.html"><tt class="docutils literal"><span class="pre">depth_first_search</span></tt></a> algorithm.<a class="footnote-reference" href="#old-interface" id="id2" name="id2"><sup>1</sup></a></p>
|
|
<!-- Revisit this
|
|
|
|
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. -->
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id18" id="headers-and-namespaces" name="headers-and-namespaces">2.1 Headers And Namespaces</a></h2>
|
|
<p>Most components of the Parameter library are declared in a
|
|
header named for the component. For example,</p>
|
|
<pre class="literal-block">
|
|
#include <boost/parameter/keyword.hpp>
|
|
</pre>
|
|
<p>will ensure <tt class="docutils literal"><span class="pre">boost::parameter::keyword</span></tt> is known to the
|
|
compiler. There is also a combined header,
|
|
<tt class="docutils literal"><span class="pre">boost/parameter.hpp</span></tt>, 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 <tt class="docutils literal"><span class="pre">#include</span></tt> to access any given component of the library.</p>
|
|
<p>Also, the examples below will also be written as if the
|
|
namespace alias</p>
|
|
<pre class="literal-block">
|
|
namespace parameter = boost::parameter;
|
|
</pre>
|
|
<p>has been declared: we'll write <tt class="docutils literal"><span class="pre">parameter::xxx</span></tt> instead of
|
|
<tt class="docutils literal"><span class="pre">boost::parameter::xxx</span></tt>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id19" id="the-abstract-interface-to-dfs" name="the-abstract-interface-to-dfs">2.2 The Abstract Interface to <tt class="docutils literal"><span class="pre">depth_first_search</span></tt></a></h2>
|
|
<p>The Graph library's <tt class="docutils literal"><span class="pre">depth_first_search</span></tt> algorithm is a generic function accepting
|
|
from one to four arguments by reference. If all arguments were
|
|
required, its signature might be as follows:</p>
|
|
<pre class="literal-block">
|
|
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);
|
|
</pre>
|
|
<p>However, most of the parameters have a useful default value, as
|
|
shown in the table below.</p>
|
|
<table border="1" class="docutils" id="default-expressions">
|
|
<span id="parameter-table"></span><caption><a id="default-expressions" name="default-expressions"><span id="parameter-table"></span><tt class="docutils literal"><span class="pre">depth_first_search</span></tt> Parameters</a></caption>
|
|
<colgroup>
|
|
<col width="27%" />
|
|
<col width="17%" />
|
|
<col width="57%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">Parameter Name</th>
|
|
<th class="head">Dataflow</th>
|
|
<th class="head">Default Value (if any)</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="docutils literal"><span class="pre">graph</span></tt></td>
|
|
<td>in</td>
|
|
<td>none - this argument is required.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">visitor</span></tt></td>
|
|
<td>in</td>
|
|
<td><tt class="docutils literal"><span class="pre">boost::dfs_visitor<>()</span></tt></td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">root_vertex</span></tt></td>
|
|
<td>in</td>
|
|
<td><tt class="docutils literal"><span class="pre">*vertices(graph).first</span></tt></td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">index_map</span></tt></td>
|
|
<td>in</td>
|
|
<td><tt class="docutils literal"><span class="pre">get(boost::vertex_index,graph)</span></tt></td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">color_map</span></tt></td>
|
|
<td>out</td>
|
|
<td>an <tt class="docutils literal"><span class="pre">iterator_property_map</span></tt>
|
|
created from a <tt class="docutils literal"><span class="pre">std::vector</span></tt> of
|
|
<tt class="docutils literal"><span class="pre">default_color_type</span></tt> of size
|
|
<tt class="docutils literal"><span class="pre">num_vertices(graph)</span></tt> and using
|
|
<tt class="docutils literal"><span class="pre">index_map</span></tt> for the index map.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>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 <tt class="docutils literal"><span class="pre">color_map</span></tt> is
|
|
computed later in the tutorial; trust us when we say that the
|
|
complexity of its default will become valuable.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id20" id="defining-the-keywords" name="defining-the-keywords">2.3 Defining the Keywords</a></h2>
|
|
<p>The point of this exercise is to make it possible to call
|
|
<tt class="docutils literal"><span class="pre">depth_first_search</span></tt> with keyword arguments, leaving out any
|
|
arguments for which the default is appropriate:</p>
|
|
<pre class="literal-block">
|
|
graphs::depth_first_search(g, <strong>color_map=my_color_map</strong>);
|
|
</pre>
|
|
<p>To make that syntax legal, there needs to be an object called
|
|
<tt class="docutils literal"><span class="pre">color_map</span></tt> with an assignment operator that can accept a
|
|
<tt class="docutils literal"><span class="pre">my_color_map</span></tt> argument. In this step we'll create one such
|
|
<strong>keyword object</strong> for each parameter. Each keyword object will be
|
|
identified by a unique <strong>keyword tag type</strong>.</p>
|
|
<p>We're going to define our interface in namespace <tt class="docutils literal"><span class="pre">graphs</span></tt>. Since
|
|
users need access to the keyword objects, but not the tag types,
|
|
we'll define the keyword objects so they're acceessible through
|
|
<tt class="docutils literal"><span class="pre">graphs</span></tt>, and we'll hide the tag types away in a tested
|
|
namespace, <tt class="docutils literal"><span class="pre">graphs::tag</span></tt>. The library provides a convenient
|
|
macro for that purpose (MSVC6.x users see this <a class="reference" href="#compiler-can-t-see-references-in-unnamed-namespace">note</a>):</p>
|
|
<pre class="literal-block">
|
|
#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)
|
|
}
|
|
</pre>
|
|
<p>The declaration of the <tt class="docutils literal"><span class="pre">visitor</span></tt> keyword you see here is
|
|
equivalent to:</p>
|
|
<pre class="literal-block">
|
|
namespace graphs
|
|
{
|
|
namespace tag
|
|
{
|
|
// The tag type
|
|
struct visitor;
|
|
}
|
|
|
|
namespace // unnamed
|
|
{
|
|
// A reference to the tag object
|
|
boost::parameter::keyword<tag::visitor>& visitor
|
|
= boost::parameter::keyword<tag::visitor>::instance;
|
|
}
|
|
}
|
|
</pre>
|
|
<p>This “fancy dance” involving the unnamed namespace and references
|
|
is all done to avoid violating the One Definition Rule (ODR)<a class="footnote-reference" href="#odr" id="id5" name="id5"><sup>2</sup></a> when the named parameter interface is used by function
|
|
templates that are instantiated in multiple translation
|
|
units.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id21" id="a-bare-bones-function-interface" name="a-bare-bones-function-interface">2.4 A Bare Bones Function Interface</a></h2>
|
|
<p>Next we can write the skeleton of our <tt class="docutils literal"><span class="pre">depth_first_search</span></tt>
|
|
function template. To declare the function, we'll use the
|
|
<tt class="docutils literal"><span class="pre">BOOST_PARAMETER_FUNCTION</span></tt> macro:</p>
|
|
<pre class="literal-block">
|
|
#include <boost/parameter/preprocessor.hpp>
|
|
|
|
namespace graphs
|
|
{
|
|
BOOST_PARAMETER_FUNCTION(
|
|
(void),
|
|
depth_first_search,
|
|
|
|
tag,
|
|
(required (graph,*) )
|
|
(optional (visitor,*) (root_vertex,*)
|
|
(index_map,*) (out(color_map),*) )
|
|
)
|
|
{
|
|
// ... body of function goes here...
|
|
}
|
|
}
|
|
</pre>
|
|
<p>The first argument to <tt class="docutils literal"><span class="pre">BOOST_PARAMETER_FUNCTION</span></tt> is the
|
|
function's return type, in parentheses. These parentheses are
|
|
necessary because some types, such as <tt class="docutils literal"><span class="pre">std::pair<int,int></span></tt>,
|
|
contain commas that would otherwise confuse the preprocessor. The
|
|
second argument is the name of the resulting function template.
|
|
The third argument is the name of the namespace in which keyword
|
|
types can be found, but most of the interesting information is in
|
|
the fourth argument, which describes the function signature.</p>
|
|
<div class="section">
|
|
<h3><a class="toc-backref" href="#id22" id="the-signature" name="the-signature">2.4.1 The Signature</a></h3>
|
|
<p>The fourth argument to <tt class="docutils literal"><span class="pre">BOOST_PARAMETER_FUNCTION</span></tt> is a
|
|
<a class="reference" href="../../preprocessor">Boost.Preprocessor</a> <a class="reference" href="../../preprocessor/doc/data/sequences.html">sequence</a> of two elements, describing the
|
|
required and optional parameters to <tt class="docutils literal"><span class="pre">depth_first_search</span></tt>,
|
|
respectively (if the parameters were all required—or all
|
|
optional—the sequence would have had only one element). The first
|
|
element specifies a single <tt class="docutils literal"><span class="pre">required</span></tt> parameter, <tt class="docutils literal"><span class="pre">graph</span></tt>:</p>
|
|
<pre class="literal-block">
|
|
(required (graph,*) )
|
|
</pre>
|
|
<p>The <tt class="docutils literal"><span class="pre">*</span></tt> simply indicates that we can pass anything at all to
|
|
<tt class="docutils literal"><span class="pre">depth_first_search</span></tt> as a <tt class="docutils literal"><span class="pre">graph</span></tt>. The second element of the
|
|
outer sequence lists the <tt class="docutils literal"><span class="pre">optional</span></tt> arguments.
|
|
Since there are multiple optional arguments, their entries are
|
|
composed into another <a class="reference" href="../../preprocessor/doc/data/sequences.html">sequence</a>. Note that since the <tt class="docutils literal"><span class="pre">color_map</span></tt> is an
|
|
“out” parameter, its name has been enclosed in the <tt class="docutils literal"><span class="pre">out(…)</span></tt>
|
|
construct, which indicates to the library that it should be passed
|
|
by non-const reference (for an “in/out” parameter we'd use
|
|
<tt class="docutils literal"><span class="pre">in_out(…)</span></tt>). If you refer back to the <a class="reference" href="#parameter-table">parameter table</a> it
|
|
should be clear that, default values aside, this function signature
|
|
describes the same information.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h3><a class="toc-backref" href="#id23" id="exercising-the-interface" name="exercising-the-interface">2.4.2 Exercising the Interface</a></h3>
|
|
<p>We've already gained the ability to call our function with a
|
|
mixture of positional and named arguments:</p>
|
|
<pre class="literal-block">
|
|
int main()
|
|
{
|
|
// Make keyword names available without qualification
|
|
using namespace graphs;
|
|
|
|
graphs::depth_first_search(
|
|
'G', 'v', // Positional args
|
|
index_map = "hello, world", // Named args in
|
|
root_vertex = 3.5, color_map = false); // arbitrary order
|
|
}
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h3><a class="toc-backref" href="#id24" id="signature-matching-and-overloading" name="signature-matching-and-overloading">2.4.3 Signature Matching and Overloading</a></h3>
|
|
<p>We can also observe the effects of using <tt class="docutils literal"><span class="pre">required</span></tt> and
|
|
<tt class="docutils literal"><span class="pre">optional</span></tt> in the function signature. Any invocation of
|
|
<tt class="docutils literal"><span class="pre">depth_first_search</span></tt> will compile, as long as it has a <tt class="docutils literal"><span class="pre">graph</span></tt>
|
|
parameter:</p>
|
|
<pre class="literal-block">
|
|
depth_first_search("some-graph"); // OK
|
|
depth_first_search(index_map="hello, world", graph='G'); // OK
|
|
</pre>
|
|
<p>however, if we leave out the graph argument, the compiler will
|
|
complain that no <tt class="docutils literal"><span class="pre">depth_first_search</span></tt> matches the arguments:</p>
|
|
<pre class="literal-block">
|
|
depth_first_search(root_vertex=3.5); // ERROR
|
|
</pre>
|
|
<p>It's important to note that the parameter library is not forcing a
|
|
compilation error in this case. If we add another overload of
|
|
<tt class="docutils literal"><span class="pre">depth_first_search</span></tt> that <em>does</em> match, the compiler will be
|
|
happy again:</p>
|
|
<pre class="literal-block">
|
|
// New overload; matches anything
|
|
template <class T> void depth_first_search(T) {}
|
|
|
|
depth_first_search(root_vertex=3.5); // OK
|
|
</pre>
|
|
<p>This capability depends on your compiler's support for SFINAE.<a class="footnote-reference" href="#sfinae" id="id6" name="id6"><sup>6</sup></a></p>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id25" id="filling-in-the-body" name="filling-in-the-body">2.5 Filling in the Body</a></h2>
|
|
<p>Of course, the test above isn't very interesting unless we can see
|
|
the values of the arguments. Just to get a feel for how things
|
|
work, let's add some temporary code to print the arguments. The
|
|
most natural approach would be to access the arguments directly, by
|
|
name:</p>
|
|
<pre class="literal-block">
|
|
{
|
|
std::cout << "graph:\\t" << graph << std::endl;
|
|
std::cout << "visitor:\\t" << visitor << std::endl;
|
|
std::cout << "root_vertex:\\t" << root_vertex << std::endl;
|
|
std::cout << "index_map:\\t" << index_map << std::endl;
|
|
std::cout << "color_map:\\t" << color_map << std::endl;
|
|
}
|
|
</pre>
|
|
<p>Unfortunately, that won't quite work, because the function whose
|
|
body we'll be writing doesn't have parameters named <tt class="docutils literal"><span class="pre">graph</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">visitor</span></tt>, etc. It may not be obvious, since the declaration is
|
|
generated by the <tt class="docutils literal"><span class="pre">BOOST_PARAMETER_FUNCTION</span></tt> macro, but there is
|
|
actually only a single parameter, called <tt class="docutils literal"><span class="pre">args</span></tt>. <tt class="docutils literal"><span class="pre">args</span></tt> is what
|
|
is known as an <span class="concept">ArgumentPack</span>: a bundle of references to the actual
|
|
arguments, tagged with their keywords. To extract each parameter,
|
|
we just need to pass its keyword object to the <span class="concept">ArgumentPack</span>'s
|
|
subscript operator, like this:</p>
|
|
<pre class="literal-block">
|
|
namespace graphs
|
|
{
|
|
BOOST_PARAMETER_FUNCTION(
|
|
(void),
|
|
depth_first_search,
|
|
|
|
tag,
|
|
(required (graph,*) )
|
|
(optional (visitor,*) (root_vertex,*)
|
|
(index_map,*) (out(color_map),*) )
|
|
)
|
|
{
|
|
std::cout << "graph:\t" << <strong>args[graph]</strong> << std::endl;
|
|
std::cout << "visitor:\t" << <strong>args[visitor]</strong> << std::endl;
|
|
std::cout << "root_vertex:\t" << <strong>args[root_vertex]</strong> << std::endl;
|
|
std::cout << "index_map:\t" << <strong>args[index_map]</strong> << std::endl;
|
|
std::cout << "color_map:\t" << <strong>args[color_map]</strong> << std::endl;
|
|
}
|
|
}
|
|
</pre>
|
|
<p>Now our program will print:</p>
|
|
<pre class="literal-block">
|
|
graph: G
|
|
visitor: 2
|
|
root_vertex: 3.5
|
|
index_map: hello, world
|
|
color_map: false
|
|
</pre>
|
|
<p>Of course, we can pass the arguments in any order without changing
|
|
the result:</p>
|
|
<pre class="literal-block">
|
|
int main()
|
|
{
|
|
using namespace graphs;
|
|
|
|
graphs::depth_first_search(
|
|
root_vertex = 3.5, graph = 'G', color_map = false,
|
|
index_map = "hello, world", visitor = 2);
|
|
}
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id26" id="adding-defaults" name="adding-defaults">2.6 Adding Defaults</a></h2>
|
|
<p>Despite the use of <tt class="docutils literal"><span class="pre">optional</span></tt> in the signature, all
|
|
the arguments to <tt class="docutils literal"><span class="pre">depth_first_search</span></tt> are actually required. If
|
|
any parameter can't be found, there will be a compilation error
|
|
where we try to extract it from the <span class="concept">ArgumentPack</span> using the
|
|
subscript operator. To make it legal to omit an argument we need
|
|
to give it a default value.</p>
|
|
<div class="section">
|
|
<h3><a class="toc-backref" href="#id27" id="syntax" name="syntax">2.6.1 Syntax</a></h3>
|
|
<p>To make an optional parameter <em>truly</em> optional, we can follow its keyword
|
|
with the <tt class="docutils literal"><span class="pre">|</span></tt> operator and the parameter's default value within
|
|
the square brackets. In the following example, we've given
|
|
<tt class="docutils literal"><span class="pre">root_vertex</span></tt> a default of <tt class="docutils literal"><span class="pre">42</span></tt> and <tt class="docutils literal"><span class="pre">color_map</span></tt> a default of
|
|
<tt class="docutils literal"><span class="pre">"hello,</span> <span class="pre">world"</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
namespace graphs
|
|
{
|
|
{
|
|
BOOST_PARAMETER_FUNCTION(
|
|
(void),
|
|
depth_first_search,
|
|
|
|
tag,
|
|
(required (graph,*) )
|
|
(optional (visitor,*) (root_vertex,*)
|
|
(index_map,*) (out(color_map),*) )
|
|
)
|
|
{
|
|
std::cout << "graph:\t" << args[graph] << std::endl;
|
|
std::cout << "visitor:\t" << args[visitor] << std::endl;
|
|
std::cout << "root_vertex:\t" << args[root_vertex<strong>|42</strong>] << std::endl;
|
|
std::cout << "index_map:\t" << args[index_map] << std::endl;
|
|
std::cout << "color_map:\t" << args[color_map<strong>|"hello, world"</strong>] << std::endl;
|
|
}
|
|
}
|
|
</pre>
|
|
<p>Now we can invoke the function without supplying <tt class="docutils literal"><span class="pre">color_map</span></tt> or
|
|
<tt class="docutils literal"><span class="pre">root_vertex</span></tt>:</p>
|
|
<pre class="literal-block">
|
|
graphs::depth_first_search(
|
|
graph = 'G', index_map = "index", visitor = 6);
|
|
</pre>
|
|
<p>The call above would print:</p>
|
|
<pre class="literal-block">
|
|
graph: G
|
|
visitor: 6
|
|
root_vertex: 42
|
|
index_map: index
|
|
color_map: hello, world
|
|
</pre>
|
|
<div class="important">
|
|
<p class="first admonition-title">Important</p>
|
|
<p class="last">The index expression <tt class="docutils literal"><span class="pre">args[…]</span></tt> always yields a <em>reference</em>
|
|
that is bound either to the actual argument passed by the caller
|
|
or, if no argument is passed explicitly, to the specified
|
|
default value.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id28" id="deducing-parameter-types" name="deducing-parameter-types">2.7 Deducing Parameter Types</a></h2>
|
|
<p>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.</p>
|
|
<p>Instead, we'll connect local variables to the arguments and use
|
|
those in our algorithm:</p>
|
|
<pre class="literal-block">
|
|
namespace graphs
|
|
{
|
|
BOOST_PARAMETER_FUNCTION(
|
|
(void),
|
|
depth_first_search,
|
|
|
|
tag,
|
|
(required (graph,*) )
|
|
(optional (visitor,*) (root_vertex,*)
|
|
(index_map,*) (out(color_map),*) )
|
|
)
|
|
{
|
|
<em>Graph</em> g = args[graph];
|
|
<em>Visitor</em> v = args[visitor|<em>default-expression</em><sub>1</sub>];
|
|
<em>Vertex</em> s = args[root_vertex|<em>default-expression</em><sub>2</sub>];
|
|
<em>Index</em> i = args[index_map|<em>default-expression</em><sub>3</sub>];
|
|
<em>Color</em> c = args[color|<em>default-expression</em><sub>4</sub>];
|
|
|
|
<em>…use g, v, s, i, and c to implement the algorithm…</em>
|
|
}
|
|
}
|
|
</pre>
|
|
<p>We'll insert the <a class="reference" href="#default-expressions">default expressions</a> in a moment, but first we
|
|
need to come up with the types <em>Graph</em>, <em>Visitor</em>, <em>Vertex</em>,
|
|
<em>Index</em>, and <em>Color</em>.</p>
|
|
<div class="section">
|
|
<h3><a class="toc-backref" href="#id29" id="forwarding-to-an-implementation-function" name="forwarding-to-an-implementation-function">2.7.1 Forwarding to an Implementation Function</a></h3>
|
|
<p>The easiest way to discover the parameter types is to forward them
|
|
on to another function template and allow C++ to do the type
|
|
deduction for us:</p>
|
|
<pre class="literal-block">
|
|
namespace graphs
|
|
{
|
|
namespace detail
|
|
{
|
|
template <
|
|
class Graph, class Visitor
|
|
, class Vertex, class Index, class Color>
|
|
void depth_first_search_impl(
|
|
Graph const& g, Visitor const& v,
|
|
Vertex const& s, Index const& i, Color& c)
|
|
{
|
|
<em>…use g, v, s, i, and c to implement the algorithm…</em>
|
|
}
|
|
}
|
|
|
|
BOOST_PARAMETER_FUNCTION(
|
|
(void),
|
|
depth_first_search,
|
|
|
|
tag,
|
|
(required (graph,*) )
|
|
(optional (visitor,*) (root_vertex,*)
|
|
(index_map,*) (out(color_map),*) )
|
|
)
|
|
{
|
|
detail::depth_first_search_impl(
|
|
args[graph], args[visitor|<em>default-expression</em><sub>1</sub>],
|
|
args[root_vertex|<em>default-expression</em><sub>2</sub>],
|
|
args[index_map|<em>default-expression</em><sub>3</sub>],
|
|
args[color|<em>default-expression</em><sub>4</sub>]);
|
|
}
|
|
}
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h3><a id="the-binding-metafunction" name="the-binding-metafunction">2.7.2 The <tt class="docutils literal"><span class="pre">binding</span></tt> <a class="reference" href="../../../mpl/doc/refmanual/metafunction.html"><span class="concept">Metafunction</span></a></a></h3>
|
|
<p>If for some reason forwarding isn't an option, or if writing a
|
|
separate implementation function is too cumbersome, we can use a
|
|
<a class="reference" href="../../../mpl/doc/refmanual/metafunction.html"><span class="concept">Metafunction</span></a> called <tt class="docutils literal"><span class="pre">binding</span></tt> to compute parameter types
|
|
directly:</p>
|
|
<pre class="literal-block">
|
|
binding<ArgumentPack, Keyword, Default = parameter::void_>
|
|
{ typedef <em>see text</em> type; };
|
|
</pre>
|
|
<p>where <tt class="docutils literal"><span class="pre">Default</span></tt> is the type of the default argument, if any.</p>
|
|
<p>To use <tt class="docutils literal"><span class="pre">binding</span></tt> we need one more piece of information that's
|
|
hidden by the macro generating our declaration: the <em>type</em> of
|
|
<tt class="docutils literal"><span class="pre">args</span></tt>, our ArgumentPack, is quite fittingly available as
|
|
<tt class="docutils literal"><span class="pre">Args</span></tt>. Now, to directly declare and initialize <tt class="docutils literal"><span class="pre">g</span></tt>, we could
|
|
write:</p>
|
|
<pre class="literal-block">
|
|
typedef typename parameter::binding<
|
|
Args,<strong>tag::graph</strong>
|
|
>::type Graph;
|
|
|
|
Graph g = args[graph];
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h3><a class="toc-backref" href="#id31" id="binding-with-defaults" name="binding-with-defaults">2.7.3 <tt class="docutils literal"><span class="pre">binding</span></tt> With Defaults</a></h3>
|
|
<p>As shown in the <a class="reference" href="#parameter-table">parameter table</a>, <tt class="docutils literal"><span class="pre">graph</span></tt> has no default, so
|
|
the <tt class="docutils literal"><span class="pre">binding</span></tt> invocation for <em>Graph</em> takes only two arguments.
|
|
The default <tt class="docutils literal"><span class="pre">visitor</span></tt> is <tt class="docutils literal"><span class="pre">boost::dfs_visitor<>()</span></tt>, so the
|
|
<tt class="docutils literal"><span class="pre">binding</span></tt> invocation for <em>Visitor</em> takes three arguments:</p>
|
|
<pre class="literal-block">
|
|
typedef typename parameter::binding<
|
|
Args,<strong>tag::visitor,boost::dfs_visitor<></strong>
|
|
>::type Visitor;
|
|
|
|
Visitor v = args[visitor|<strong>boost::dfs_visitor<>()</strong>];
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h3><a class="toc-backref" href="#id32" id="binding-safely" name="binding-safely"><span id="dangling"></span>2.7.4 <tt class="docutils literal"><span class="pre">binding</span></tt> Safely</a></h3>
|
|
<p>Note that the default <tt class="docutils literal"><span class="pre">visitor</span></tt> is supplied as a <em>temporary</em>
|
|
instance of <tt class="docutils literal"><span class="pre">dfs_visitor</span></tt>. Because <tt class="docutils literal"><span class="pre">args[…]</span></tt> always yields
|
|
a reference, making <tt class="docutils literal"><span class="pre">v</span></tt> a reference would cause it to bind to
|
|
that temporary, and immediately dangle. Therefore, it's crucial
|
|
that we passed <tt class="docutils literal"><span class="pre">dfs_visitor<></span></tt>, and not <tt class="docutils literal"><span class="pre">dfs_visitor<></span>
|
|
<span class="pre">const&</span></tt>, as the last argument to <tt class="docutils literal"><span class="pre">binding</span></tt>.</p>
|
|
<div class="important">
|
|
<p class="first admonition-title">Important</p>
|
|
<p class="last">Never pass <tt class="docutils literal"><span class="pre">binding</span></tt> a reference type as the default unless
|
|
you know that the default value passed to the <span class="concept">ArgumentPack</span>'s
|
|
indexing operator will outlive the reference you'll bind to it.</p>
|
|
</div>
|
|
<p>Sometimes there's no need to use <tt class="docutils literal"><span class="pre">binding</span></tt> at all. The
|
|
<tt class="docutils literal"><span class="pre">root_vertex</span></tt> argument is required to be of the graph's
|
|
<tt class="docutils literal"><span class="pre">vertex_descriptor</span></tt> type,<a class="footnote-reference" href="#vertex-descriptor" id="id7" name="id7"><sup>3</sup></a> so we can just
|
|
declare it that way:</p>
|
|
<pre class="literal-block">
|
|
typename <strong>boost::graph_traits<Graph>::vertex_descriptor</strong>
|
|
s = args[root_vertex|<strong>*vertices(g).first</strong>];
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id33" id="beyond-ordinary-default-arguments" name="beyond-ordinary-default-arguments">2.8 Beyond Ordinary Default Arguments</a></h2>
|
|
<p>Consider how one might bind a variable to the <tt class="docutils literal"><span class="pre">index_map</span></tt>
|
|
parameter:</p>
|
|
<pre class="literal-block">
|
|
typedef typename parameter::binding<
|
|
ArgumentPack
|
|
, <a class="reference" href="tag::index_map">tag::index_map</a>
|
|
, <strong>typename boost::property_map<Graph, vertex_index_t>::const_type</strong>
|
|
>::type Index;
|
|
|
|
Index i = args[index_map|<strong>get(boost::vertex_index,g)</strong>];
|
|
</pre>
|
|
<p>We have gained two capabilities beyond what plain C++ default
|
|
arguments provide:</p>
|
|
<ol class="arabic">
|
|
<li><p class="first">The default value of the <tt class="docutils literal"><span class="pre">index</span></tt> parameter depends on the
|
|
value of the <tt class="docutils literal"><span class="pre">graph</span></tt> parameter. That's illegal in plain C++:</p>
|
|
<pre class="literal-block">
|
|
void f(int <strong>graph</strong>, int index = <strong>graph</strong> + 1); // error
|
|
</pre>
|
|
</li>
|
|
<li><p class="first">The <tt class="docutils literal"><span class="pre">index</span></tt> parameter has a useful default, yet it is
|
|
templated and its type can be deduced when an <tt class="docutils literal"><span class="pre">index</span></tt>
|
|
argument is explicitly specified by the caller. In plain C++, you
|
|
can <em>specify</em> a default value for a parameter with deduced type,
|
|
but it's not very useful:</p>
|
|
<pre class="literal-block">
|
|
template <class Index>
|
|
int f(Index index <strong>= 42</strong>); // OK
|
|
int y = f(); // <strong>error; can't deduce Index</strong>
|
|
</pre>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id34" id="more-restrictive-signatures" name="more-restrictive-signatures">2.9 More Restrictive Signatures</a></h2>
|
|
<p>Currently, our function will be considered for overload resolution
|
|
whenever``depth_first_search`` is called with a <tt class="docutils literal"><span class="pre">graph</span></tt> argument
|
|
and up to four others, of any type. Compilation may fail inside
|
|
our <tt class="docutils literal"><span class="pre">depth_first_search</span></tt> when it is instantiated if the compiler
|
|
discovers that the argument types don't provide the required
|
|
operations, but that may be too late:</p>
|
|
<ul class="simple">
|
|
<li>By the time our <tt class="docutils literal"><span class="pre">depth_first_search</span></tt> is instantiated, it has
|
|
been selected as the best matching overload. Some other
|
|
<tt class="docutils literal"><span class="pre">depth_first_search</span></tt> 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.</li>
|
|
<li>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 <tt class="docutils literal"><span class="pre">graphs::detail::depth_first_search_impl</span></tt> or worse (think
|
|
of the kinds of errors you get from your STL implementation when
|
|
you make a mistake).</li>
|
|
<li>The problems with exposing such permissive function template
|
|
signatures have been the subject of much discussion, especially
|
|
in the presence of <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-defects.html#225">unqualified calls</a>. If all we want is to
|
|
avoid unintentional argument-dependent lookup (ADL), we can
|
|
isolate <tt class="docutils literal"><span class="pre">depth_first_search</span></tt> in a namespace containing no
|
|
types<a class="footnote-reference" href="#using" id="id8" name="id8"><sup>5</sup></a>, but suppose we <em>want</em> it to found via ADL?</li>
|
|
</ul>
|
|
<p>It's usually a good idea to prevent functions from being considered
|
|
for overload resolution when the passed argument types aren't
|
|
appropriate. We've already seen that the library does this when
|
|
the required <tt class="docutils literal"><span class="pre">graph</span></tt> parameter is not supplied.</p>
|
|
<div class="section">
|
|
<h3><a class="toc-backref" href="#id35" id="checking-for-convertibility-to-specific-types" name="checking-for-convertibility-to-specific-types">2.9.1 Checking for Convertibility to Specific Types</a></h3>
|
|
<p>The simplest way to make the signature more restrictive is to
|
|
replace some of the <tt class="docutils literal"><span class="pre">*</span></tt>s with types to which the corresponding
|
|
arguments must be convertible, in parentheses. For example, the
|
|
following signature will only be matched when the
|
|
<tt class="docutils literal"><span class="pre">graph</span></tt> parameter is convertible to <tt class="docutils literal"><span class="pre">char</span> <span class="pre">const*</span></tt> and the
|
|
<tt class="docutils literal"><span class="pre">root_vertex</span></tt> parameter is convertible to <tt class="docutils literal"><span class="pre">int</span></tt>:</p>
|
|
<pre class="literal-block">
|
|
namespace graphs
|
|
{
|
|
BOOST_PARAMETER_FUNCTION(
|
|
(void),
|
|
depth_first_search,
|
|
|
|
tag,
|
|
(required (graph,<strong>(char const*)</strong>) )
|
|
(optional (visitor,*) (root_vertex,<strong>(int)</strong>)
|
|
(index_map,*) (out(color_map),*) )
|
|
)
|
|
{
|
|
<em>…</em>
|
|
}
|
|
}
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h3><a class="toc-backref" href="#id36" id="signature-restriction-predicates" name="signature-restriction-predicates">2.9.2 Signature Restriction Predicates</a></h3>
|
|
<p>Sometimes the appropriate restriction can't be expressed in terms
|
|
of convertibility. In that case, instead of replacing the <tt class="docutils literal"><span class="pre">*</span></tt>,
|
|
you can <em>follow</em> it with a parenthesized unary <a class="reference" href="../../../mpl/doc/refmanual/lambda-expression.html">MPL lambda
|
|
expression</a> that, when applied to the actual type of the argument,
|
|
indicates whether that argument type meets the function's
|
|
requirements for that parameter position.</p>
|
|
<p>For example, if we want to require that the <tt class="docutils literal"><span class="pre">visitor</span></tt> parameter
|
|
be derived from some class <tt class="docutils literal"><span class="pre">VBase</span></tt>, we can write:</p>
|
|
<pre class="literal-block">
|
|
namespace graphs
|
|
{
|
|
using namespace boost::mpl;
|
|
|
|
BOOST_PARAMETER_FUNCTION(
|
|
(void),
|
|
depth_first_search,
|
|
|
|
tag,
|
|
(required (graph,(char const*)) )
|
|
(optional (visitor,<strong>*(boost::is_base_and_derived<VBase,_>)</strong>)
|
|
(root_vertex,(int)) (index_map,*) (out(color_map),*) )
|
|
)
|
|
{
|
|
<em>…</em>
|
|
}
|
|
}
|
|
</pre>
|
|
<div class="note">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">The restrictions implemented in this section are not realistic
|
|
ones for use with the graph library, and further examples are
|
|
written under the assumption that no such restrictions are in
|
|
effect.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id37" id="efficiency-issues" name="efficiency-issues">2.10 Efficiency Issues</a></h2>
|
|
<p>The <tt class="docutils literal"><span class="pre">color_map</span></tt> parameter gives us a few efficiency issues to
|
|
consider. Here's a first cut at extraction and binding:</p>
|
|
<pre class="literal-block">
|
|
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|<strong>default_color_map(num_vertices(g),i)</strong>];
|
|
</pre>
|
|
<div class="section">
|
|
<h3><a class="toc-backref" href="#id38" id="eliminating-copies" name="eliminating-copies">2.10.1 Eliminating Copies</a></h3>
|
|
<p>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 <tt class="docutils literal"><span class="pre">binding<…,k,…>::type</span></tt> is always a reference type when the
|
|
<em>k</em> parameter is supplied by the caller. Since <tt class="docutils literal"><span class="pre">args[…]</span></tt>
|
|
yields a reference to the actual argument, <tt class="docutils literal"><span class="pre">color</span></tt> will be bound
|
|
to the actual <tt class="docutils literal"><span class="pre">color_map</span></tt> argument and no copying will be done.</p>
|
|
<p>As described <a class="reference" href="#dangling">above</a>, because the default is a temporary, it's
|
|
important that <tt class="docutils literal"><span class="pre">color</span></tt> be a non-reference when the default is
|
|
used. In that case, the default value will be <em>copied</em> into
|
|
<tt class="docutils literal"><span class="pre">color</span></tt>. If we store the default in a named variable, though,
|
|
<tt class="docutils literal"><span class="pre">color</span></tt> can be a reference, thereby eliminating the copy:</p>
|
|
<pre class="literal-block">
|
|
default_color_map default_color(num_vertices(g),i);
|
|
|
|
typename parameter::binding<
|
|
ArgumentPack
|
|
, <a class="reference" href="tag::color_map">tag::color_map</a>
|
|
, <strong>default_color_map&</strong>
|
|
>::type color = args[color_map|default_color];
|
|
</pre>
|
|
<div class="hint">
|
|
<p class="first admonition-title">Hint</p>
|
|
<p class="last">To avoid making needless copies, pass a <em>reference to the
|
|
default type</em> as the third argument to <tt class="docutils literal"><span class="pre">binding</span></tt>, and store
|
|
the default value in a <em>named</em> variable.</p>
|
|
</div>
|
|
<p>That said,</p>
|
|
<div class="note">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">The extra copy becomes a non-issue if we just use the
|
|
<a class="reference" href="#forwarding-to-an-implementation-function">forwarding</a> technique described earlier.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h3><a class="toc-backref" href="#id39" id="lazy-default-computation" name="lazy-default-computation">2.10.2 Lazy Default Computation</a></h3>
|
|
<p>Of course it's nice to avoid copying <tt class="docutils literal"><span class="pre">default_color</span></tt>, but the
|
|
more important cost is that of <em>constructing</em> it in the first
|
|
place. A <tt class="docutils literal"><span class="pre">vector_property_map</span></tt> is cheap to copy, since it holds
|
|
its elements via a <a class="reference" href="../../../smart_ptr/shared_ptr.htm"><tt class="docutils literal"><span class="pre">shared_ptr</span></tt></a>. On the other hand, construction of
|
|
<tt class="docutils literal"><span class="pre">default_color</span></tt> costs at least two dynamic memory allocations and
|
|
<tt class="docutils literal"><span class="pre">num_vertices(g)</span></tt> copies; it would be better to avoid doing this
|
|
work when the default value won't be needed.</p>
|
|
<p>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 <tt class="docutils literal"><span class="pre">|</span></tt> operator, we'll use <tt class="docutils literal"><span class="pre">||</span></tt> and follow it with a
|
|
nullary (zero-argument) function object that constructs a
|
|
default_color_map. Here, we build the function object using
|
|
<a class="reference" href="../../../lambda/index.html">Boost.Lambda</a>:<a class="footnote-reference" href="#bind" id="id11" name="id11"><sup>4</sup></a></p>
|
|
<pre class="literal-block">
|
|
// After #include <boost/lambda/construct.hpp>
|
|
typename parameter::binding<
|
|
ArgumentPack
|
|
, <a class="reference" href="tag::color_map">tag::color_map</a>
|
|
, default_color_map
|
|
>::type color = args[
|
|
color_map
|
|
<strong>|| boost::lambda::construct<default_color_map>(num_vertices(g),i)</strong>
|
|
];
|
|
</pre>
|
|
<div class="sidebar">
|
|
<p class="first sidebar-title">Mnemonics</p>
|
|
<p class="last">To remember the difference between <tt class="docutils literal"><span class="pre">|</span></tt> and <tt class="docutils literal"><span class="pre">||</span></tt>, recall that
|
|
<tt class="docutils literal"><span class="pre">||</span></tt> normally uses short-circuit evaluation: its second
|
|
argument is only evaluated if its first argument is <tt class="docutils literal"><span class="pre">false</span></tt>.
|
|
Similarly, in <tt class="docutils literal"><span class="pre">color_map[param||f]</span></tt>, <tt class="docutils literal"><span class="pre">f</span></tt> is only invoked if
|
|
no <tt class="docutils literal"><span class="pre">color_map</span></tt> argument was supplied.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h3><a class="toc-backref" href="#id40" id="dispatching-based-on-the-presence-of-a-default" name="dispatching-based-on-the-presence-of-a-default">2.10.3 Dispatching Based on the Presence of a Default</a></h3>
|
|
<p>In fact, the Graph library itself constructs a slightly different
|
|
<tt class="docutils literal"><span class="pre">color_map</span></tt>, to avoid even the overhead of initializing a
|
|
<a class="reference" href="../../../smart_ptr/shared_ptr.htm"><tt class="docutils literal"><span class="pre">shared_ptr</span></tt></a>:</p>
|
|
<pre class="literal-block">
|
|
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);
|
|
</pre>
|
|
<p>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 <tt class="docutils literal"><span class="pre">color_map</span></tt> argument was
|
|
supplied. By using <a class="reference" href="../../../../more/generic_programming.html#tag_dispatching">tag dispatching</a> on the presence of a
|
|
<tt class="docutils literal"><span class="pre">color_map</span></tt> argument, we can do just that:</p>
|
|
<pre class="literal-block">
|
|
#include <boost/type_traits/is_same.hpp>
|
|
#include <boost/mpl/bool.hpp>
|
|
|
|
namespace graphs
|
|
{
|
|
template <class ArgumentPack>
|
|
void dfs_dispatch(ArgumentPack& args, <strong>mpl::true_</strong>)
|
|
{
|
|
<em>…use the color map computed in the previous example…</em>
|
|
}
|
|
|
|
template <class ArgumentPack>
|
|
void dfs_dispatch(ArgumentPack& args, <strong>mpl::false_</strong>)
|
|
{
|
|
<em>…use args[color]…</em>
|
|
}
|
|
|
|
BOOST_PARAMETER_FUNCTION(
|
|
(void),
|
|
depth_first_search,
|
|
|
|
tag,
|
|
(required (graph,*) )
|
|
(optional (visitor,*) (root_vertex,*)
|
|
(index_map,*) (out(color_map),*) )
|
|
)
|
|
{
|
|
typedef typename binding<args,tag::color>::type color_;
|
|
dfs_dispatch(
|
|
args, <strong>boost::is_same<color_,parameter::void_>()</strong>);
|
|
}
|
|
}
|
|
</pre>
|
|
<p>We've used the fact that the default for <tt class="docutils literal"><span class="pre">binding</span></tt>'s third
|
|
argument is <tt class="docutils literal"><span class="pre">parameter::void</span></tt>: because specializations of <tt class="docutils literal"><span class="pre">is_same</span></tt> are
|
|
<tt class="docutils literal"><span class="pre">bool</span></tt>-valued MPL <a class="reference" href="../../../mpl/doc/refmanual/integral-constant.html"><span class="concept">Integral Constant</span></a>s derived either
|
|
from <tt class="docutils literal"><span class="pre">mpl::true_</span></tt> or <tt class="docutils literal"><span class="pre">mpl::false_</span></tt>, the appropriate
|
|
<tt class="docutils literal"><span class="pre">dfs_dispatch</span></tt> implementation will be selected.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id41" id="portability-considerations" name="portability-considerations">3 Portability Considerations</a></h1>
|
|
<p>Use the <a class="reference" href="http://www.boost.org/regression/release/user/parameter.html">regression test results</a> 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.</p>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id42" id="no-sfinae-support" name="no-sfinae-support">3.1 No SFINAE Support</a></h2>
|
|
<p>Some older compilers don't support SFINAE. If your compiler meets
|
|
that criterion, then Boost headers will <tt class="docutils literal"><span class="pre">#define</span></tt> the preprocessor
|
|
symbol <tt class="docutils literal"><span class="pre">BOOST_NO_SFINAE</span></tt>, and parameter-enabled functions won't be
|
|
removed from the overload set based on their signatures.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="no-support-for-result-of" name="no-support-for-result-of">3.2 No Support for <a class="reference" href="../../../utility/utility.htm#result_of"><tt class="docutils literal"><span class="pre">result_of</span></tt></a></a></h2>
|
|
<p><a class="reference" href="#lazy-default-computation">Lazy default computation</a> relies on the <tt class="docutils literal"><span class="pre">result_of</span></tt> 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 <tt class="docutils literal"><span class="pre">result_of</span></tt>, <tt class="docutils literal"><span class="pre">BOOST_NO_RESULT_OF</span></tt> will be
|
|
<tt class="docutils literal"><span class="pre">#define</span></tt>d, and the compiler will expect the function object to
|
|
contain a nested type name, <tt class="docutils literal"><span class="pre">result_type</span></tt>, 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 <tt class="docutils literal"><span class="pre">result_type</span></tt> as a <tt class="docutils literal"><span class="pre">typedef</span></tt>
|
|
and invokes the function via its <tt class="docutils literal"><span class="pre">operator()</span></tt>.</p>
|
|
<!-- 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:
|
|
|
|
.. parsed-literal::
|
|
|
|
**struct dfs_parameters
|
|
:** parameter::parameters<
|
|
tag::graph, tag::visitor, tag::root_vertex
|
|
, tag::index_map, tag::color_map
|
|
> **{};**
|
|
|
|
|
|
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.
|
|
|
|
.. |BOOST_PARAMETER_MATCH| replace:: ``BOOST_PARAMETER_MATCH`` -->
|
|
</div>
|
|
<div class="section">
|
|
<h2><a class="toc-backref" href="#id44" id="compiler-can-t-see-references-in-unnamed-namespace" name="compiler-can-t-see-references-in-unnamed-namespace">3.3 Compiler Can't See References In Unnamed Namespace</a></h2>
|
|
<p>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
|
|
<em>using-declarations</em> to force the names to be available in the
|
|
enclosing namespace without qualification:</p>
|
|
<pre class="literal-block">
|
|
namespace graphs
|
|
{
|
|
using graphs::graph;
|
|
using graphs::visitor;
|
|
using graphs::root_vertex;
|
|
using graphs::index_map;
|
|
using graphs::color_map;
|
|
}
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id45" id="reference" name="reference">4 Reference</a></h1>
|
|
<p>Follow <a class="reference" href="reference.html">this link</a> to the Boost.Parameter reference
|
|
documentation.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a class="toc-backref" href="#id46" id="acknowledgements" name="acknowledgements">5 Acknowledgements</a></h1>
|
|
<p>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.</p>
|
|
<hr class="docutils" />
|
|
<table class="docutils footnote" frame="void" id="old-interface" rules="none">
|
|
<colgroup><col class="label" /><col /></colgroup>
|
|
<tbody valign="top">
|
|
<tr><td class="label"><a class="fn-backref" href="#id2" name="old-interface">[1]</a></td><td>As of Boost 1.33.0 the Graph library was still
|
|
using an <a class="reference" href="../../../graph/doc/bgl_named_params.html">older named parameter mechanism</a>, 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.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<table class="docutils footnote" frame="void" id="odr" rules="none">
|
|
<colgroup><col class="label" /><col /></colgroup>
|
|
<tbody valign="top">
|
|
<tr><td class="label"><a class="fn-backref" href="#id5" name="odr">[2]</a></td><td>The <strong>One Definition Rule</strong> 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.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<table class="docutils footnote" frame="void" id="vertex-descriptor" rules="none">
|
|
<colgroup><col class="label" /><col /></colgroup>
|
|
<tbody valign="top">
|
|
<tr><td class="label"><a class="fn-backref" href="#id7" name="vertex-descriptor">[3]</a></td><td>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
|
|
<tt class="docutils literal"><span class="pre">int</span></tt> in the text, and your understanding of the Parameter
|
|
library wouldn't suffer.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<table class="docutils footnote" frame="void" id="bind" rules="none">
|
|
<colgroup><col class="label" /><col /></colgroup>
|
|
<tbody valign="top">
|
|
<tr><td class="label"><a class="fn-backref" href="#id11" name="bind">[4]</a></td><td><p class="first">The Lambda library is known not to work on <a class="reference" href="http://www.boost.org/regression/release/user/lambda.html">some
|
|
less-conformant compilers</a>. When using one of those you could
|
|
define</p>
|
|
<pre class="last literal-block">
|
|
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)
|
|
</pre>
|
|
</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<table class="docutils footnote" frame="void" id="using" rules="none">
|
|
<colgroup><col class="label" /><col /></colgroup>
|
|
<tbody valign="top">
|
|
<tr><td class="label"><a class="fn-backref" href="#id8" name="using">[5]</a></td><td><p class="first">You can always give the illusion that the function
|
|
lives in an outer namespace by applying a <em>using-declaration</em>:</p>
|
|
<pre class="last literal-block">
|
|
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.
|
|
</pre>
|
|
</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<table class="docutils footnote" frame="void" id="sfinae" rules="none">
|
|
<colgroup><col class="label" /><col /></colgroup>
|
|
<tbody valign="top">
|
|
<tr><td class="label"><a class="fn-backref" href="#id6" name="sfinae">[6]</a></td><td><strong>SFINAE</strong>: <strong>S</strong>ubstitution <strong>F</strong>ailure <strong>I</strong>s
|
|
<strong>N</strong>ot <strong>A</strong>n <strong>E</strong> 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 <a class="reference" href="../../../utility/enable_if.html"><tt class="docutils literal"><span class="pre">enable_if</span></tt></a> utility. Most recent compilers support SFINAE;
|
|
on compilers that don't support it, the Boost config library
|
|
will <tt class="docutils literal"><span class="pre">#define</span></tt> the symbol <tt class="docutils literal"><span class="pre">BOOST_NO_SFINAE</span></tt>.
|
|
See
|
|
<a class="reference" href="http://www.semantics.org/once_weakly/w02_SFINAE.pdf">http://www.semantics.org/once_weakly/w02_SFINAE.pdf</a> for more
|
|
information on SFINAE.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="footer">
|
|
<hr class="footer" />
|
|
Generated on: 2006-05-18 14:54 UTC.
|
|
Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|