2201 lines
92 KiB
HTML
2201 lines
92 KiB
HTML
<?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.7: 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 external" 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<Deallocate<Foo> ></strong>
|
||
, <strong>copy_policy<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>deduced</em> parameters; that is to say, parameters whose identity
|
||
can be deduced from their types.</p>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<!-- @jam_prefix.append('''
|
||
project test : requirements <include>. <implicit-dependency>/boost//headers ;''') -->
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter.hpp>
|
||
|
||
namespace test
|
||
{
|
||
BOOST_PARAMETER_NAME(title)
|
||
BOOST_PARAMETER_NAME(width)
|
||
BOOST_PARAMETER_NAME(titlebar)
|
||
|
||
BOOST_PARAMETER_FUNCTION(
|
||
(int), new_window, tag, (required (title,*)(width,*)(titlebar,*)))
|
||
{
|
||
return 0;
|
||
}
|
||
|
||
BOOST_PARAMETER_TEMPLATE_KEYWORD(deleter)
|
||
BOOST_PARAMETER_TEMPLATE_KEYWORD(copy_policy)
|
||
|
||
template <class T> struct Deallocate {};
|
||
struct DeepCopy {};
|
||
|
||
namespace parameter = boost::parameter;
|
||
|
||
struct Foo {};
|
||
template <class T, class A0, class A1>
|
||
struct smart_ptr
|
||
{
|
||
smart_ptr(Foo*);
|
||
};
|
||
}
|
||
using namespace test;
|
||
int x = '''); -->
|
||
<!-- @test('compile') -->
|
||
<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 external" href="mailto:dave@boost-consulting.com">dave@boost-consulting.com</a>, <a class="reference external" href="mailto:daniel@boostpro.com">daniel@boostpro.com</a></td>
|
||
</tr>
|
||
<tr class="field"><th class="field-name">organization:</th><td class="field-body"><a class="reference external" href="http://www.boostpro.com">BoostPro Computing</a></td>
|
||
</tr>
|
||
<tr class="field"><th class="field-name">date:</th><td class="field-body">$Date: 2005/07/17 19:53:01 $</td>
|
||
</tr>
|
||
<tr class="field"><th class="field-name">copyright:</th><td class="field-body">Copyright David Abrahams, Daniel Wallin
|
||
2005-2009. Distributed under the Boost Software License,
|
||
Version 1.0. (See accompanying file LICENSE_1_0.txt
|
||
or copy at <a class="reference external" 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" />
|
||
<p>[Note: this tutorial does not cover all details of the library. Please see also the <a class="reference external" href="reference.html">reference documentation</a>]</p>
|
||
<div class="contents topic" id="table-of-contents">
|
||
<p class="topic-title first"><strong>Table of Contents</strong></p>
|
||
<ul class="auto-toc simple">
|
||
<li><a class="reference internal" href="#motivation" id="id22">1 Motivation</a><ul class="auto-toc">
|
||
<li><a class="reference internal" href="#named-function-parameters" id="id23">1.1 Named Function Parameters</a></li>
|
||
<li><a class="reference internal" href="#deduced-function-parameters" id="id24">1.2 Deduced Function Parameters</a></li>
|
||
<li><a class="reference internal" href="#class-template-parameter-support" id="id25">1.3 Class Template Parameter Support</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#tutorial" id="id26">2 Tutorial</a><ul class="auto-toc">
|
||
<li><a class="reference internal" href="#parameter-enabled-functions" id="id27">2.1 Parameter-Enabled Functions</a></li>
|
||
<li><a class="reference internal" href="#parameter-enabled-member-functions" id="id28">2.2 Parameter-Enabled Member Functions</a></li>
|
||
<li><a class="reference internal" href="#parameter-enabled-constructors" id="id29">2.3 Parameter-Enabled Constructors</a></li>
|
||
<li><a class="reference internal" href="#parameter-enabled-class-templates" id="id30">2.4 Parameter-Enabled Class Templates</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#advanced-topics" id="id31">3 Advanced Topics</a><ul class="auto-toc">
|
||
<li><a class="reference internal" href="#fine-grained-name-control" id="id32">3.1 Fine-Grained Name Control</a></li>
|
||
<li><a class="reference internal" href="#more-argumentpacks" id="id33">3.2 More <span class="concept">ArgumentPack</span>s</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#best-practices" id="id34">4 Best Practices</a><ul class="auto-toc">
|
||
<li><a class="reference internal" href="#keyword-naming" id="id35">4.1 Keyword Naming</a></li>
|
||
<li><a class="reference internal" href="#namespaces" id="id36">4.2 Namespaces</a></li>
|
||
<li><a class="reference internal" href="#documentation" id="id37">4.3 Documentation</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#portability-considerations" id="id38">5 Portability Considerations</a><ul class="auto-toc">
|
||
<li><a class="reference internal" href="#no-sfinae-support" id="id39">5.1 No SFINAE Support</a></li>
|
||
<li><a class="reference internal" href="#no-support-for-result-of" id="id40">5.2 No Support for <tt class="docutils literal">result_of</tt></a></li>
|
||
<li><a class="reference internal" href="#compiler-can-t-see-references-in-unnamed-namespace" id="id41">5.3 Compiler Can't See References In Unnamed Namespace</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#python-binding" id="id42">6 Python Binding</a></li>
|
||
<li><a class="reference internal" href="#reference" id="id43">7 Reference</a></li>
|
||
<li><a class="reference internal" href="#glossary" id="id44">8 Glossary</a></li>
|
||
<li><a class="reference internal" href="#acknowledgements" id="id45">9 Acknowledgements</a></li>
|
||
</ul>
|
||
</div>
|
||
<hr class="docutils" />
|
||
<div class="section" id="motivation">
|
||
<h1><a class="toc-backref" href="#id22">1 Motivation</a></h1>
|
||
<p>In C++, <a class="reference internal" href="#arguments">arguments</a> are normally given meaning by their positions
|
||
with respect to a <a class="reference internal" href="#parameter">parameter</a> list: the first argument passed maps
|
||
onto the first parameter in a function's definition, and so on.
|
||
That protocol is fine when there is at most one parameter with a
|
||
default value, but when there are even a few useful defaults, the
|
||
positional interface becomes burdensome:</p>
|
||
<ul>
|
||
<li><div class="first compound">
|
||
<p class="compound-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="compound-middle 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 class="compound-middle">In the example above we wanted to make an unmoveable window
|
||
with a default <tt class="docutils literal">border_width</tt>, but instead we got a moveable
|
||
window with a <tt class="docutils literal">border_width</tt> of zero. To get the desired
|
||
effect, we'd need to write:</p>
|
||
<pre class="compound-last literal-block">
|
||
window* w = new_window(
|
||
"alert box", <strong>default_border_width</strong>, movability);
|
||
</pre>
|
||
</div>
|
||
</li>
|
||
<li><div class="first compound">
|
||
<p class="compound-first">It can become difficult for readers to understand the meaning of
|
||
arguments at the call site:</p>
|
||
<pre class="compound-middle literal-block">
|
||
window* w = new_window("alert", 1, true, false);
|
||
</pre>
|
||
<p class="compound-last">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>
|
||
</div>
|
||
</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>
|
||
<!-- @ignore(3) -->
|
||
<div class="section" id="named-function-parameters">
|
||
<h2><a class="toc-backref" href="#id23">1.1 Named Function Parameters</a></h2>
|
||
<div class="compound">
|
||
<p class="compound-first">This library addresses the problems outlined above by associating
|
||
each parameter name with a keyword object. Now users can identify
|
||
arguments by name, rather than by position:</p>
|
||
<pre class="compound-last literal-block">
|
||
window* w = new_window("alert box", <strong>movable_=</strong>false); // OK!
|
||
</pre>
|
||
</div>
|
||
<!-- @ignore() -->
|
||
</div>
|
||
<div class="section" id="deduced-function-parameters">
|
||
<h2><a class="toc-backref" href="#id24">1.2 Deduced Function Parameters</a></h2>
|
||
<div class="compound">
|
||
<p class="compound-first">A <strong>deduced parameter</strong> can be passed in any position <em>without</em>
|
||
supplying an explicit parameter name. It's not uncommon for a
|
||
function to have parameters that can be uniquely identified based
|
||
on the types of arguments passed. The <tt class="docutils literal">name</tt> parameter to
|
||
<tt class="docutils literal">new_window</tt> is one such example. None of the other arguments,
|
||
if valid, can reasonably be converted to a <tt class="docutils literal">char const*</tt>. With
|
||
a deduced parameter interface, we could pass the window name in
|
||
<em>any</em> argument position without causing ambiguity:</p>
|
||
<pre class="compound-middle literal-block">
|
||
window* w = new_window(movable_=false, <strong>"alert box"</strong>); // OK!
|
||
window* w = new_window(<strong>"alert box"</strong>, movable_=false); // OK!
|
||
</pre>
|
||
<p class="compound-last">Appropriately used, a deduced parameter interface can free the
|
||
user of the burden of even remembering the formal parameter
|
||
names.</p>
|
||
</div>
|
||
<!-- @ignore() -->
|
||
</div>
|
||
<div class="section" id="class-template-parameter-support">
|
||
<h2><a class="toc-backref" href="#id25">1.3 Class Template Parameter Support</a></h2>
|
||
<div class="compound">
|
||
<p class="compound-first">The reasoning we've given for named and deduced parameter
|
||
interfaces applies equally well to class templates as it does to
|
||
functions. Using the Parameter library, we can create interfaces
|
||
that allow template arguments (in this case <tt class="docutils literal">shared</tt> and
|
||
<tt class="docutils literal">Client</tt>) to be explicitly named, like this:</p>
|
||
<pre class="compound-middle literal-block">
|
||
smart_ptr<<strong>ownership<shared></strong>, <strong>value_type<Client></strong> > p;
|
||
</pre>
|
||
<p class="compound-middle">The syntax for passing named template arguments is not quite as
|
||
natural as it is for function arguments (ideally, we'd be able to
|
||
write <tt class="docutils literal"><span class="pre">smart_ptr<ownership=shared,…></span></tt>). This small syntactic
|
||
deficiency makes deduced parameters an especially big win when
|
||
used with class templates:</p>
|
||
<pre class="compound-last literal-block">
|
||
// <em>p and q could be equivalent, given a deduced</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>
|
||
<!-- @ignore(2) -->
|
||
</div>
|
||
</div>
|
||
<div class="section" id="tutorial">
|
||
<h1><a class="toc-backref" href="#id26">2 Tutorial</a></h1>
|
||
<p>This tutorial shows all the basics—how to build both named- and deduced-parameter
|
||
interfaces to function templates and class templates—and several
|
||
more advanced idioms as well.</p>
|
||
<div class="section" id="parameter-enabled-functions">
|
||
<h2><a class="toc-backref" href="#id27">2.1 Parameter-Enabled Functions</a></h2>
|
||
<p>In this section we'll show how the Parameter library can be used to
|
||
build an expressive interface to the <a class="reference external" href="../../../graph/index.html">Boost Graph library</a>'s
|
||
<a class="reference external" href="../../../graph/doc/depth_first_search.html"><tt class="docutils literal">depth_first_search</tt></a> algorithm.<a class="footnote-reference" href="#old-interface" id="id3"><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" id="headers-and-namespaces">
|
||
<h3>2.1.1 Headers And Namespaces</h3>
|
||
<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">boost/parameter.hpp</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">#include</tt> to access any given component of the library.</p>
|
||
<!-- @example.append('''
|
||
using boost::parameter::keyword;
|
||
''') -->
|
||
<!-- @test('compile') -->
|
||
<p>Also, the examples below will also be written as if the
|
||
namespace alias</p>
|
||
<pre class="literal-block">
|
||
namespace parameter = boost::parameter;
|
||
</pre>
|
||
<!-- @ignore() -->
|
||
<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" id="the-abstract-interface-to-dfs">
|
||
<h3>2.1.2 The Abstract Interface to <tt class="docutils literal">depth_first_search</tt></h3>
|
||
<p>The Graph library's <tt class="docutils literal">depth_first_search</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>
|
||
<!-- @ignore() -->
|
||
<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><tt class="docutils literal">depth_first_search</tt> Parameters</caption>
|
||
<colgroup>
|
||
<col width="17%" />
|
||
<col width="11%" />
|
||
<col width="35%" />
|
||
<col width="37%" />
|
||
</colgroup>
|
||
<thead valign="bottom">
|
||
<tr><th class="head">Parameter Name</th>
|
||
<th class="head">Dataflow</th>
|
||
<th class="head">Type</th>
|
||
<th class="head">Default Value (if any)</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody valign="top">
|
||
<tr><td><tt class="docutils literal">graph</tt></td>
|
||
<td>in</td>
|
||
<td>Model of <a class="reference external" href="../../../graph/doc/IncidenceGraph.html"><span class="concept">Incidence Graph</span></a> and
|
||
<a class="reference external" href="../../../graph/doc/VertexListGraph.html"><span class="concept">Vertex List Graph</span></a></td>
|
||
<td>none - this argument is required.</td>
|
||
</tr>
|
||
<tr><td><tt class="docutils literal">visitor</tt></td>
|
||
<td>in</td>
|
||
<td>Model of <a class="reference external" href="../../../graph/doc/DFSVisitor.html"><span class="concept">DFS Visitor</span></a></td>
|
||
<td><tt class="docutils literal"><span class="pre">boost::dfs_visitor<>()</span></tt></td>
|
||
</tr>
|
||
<tr><td><tt class="docutils literal">root_vertex</tt></td>
|
||
<td>in</td>
|
||
<td><tt class="docutils literal">graph</tt>'s vertex descriptor
|
||
type.</td>
|
||
<td><tt class="docutils literal"><span class="pre">*vertices(graph).first</span></tt></td>
|
||
</tr>
|
||
<tr><td><tt class="docutils literal">index_map</tt></td>
|
||
<td>in</td>
|
||
<td>Model of <a class="reference external" href="../../../property_map/doc/ReadablePropertyMap.html"><span class="concept">Readable Property Map</span></a>
|
||
with key type := <tt class="docutils literal">graph</tt>'s
|
||
vertex descriptor and value type
|
||
an integer type.</td>
|
||
<td><tt class="docutils literal"><span class="pre">get(boost::vertex_index,graph)</span></tt></td>
|
||
</tr>
|
||
<tr><td><tt class="docutils literal">color_map</tt></td>
|
||
<td>in/out</td>
|
||
<td>Model of <a class="reference external" href="../../../property_map/doc/ReadWritePropertyMap.html"><span class="concept">Read/Write Property Map</span></a>
|
||
with key type := <tt class="docutils literal">graph</tt>'s
|
||
vertex descriptor type.</td>
|
||
<td>an <tt class="docutils literal">iterator_property_map</tt>
|
||
created from a <tt class="docutils literal"><span class="pre">std::vector</span></tt> of
|
||
<tt class="docutils literal">default_color_type</tt> of size
|
||
<tt class="docutils literal">num_vertices(graph)</tt> and using
|
||
<tt class="docutils literal">index_map</tt> for the index map.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>Don't be intimidated by the information in the second and third
|
||
columns above. For the purposes of this exercise, you don't need
|
||
to understand them in detail.</p>
|
||
</div>
|
||
<div class="section" id="defining-the-keywords">
|
||
<h3>2.1.3 Defining the Keywords</h3>
|
||
<p>The point of this exercise is to make it possible to call
|
||
<tt class="docutils literal">depth_first_search</tt> with named 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>
|
||
<!-- @ignore() -->
|
||
<p>To make that syntax legal, there needs to be an object called
|
||
“<tt class="docutils literal">color_map_</tt>” whose assignment operator can accept a
|
||
<tt class="docutils literal">my_color_map</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>
|
||
<!-- Revisit this
|
||
|
||
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 accessible through
|
||
``graphs``, and we'll hide the tag types away in a nested
|
||
namespace, ``graphs::tag``. The library provides a convenient
|
||
macro for that purpose. -->
|
||
<p>We're going to define our interface in namespace <tt class="docutils literal">graphs</tt>. The
|
||
library provides a convenient macro for defining keyword objects:</p>
|
||
<pre class="literal-block">
|
||
#include <boost/parameter/name.hpp>
|
||
|
||
namespace graphs
|
||
{
|
||
BOOST_PARAMETER_NAME(graph) // Note: no semicolon
|
||
BOOST_PARAMETER_NAME(visitor)
|
||
BOOST_PARAMETER_NAME(root_vertex)
|
||
BOOST_PARAMETER_NAME(index_map)
|
||
BOOST_PARAMETER_NAME(color_map)
|
||
}
|
||
</pre>
|
||
<!-- @test('compile') -->
|
||
<p>The declaration of the <tt class="docutils literal">graph</tt> keyword you see here is
|
||
equivalent to:</p>
|
||
<pre class="literal-block">
|
||
namespace graphs
|
||
{
|
||
namespace tag { struct graph; } // keyword tag type
|
||
|
||
namespace // unnamed
|
||
{
|
||
// A reference to the keyword object
|
||
boost::parameter::keyword<tag::graph>& _graph
|
||
= boost::parameter::keyword<tag::graph>::get();
|
||
}
|
||
}
|
||
</pre>
|
||
<!-- @example.prepend('#include <boost/parameter/keyword.hpp>') -->
|
||
<!-- @test('compile') -->
|
||
<p>It defines a <em>keyword tag type</em> named <tt class="docutils literal"><span class="pre">tag::graph</span></tt> and a <em>keyword
|
||
object</em> reference named <tt class="docutils literal">_graph</tt>.</p>
|
||
<p>This “fancy dance” involving an unnamed namespace and references
|
||
is all done to avoid violating the One Definition Rule (ODR)<a class="footnote-reference" href="#odr" id="id5"><sup>2</sup></a> when the named parameter interface is used by function
|
||
templates that are instantiated in multiple translation
|
||
units (MSVC6.x users see <a class="reference internal" href="#compiler-can-t-see-references-in-unnamed-namespace">this note</a>).</p>
|
||
</div>
|
||
<div class="section" id="writing-the-function">
|
||
<h3>2.1.4 Writing the Function</h3>
|
||
<p>Now that we have our keywords defined, the function template
|
||
definition follows a simple pattern using the
|
||
<tt class="docutils literal">BOOST_PARAMETER_FUNCTION</tt> macro:</p>
|
||
<pre class="literal-block">
|
||
#include <boost/parameter/preprocessor.hpp>
|
||
|
||
namespace graphs
|
||
{
|
||
BOOST_PARAMETER_FUNCTION(
|
||
(void), // 1. parenthesized return type
|
||
depth_first_search, // 2. name of the function template
|
||
|
||
tag, // 3. namespace of tag types
|
||
|
||
(required (graph, *) ) // 4. one required parameter, and
|
||
|
||
(optional // four optional parameters, with defaults
|
||
(visitor, *, boost::dfs_visitor<>())
|
||
(root_vertex, *, *vertices(graph).first)
|
||
(index_map, *, get(boost::vertex_index,graph))
|
||
(in_out(color_map), *,
|
||
default_color_map(num_vertices(graph), index_map) )
|
||
)
|
||
)
|
||
{
|
||
// ... body of function goes here...
|
||
// use graph, visitor, index_map, and color_map
|
||
}
|
||
}
|
||
</pre>
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter/name.hpp>
|
||
|
||
BOOST_PARAMETER_NAME(graph)
|
||
BOOST_PARAMETER_NAME(visitor)
|
||
BOOST_PARAMETER_NAME(root_vertex)
|
||
BOOST_PARAMETER_NAME(index_map)
|
||
BOOST_PARAMETER_NAME(color_map)
|
||
|
||
namespace boost {
|
||
|
||
template <class T = int>
|
||
struct dfs_visitor
|
||
{};
|
||
|
||
int vertex_index = 0;
|
||
|
||
}''') -->
|
||
<!-- @test('compile') -->
|
||
<p>The arguments to <tt class="docutils literal">BOOST_PARAMETER_FUNCTION</tt> are:</p>
|
||
<ol class="arabic simple">
|
||
<li>The return type of the resulting function template. Parentheses
|
||
around the return type prevent any commas it might contain from
|
||
confusing the preprocessor, and are always required.</li>
|
||
<li>The name of the resulting function template.</li>
|
||
<li>The name of a namespace where we can find tag types whose names
|
||
match the function's parameter names.</li>
|
||
<li>The function signature.</li>
|
||
</ol>
|
||
</div>
|
||
<div class="section" id="function-signatures">
|
||
<h3>2.1.5 Function Signatures</h3>
|
||
<p>Function signatures are described as one or two adjacent
|
||
parenthesized terms (a <a class="reference external" href="../../../preprocessor/index.html">Boost.Preprocessor</a> <a class="reference external" href="http://boost-consulting.com/mplbook/preprocessor.html#sequences">sequence</a>) describing
|
||
the function's parameters in the order in which they'd be expected
|
||
if passed positionally. Any required parameters must come first,
|
||
but the <tt class="docutils literal">(required … )</tt> clause can be omitted when all the
|
||
parameters are optional.</p>
|
||
<div class="section" id="required-parameters">
|
||
<h4>2.1.5.1 Required Parameters</h4>
|
||
<div class="compound">
|
||
<p class="compound-first">Required parameters are given first—nested in a <tt class="docutils literal">(required … )</tt>
|
||
clause—as a series of two-element tuples describing each parameter
|
||
name and any requirements on the argument type. In this case there
|
||
is only a single required parameter, so there's just a single
|
||
tuple:</p>
|
||
<pre class="compound-middle literal-block">
|
||
(required <strong>(graph, *)</strong> )
|
||
</pre>
|
||
<p class="compound-last">Since <tt class="docutils literal">depth_first_search</tt> doesn't require any particular type
|
||
for its <tt class="docutils literal">graph</tt> parameter, we use an asterix to indicate that
|
||
any type is allowed. Required parameters must always precede any
|
||
optional parameters in a signature, but if there are <em>no</em>
|
||
required parameters, the <tt class="docutils literal">(required … )</tt> clause can be omitted
|
||
entirely.</p>
|
||
</div>
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter.hpp>
|
||
|
||
BOOST_PARAMETER_NAME(graph)
|
||
|
||
BOOST_PARAMETER_FUNCTION((void), f, tag,
|
||
''') -->
|
||
<!-- @example.append(') {}') -->
|
||
<!-- @test('compile') -->
|
||
</div>
|
||
<div class="section" id="optional-parameters">
|
||
<h4>2.1.5.2 Optional Parameters</h4>
|
||
<div class="compound">
|
||
<p class="compound-first">Optional parameters—nested in an <tt class="docutils literal">(optional … )</tt> clause—are given
|
||
as a series of adjacent <em>three</em>-element tuples describing the
|
||
parameter name, any requirements on the argument type, <em>and</em> and an
|
||
expression representing the parameter's default value:</p>
|
||
<pre class="compound-last literal-block">
|
||
(optional <strong> (visitor, *, boost::dfs_visitor<>())
|
||
(root_vertex, *, *vertices(graph).first)
|
||
(index_map, *, get(boost::vertex_index,graph))
|
||
(in_out(color_map), *,
|
||
default_color_map(num_vertices(graph), index_map) )</strong>
|
||
)
|
||
</pre>
|
||
</div>
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter.hpp>
|
||
|
||
namespace boost
|
||
{
|
||
int vertex_index = 0;
|
||
|
||
template <class T = int>
|
||
struct dfs_visitor
|
||
{};
|
||
}
|
||
|
||
BOOST_PARAMETER_NAME(graph)
|
||
BOOST_PARAMETER_NAME(visitor)
|
||
BOOST_PARAMETER_NAME(root_vertex)
|
||
BOOST_PARAMETER_NAME(index_map)
|
||
BOOST_PARAMETER_NAME(color_map)
|
||
|
||
BOOST_PARAMETER_FUNCTION((void), f, tag,
|
||
(required (graph, *))
|
||
''') -->
|
||
<!-- @example.append(') {}') -->
|
||
<!-- @test('compile') -->
|
||
</div>
|
||
<div class="section" id="handling-out-parameters">
|
||
<h4>2.1.5.3 Handling “Out” Parameters</h4>
|
||
<div class="compound">
|
||
<p class="compound-first">Within the function body, a parameter name such as <tt class="docutils literal">visitor</tt> is
|
||
a <em>C++ reference</em>, bound either to an actual argument passed by
|
||
the caller or to the result of evaluating a default expression.
|
||
In most cases, parameter types are of the form <tt class="docutils literal">T const&</tt> for
|
||
some <tt class="docutils literal">T</tt>. Parameters whose values are expected to be modified,
|
||
however, must be passed by reference to <em>non</em>-<tt class="docutils literal">const</tt>. To
|
||
indicate that <tt class="docutils literal">color_map</tt> is both read and written, we wrap
|
||
its name in <tt class="docutils literal"><span class="pre">in_out(…)</span></tt>:</p>
|
||
<pre class="compound-last literal-block">
|
||
(optional
|
||
(visitor, *, boost::dfs_visitor<>())
|
||
(root_vertex, *, *vertices(graph).first)
|
||
(index_map, *, get(boost::vertex_index,graph))
|
||
(<strong>in_out(color_map)</strong>, *,
|
||
default_color_map(num_vertices(graph), index_map) )
|
||
)
|
||
</pre>
|
||
</div>
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter.hpp>
|
||
|
||
namespace boost
|
||
{
|
||
int vertex_index = 0;
|
||
|
||
template <class T = int>
|
||
struct dfs_visitor
|
||
{};
|
||
}
|
||
|
||
BOOST_PARAMETER_NAME(graph)
|
||
|
||
BOOST_PARAMETER_NAME(visitor)
|
||
BOOST_PARAMETER_NAME(root_vertex)
|
||
BOOST_PARAMETER_NAME(index_map)
|
||
BOOST_PARAMETER_NAME(color_map)
|
||
|
||
BOOST_PARAMETER_FUNCTION((void), f, tag,
|
||
(required (graph, *))
|
||
''') -->
|
||
<!-- @example.append(') {}') -->
|
||
<!-- @test('compile') -->
|
||
<p>If <tt class="docutils literal">color_map</tt> were strictly going to be modified but not examined,
|
||
we could have written <tt class="docutils literal">out(color_map)</tt>. There is no functional
|
||
difference between <tt class="docutils literal">out</tt> and <tt class="docutils literal">in_out</tt>; the library provides
|
||
both so you can make your interfaces more self-documenting.</p>
|
||
</div>
|
||
<div class="section" id="positional-arguments">
|
||
<h4>2.1.5.4 Positional Arguments</h4>
|
||
<p>When arguments are passed positionally (without the use of
|
||
keywords), they will be mapped onto parameters in the order the
|
||
parameters are given in the signature, so for example in this
|
||
call</p>
|
||
<pre class="literal-block">
|
||
graphs::depth_first_search(x, y);
|
||
</pre>
|
||
<!-- @ignore() -->
|
||
<p><tt class="docutils literal">x</tt> will always be interpreted as a graph and <tt class="docutils literal">y</tt> will always
|
||
be interpreted as a visitor.</p>
|
||
</div>
|
||
<div class="section" id="default-expression-evaluation">
|
||
<h4>2.1.5.5 Default Expression Evaluation</h4>
|
||
<div class="compound">
|
||
<p class="compound-first">Note that in our example, the value of the graph parameter is
|
||
used in the default expressions for <tt class="docutils literal">root_vertex</tt>,
|
||
<tt class="docutils literal">index_map</tt> and <tt class="docutils literal">color_map</tt>.</p>
|
||
<pre class="compound-middle literal-block">
|
||
(required (<strong>graph</strong>, *) )
|
||
(optional
|
||
(visitor, *, boost::dfs_visitor<>())
|
||
(root_vertex, *, *vertices(<strong>graph</strong>).first)
|
||
(index_map, *, get(boost::vertex_index,<strong>graph</strong>))
|
||
(in_out(color_map), *,
|
||
default_color_map(num_vertices(<strong>graph</strong>), index_map) )
|
||
)
|
||
</pre>
|
||
<!-- @ignore() -->
|
||
<p class="compound-last">A default expression is evaluated in the context of all preceding
|
||
parameters, so you can use any of their values by name.</p>
|
||
</div>
|
||
<div class="compound">
|
||
<p class="compound-first">A default expression is never evaluated—or even instantiated—if
|
||
an actual argument is passed for that parameter. We can actually
|
||
demonstrate that with our code so far by replacing the body of
|
||
<tt class="docutils literal">depth_first_search</tt> with something that prints the arguments:</p>
|
||
<pre class="compound-middle literal-block">
|
||
#include <boost/graph/depth_first_search.hpp> // for dfs_visitor
|
||
|
||
BOOST_PARAMETER_FUNCTION(
|
||
(void), depth_first_search, tag
|
||
<em>…signature goes here…</em>
|
||
)
|
||
{
|
||
std::cout << "graph=" << graph << std::endl;
|
||
std::cout << "visitor=" << visitor << std::endl;
|
||
std::cout << "root_vertex=" << root_vertex << std::endl;
|
||
std::cout << "index_map=" << index_map << std::endl;
|
||
std::cout << "color_map=" << color_map << std::endl;
|
||
}
|
||
|
||
int main()
|
||
{
|
||
depth_first_search(1, 2, 3, 4, 5);
|
||
|
||
depth_first_search(
|
||
"1", '2', _color_map = '5',
|
||
_index_map = "4", _root_vertex = "3");
|
||
}
|
||
</pre>
|
||
<p class="compound-last">Despite the fact that default expressions such as
|
||
<tt class="docutils literal"><span class="pre">vertices(graph).first</span></tt> are ill-formed for the given <tt class="docutils literal">graph</tt>
|
||
arguments, both calls will compile, and each one will print
|
||
exactly the same thing.</p>
|
||
</div>
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter.hpp>
|
||
#include <iostream>
|
||
|
||
BOOST_PARAMETER_NAME(graph)
|
||
BOOST_PARAMETER_NAME(visitor)
|
||
BOOST_PARAMETER_NAME(root_vertex)
|
||
BOOST_PARAMETER_NAME(index_map)
|
||
BOOST_PARAMETER_NAME(color_map)''') -->
|
||
<!-- @example.replace_emphasis('''
|
||
, (required
|
||
(graph, *)
|
||
(visitor, *)
|
||
(root_vertex, *)
|
||
(index_map, *)
|
||
(color_map, *)
|
||
)
|
||
''') -->
|
||
<!-- @test('compile') -->
|
||
</div>
|
||
<div class="section" id="signature-matching-and-overloading">
|
||
<h4>2.1.5.6 Signature Matching and Overloading</h4>
|
||
<p>In fact, the function signature is so general that any call to
|
||
<tt class="docutils literal">depth_first_search</tt> with fewer than five arguments will match
|
||
our function, provided we pass <em>something</em> for the required
|
||
<tt class="docutils literal">graph</tt> parameter. That might not seem to be a problem at first;
|
||
after all, if the arguments don't match the requirements imposed by
|
||
the implementation of <tt class="docutils literal">depth_first_search</tt>, a compilation error
|
||
will occur later, when its body is instantiated.</p>
|
||
<p>There are at least three problems with very general function
|
||
signatures.</p>
|
||
<ol class="arabic simple">
|
||
<li>By the time our <tt class="docutils literal">depth_first_search</tt> is instantiated, it has
|
||
been selected as the best matching overload. Some other
|
||
<tt class="docutils literal">depth_first_search</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 names generated by <tt class="docutils literal">BOOST_PARAMETER_FUNCTION</tt> such as
|
||
<tt class="docutils literal"><span class="pre">graphs::detail::depth_first_search_with_named_params</span></tt> (or
|
||
worse—think of the kinds of errors you get from your STL
|
||
implementation when you make a mistake).<a class="footnote-reference" href="#conceptcpp" id="id7"><sup>4</sup></a></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 external" href="http://www.open-std.org/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">depth_first_search</tt> in a namespace containing no
|
||
types<a class="footnote-reference" href="#using" id="id8"><sup>6</sup></a>, but suppose we <em>want</em> it to found via ADL?</li>
|
||
</ol>
|
||
<p>It's usually a good idea to prevent functions from being considered
|
||
for overload resolution when the passed argument types aren't
|
||
appropriate. The library already does this when the required
|
||
<tt class="docutils literal">graph</tt> parameter is not supplied, but we're not likely to see a
|
||
depth first search that doesn't take a graph to operate on.
|
||
Suppose, instead, that we found a different depth first search
|
||
algorithm that could work on graphs that don't model
|
||
<a class="reference external" href="../../../graph/doc/IncidenceGraph.html"><span class="concept">Incidence Graph</span></a>? If we just added a simple overload,
|
||
it would be ambiguous:</p>
|
||
<pre class="literal-block">
|
||
// new overload
|
||
BOOST_PARAMETER_FUNCTION(
|
||
(void), depth_first_search, (tag), (required (graph,*))( … ))
|
||
{
|
||
// new algorithm implementation
|
||
}
|
||
|
||
…
|
||
|
||
// ambiguous!
|
||
depth_first_search(boost::adjacency_list<>(), 2, "hello");
|
||
</pre>
|
||
<!-- @ignore() -->
|
||
<div class="section" id="adding-type-requirements">
|
||
<h5>2.1.5.6.1 Adding Type Requirements</h5>
|
||
<p>We really don't want the compiler to consider the original version
|
||
of <tt class="docutils literal">depth_first_search</tt> because the <tt class="docutils literal">root_vertex</tt> argument,
|
||
<tt class="docutils literal">"hello"</tt>, doesn't meet the <a class="reference internal" href="#parameter-table">requirement</a> that it match the
|
||
<tt class="docutils literal">graph</tt> parameter's vertex descriptor type. Instead, this call
|
||
should just invoke our new overload. To take the original
|
||
<tt class="docutils literal">depth_first_search</tt> overload out of contention, we need to tell
|
||
the library about this requirement by replacing the <tt class="docutils literal">*</tt> element
|
||
of the signature with the required type, in parentheses:</p>
|
||
<pre class="literal-block">
|
||
(root_vertex,
|
||
<strong>(typename boost::graph_traits<graph_type>::vertex_descriptor)</strong>,
|
||
*vertices(graph).first)
|
||
</pre>
|
||
<!-- @ignore() -->
|
||
<p>Now the original <tt class="docutils literal">depth_first_search</tt> will only be called when
|
||
the <tt class="docutils literal">root_vertex</tt> argument can be converted to the graph's vertex
|
||
descriptor type, and our example that <em>was</em> ambiguous will smoothly
|
||
call the new overload.</p>
|
||
<div class="note">
|
||
<p class="first admonition-title">Note</p>
|
||
<p class="last">The <em>type</em> of the <tt class="docutils literal">graph</tt> argument is available in the
|
||
signature—and in the function body—as <tt class="docutils literal">graph_type</tt>. In
|
||
general, to access the type of any parameter <em>foo</em>, write <em>foo</em><tt class="docutils literal">_type</tt>.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="predicate-requirements">
|
||
<h5>2.1.5.6.2 Predicate Requirements</h5>
|
||
<p>The requirements on other arguments are a bit more interesting than
|
||
those on <tt class="docutils literal">root_vertex</tt>; they can't be described in terms of simple
|
||
type matching. Instead, they must be described in terms of <a class="reference external" href="../../../mpl/doc/refmanual/metafunction.html">MPL
|
||
Metafunctions</a>. There's no space to give a complete description
|
||
of metafunctions or of graph library details here, but we'll show
|
||
you the complete signature with maximal checking, just to give you
|
||
a feel for how it's done. Each predicate metafunction is enclosed
|
||
in parentheses <em>and preceded by an asterix</em>, as follows:</p>
|
||
<pre class="literal-block">
|
||
// We first need to define a few metafunction that we use in the
|
||
// predicates below.
|
||
|
||
template <class G>
|
||
struct traversal_category
|
||
{
|
||
typedef typename boost::graph_traits<G>::traversal_category type;
|
||
};
|
||
|
||
template <class G>
|
||
struct vertex_descriptor
|
||
{
|
||
typedef typename boost::graph_traits<G>::vertex_descriptor type;
|
||
};
|
||
|
||
template <class G>
|
||
struct value_type
|
||
{
|
||
typedef typename boost::property_traits<G>::value_type type;
|
||
};
|
||
|
||
template <class G>
|
||
struct key_type
|
||
{
|
||
typedef typename boost::property_traits<G>::key_type type;
|
||
};
|
||
|
||
template<class Size, class IndexMap>
|
||
boost::iterator_property_map<
|
||
boost::default_color_type*, IndexMap
|
||
, boost::default_color_type, boost::default_color_type&
|
||
>
|
||
default_color_map(Size num_vertices, IndexMap const& index_map)
|
||
{
|
||
std::vector<boost::default_color_type> colors(num_vertices);
|
||
return &colors[0];
|
||
}
|
||
|
||
BOOST_PARAMETER_FUNCTION(
|
||
(void), depth_first_search, graphs
|
||
|
||
, (required
|
||
(graph
|
||
, <strong>*(boost::mpl::and_<
|
||
boost::is_convertible<
|
||
traversal_category<_>, boost::incidence_graph_tag
|
||
>
|
||
, boost::is_convertible<
|
||
traversal_category<_>, boost::vertex_list_graph_tag
|
||
>
|
||
>)</strong> ))
|
||
|
||
(optional
|
||
(visitor, *, boost::dfs_visitor<>()) // not checkable
|
||
|
||
(root_vertex
|
||
, (vertex_descriptor<graphs::graph::_>)
|
||
, *vertices(graph).first)
|
||
|
||
(index_map
|
||
, <strong>*(boost::mpl::and_<
|
||
boost::is_integral<value_type<_> >
|
||
, boost::is_same<
|
||
vertex_descriptor<graphs::graph::_>, key_type<_>
|
||
>
|
||
>)</strong>
|
||
, get(boost::vertex_index,graph))
|
||
|
||
(in_out(color_map)
|
||
, <strong>*(boost::is_same<
|
||
vertex_descriptor<graphs::graph::_>, key_type<_>
|
||
>)</strong>
|
||
, default_color_map(num_vertices(graph), index_map) )
|
||
)
|
||
)
|
||
</pre>
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter.hpp>
|
||
#include <boost/graph/adjacency_list.hpp>
|
||
#include <boost/graph/depth_first_search.hpp>
|
||
|
||
BOOST_PARAMETER_NAME((_graph, graphs) graph)
|
||
BOOST_PARAMETER_NAME((_visitor, graphs) visitor)
|
||
BOOST_PARAMETER_NAME((_root_vertex, graphs) root_vertex)
|
||
BOOST_PARAMETER_NAME((_index_map, graphs) index_map)
|
||
BOOST_PARAMETER_NAME((_color_map, graphs) color_map)
|
||
|
||
using boost::mpl::_;
|
||
''') -->
|
||
<!-- @example.append('''
|
||
{}
|
||
|
||
int main()
|
||
{
|
||
typedef boost::adjacency_list<boost::vecS, boost::vecS, boost::directedS> G;
|
||
|
||
enum {u, v, w, x, y, z, N};
|
||
typedef std::pair<int, int> E;
|
||
E edges[] = {E(u, v), E(u, x), E(x, v), E(y, x), E(v, y), E(w, y),
|
||
E(w,z), E(z, z)};
|
||
G g(edges, edges + sizeof(edges) / sizeof(E), N);
|
||
|
||
depth_first_search(g);
|
||
depth_first_search(g, _root_vertex = (int)x);
|
||
}
|
||
''') -->
|
||
<!-- @test('compile') -->
|
||
<p>Note the use of the nested <cite>tag::_</cite>. This is a shortcut for:</p>
|
||
<pre class="literal-block">
|
||
value_type<boost::mpl::_2, tag>
|
||
</pre>
|
||
<!-- @ignore() -->
|
||
<p>Intended to be used to access preceding arguments types in the
|
||
predicates.</p>
|
||
<p>We acknowledge that this signature is pretty hairy looking.
|
||
Fortunately, it usually isn't necessary to so completely encode the
|
||
type requirements on arguments to generic functions. However, it
|
||
is usally worth the effort to do so: your code will be more
|
||
self-documenting and will often provide a better user experience.
|
||
You'll also have an easier transition to an upcoming C++ standard
|
||
with <a class="reference external" href="http://www.generic-programming.org/software/ConceptGCC/">language support for concepts</a>.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="deduced-parameters">
|
||
<h4>2.1.5.7 Deduced Parameters</h4>
|
||
<p>To illustrate deduced parameter support we'll have to leave behind
|
||
our example from the Graph library. Instead, consider the example
|
||
of the <a class="reference external" href="../../../python/doc/v2/def.html"><tt class="docutils literal">def</tt></a> function from <a class="reference external" href="../../../python/doc/index.html">Boost.Python</a>. Its signature is
|
||
roughly as follows:</p>
|
||
<pre class="literal-block">
|
||
template <
|
||
class Function, Class KeywordExpression, class CallPolicies
|
||
>
|
||
void def(
|
||
// Required parameters
|
||
char const* name, Function func
|
||
|
||
// Optional, deduced parameters
|
||
, char const* docstring = ""
|
||
, KeywordExpression keywords = no_keywords()
|
||
, CallPolicies policies = default_call_policies()
|
||
);
|
||
</pre>
|
||
<!-- @ignore() -->
|
||
<p>Try not to be too distracted by the use of the term “keywords” in
|
||
this example: although it means something analogous in Boost.Python
|
||
to what it means in the Parameter library, for the purposes of this
|
||
exercise you can think of it as being completely different.</p>
|
||
<p>When calling <tt class="docutils literal">def</tt>, only two arguments are required. The
|
||
association between any additional arguments and their parameters
|
||
can be determined by the types of the arguments actually passed, so
|
||
the caller is neither required to remember argument positions or
|
||
explicitly specify parameter names for those arguments. To
|
||
generate this interface using <tt class="docutils literal">BOOST_PARAMETER_FUNCTION</tt>, we need
|
||
only enclose the deduced parameters in a <tt class="docutils literal">(deduced …)</tt> clause, as
|
||
follows:</p>
|
||
<pre class="literal-block">
|
||
namespace mpl = boost::mpl;
|
||
|
||
BOOST_PARAMETER_FUNCTION(
|
||
(void), def, tag,
|
||
|
||
(required (name,(char const*)) (func,*) ) // nondeduced
|
||
|
||
<strong>(deduced</strong>
|
||
(optional
|
||
(docstring, (char const*), "")
|
||
|
||
(keywords
|
||
, *(is_keyword_expression<mpl::_>) // see<a class="footnote-reference" href="#is-keyword-expression" id="id13"><sup>5</sup></a>
|
||
, no_keywords())
|
||
|
||
(policies
|
||
, *(mpl::not_<
|
||
mpl::or_<
|
||
boost::is_convertible<mpl::_, char const*>
|
||
, is_keyword_expression<mpl::_> // see<a class="footnote-reference" href="#is-keyword-expression" id="id14"><sup>5</sup></a>
|
||
>
|
||
>)
|
||
, default_call_policies()
|
||
)
|
||
)
|
||
<strong>)</strong>
|
||
)
|
||
{
|
||
<em>…</em>
|
||
}
|
||
</pre>
|
||
<!-- @example.replace_emphasis('') -->
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter.hpp>
|
||
|
||
BOOST_PARAMETER_NAME(name)
|
||
BOOST_PARAMETER_NAME(func)
|
||
BOOST_PARAMETER_NAME(docstring)
|
||
BOOST_PARAMETER_NAME(keywords)
|
||
BOOST_PARAMETER_NAME(policies)
|
||
|
||
struct default_call_policies
|
||
{};
|
||
|
||
struct no_keywords
|
||
{};
|
||
|
||
struct keywords
|
||
{};
|
||
|
||
template <class T>
|
||
struct is_keyword_expression
|
||
: boost::mpl::false_
|
||
{};
|
||
|
||
template <>
|
||
struct is_keyword_expression<keywords>
|
||
: boost::mpl::true_
|
||
{};
|
||
|
||
default_call_policies some_policies;
|
||
|
||
void f()
|
||
{}
|
||
|
||
''') -->
|
||
<div class="admonition-syntax-note admonition">
|
||
<p class="first admonition-title">Syntax Note</p>
|
||
<p class="last">A <tt class="docutils literal">(deduced …)</tt> clause always contains a <tt class="docutils literal">(required …)</tt>
|
||
and/or an <tt class="docutils literal">(optional …)</tt> subclause, and must follow any
|
||
<tt class="docutils literal">(required …)</tt> or <tt class="docutils literal">(optional …)</tt> clauses indicating
|
||
nondeduced parameters at the outer level.</p>
|
||
</div>
|
||
<p>With the declaration above, the following two calls are equivalent:</p>
|
||
<pre class="literal-block">
|
||
def("f", &f, <strong>some_policies</strong>, <strong>"Documentation for f"</strong>);
|
||
def("f", &f, <strong>"Documentation for f"</strong>, <strong>some_policies</strong>);
|
||
</pre>
|
||
<!-- @example.prepend('''
|
||
int main()
|
||
{''') -->
|
||
<p>If the user wants to pass a <tt class="docutils literal">policies</tt> argument that was also,
|
||
for some reason, convertible to <tt class="docutils literal">char const*</tt>, she can always
|
||
specify the parameter name explicitly, as follows:</p>
|
||
<pre class="literal-block">
|
||
def(
|
||
"f", &f
|
||
, <strong>_policies = some_policies</strong>, "Documentation for f");
|
||
</pre>
|
||
<!-- @example.append('}') -->
|
||
<!-- @test('compile', howmany='all') -->
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="parameter-enabled-member-functions">
|
||
<h2><a class="toc-backref" href="#id28">2.2 Parameter-Enabled Member Functions</a></h2>
|
||
<p>The <tt class="docutils literal">BOOST_PARAMETER_MEMBER_FUNCTION</tt> and
|
||
<tt class="docutils literal">BOOST_PARAMETER_CONST_MEMBER_FUNCTION</tt> macros accept exactly the
|
||
same arguments as <tt class="docutils literal">BOOST_PARAMETER_FUNCTION</tt>, but are designed to
|
||
be used within the body of a class:</p>
|
||
<pre class="literal-block">
|
||
BOOST_PARAMETER_NAME(arg1)
|
||
BOOST_PARAMETER_NAME(arg2)
|
||
|
||
struct callable2
|
||
{
|
||
BOOST_PARAMETER_CONST_MEMBER_FUNCTION(
|
||
(void), call, tag, (required (arg1,(int))(arg2,(int))))
|
||
{
|
||
std::cout << arg1 << ", " << arg2 << std::endl;
|
||
}
|
||
};
|
||
</pre>
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter.hpp>
|
||
#include <iostream>
|
||
using namespace boost::parameter;
|
||
''') -->
|
||
<!-- @test('compile') -->
|
||
<p>These macros don't directly allow a function's interface to be
|
||
separated from its implementation, but you can always forward
|
||
arguments on to a separate implementation function:</p>
|
||
<pre class="literal-block">
|
||
struct callable2
|
||
{
|
||
BOOST_PARAMETER_CONST_MEMBER_FUNCTION(
|
||
(void), call, tag, (required (arg1,(int))(arg2,(int))))
|
||
{
|
||
call_impl(arg1,arg2);
|
||
}
|
||
private:
|
||
void call_impl(int, int); // implemented elsewhere.
|
||
};
|
||
</pre>
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter.hpp>
|
||
|
||
BOOST_PARAMETER_NAME(arg1)
|
||
BOOST_PARAMETER_NAME(arg2)
|
||
using namespace boost::parameter;
|
||
''') -->
|
||
<!-- @test('compile') -->
|
||
<div class="section" id="static-member-functions">
|
||
<h3>2.2.1 Static Member Functions</h3>
|
||
<p>To expose a static member function, simply insert the keyword
|
||
“<tt class="docutils literal">static</tt>” before the function name:</p>
|
||
<pre class="literal-block">
|
||
BOOST_PARAMETER_NAME(arg1)
|
||
|
||
struct somebody
|
||
{
|
||
BOOST_PARAMETER_MEMBER_FUNCTION(
|
||
(void), <strong>static</strong> f, tag, (optional (arg1,(int),0)))
|
||
{
|
||
std::cout << arg1 << std::endl;
|
||
}
|
||
};
|
||
</pre>
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter.hpp>
|
||
#include <iostream>
|
||
using namespace boost::parameter;
|
||
''') -->
|
||
<!-- @test('compile') -->
|
||
</div>
|
||
</div>
|
||
<div class="section" id="parameter-enabled-constructors">
|
||
<h2><a class="toc-backref" href="#id29">2.3 Parameter-Enabled Constructors</a></h2>
|
||
<p>The lack of a “delegating constructor”
|
||
feature in C++
|
||
(<a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1986.pdf">http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1986.pdf</a>)
|
||
limits somewhat the quality of interface this library can provide
|
||
for defining parameter-enabled constructors. The usual workaround
|
||
for a lack of constructor delegation applies: one must factor the
|
||
common logic into a base class.</p>
|
||
<p>Let's build a parameter-enabled constructor that simply prints its
|
||
arguments. The first step is to write a base class whose
|
||
constructor accepts a single argument known as an <a class="reference external" href="reference.html#argumentpack"><span class="concept">ArgumentPack</span></a>:
|
||
a bundle of references to the actual arguments, tagged with their
|
||
keywords. The values of the actual arguments are extracted from
|
||
the <span class="concept">ArgumentPack</span> by <em>indexing</em> it with keyword objects:</p>
|
||
<pre class="literal-block">
|
||
BOOST_PARAMETER_NAME(name)
|
||
BOOST_PARAMETER_NAME(index)
|
||
|
||
struct myclass_impl
|
||
{
|
||
template <class ArgumentPack>
|
||
myclass_impl(ArgumentPack const& args)
|
||
{
|
||
std::cout << "name = " << args[_name]
|
||
<< "; index = " << args[_index | 42]
|
||
<< std::endl;
|
||
}
|
||
};
|
||
</pre>
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter.hpp>
|
||
#include <iostream>''') -->
|
||
<p>Note that the bitwise or (“<tt class="docutils literal">|</tt>”) operator has a special
|
||
meaning when applied to keyword objects that are passed to an
|
||
<span class="concept">ArgumentPack</span>'s indexing operator: it is used to indicate a
|
||
default value. In this case if there is no <tt class="docutils literal">index</tt> parameter in
|
||
the <span class="concept">ArgumentPack</span>, <tt class="docutils literal">42</tt> will be used instead.</p>
|
||
<p>Now we are ready to write the parameter-enabled constructor
|
||
interface:</p>
|
||
<pre class="literal-block">
|
||
struct myclass : myclass_impl
|
||
{
|
||
BOOST_PARAMETER_CONSTRUCTOR(
|
||
myclass, (myclass_impl), tag
|
||
, (required (name,*)) (optional (index,*))) // no semicolon
|
||
};
|
||
</pre>
|
||
<p>Since we have supplied a default value for <tt class="docutils literal">index</tt> but not for
|
||
<tt class="docutils literal">name</tt>, only <tt class="docutils literal">name</tt> is required. We can exercise our new
|
||
interface as follows:</p>
|
||
<pre class="literal-block">
|
||
myclass x("bob", 3); // positional
|
||
myclass y(_index = 12, _name = "sally"); // named
|
||
myclass z("june"); // positional/defaulted
|
||
</pre>
|
||
<!-- @example.wrap('int main() {', '}') -->
|
||
<!-- @test('run', howmany='all') -->
|
||
<p>For more on <span class="concept">ArgumentPack</span> manipulation, see the <a class="reference internal" href="#advanced-topics">Advanced Topics</a>
|
||
section.</p>
|
||
</div>
|
||
<div class="section" id="parameter-enabled-class-templates">
|
||
<h2><a class="toc-backref" href="#id30">2.4 Parameter-Enabled Class Templates</a></h2>
|
||
<p>In this section we'll use Boost.Parameter to build <a class="reference external" href="../../../python/doc/index.html">Boost.Python</a>'s <a class="reference external" href="http://www.boost.org/libs/python/doc/v2/class.html#class_-spec">class_</a> template, whose “signature” is:</p>
|
||
<pre class="literal-block">
|
||
template class<
|
||
ValueType, BaseList = bases<>
|
||
, HeldType = ValueType, Copyable = void
|
||
>
|
||
class class_;
|
||
</pre>
|
||
<!-- @ignore() -->
|
||
<p>Only the first argument, <tt class="docutils literal">ValueType</tt>, is required.</p>
|
||
<div class="section" id="named-template-parameters">
|
||
<h3>2.4.1 Named Template Parameters</h3>
|
||
<p>First, we'll build an interface that allows users to pass arguments
|
||
positionally or by name:</p>
|
||
<pre class="literal-block">
|
||
struct B { virtual ~B() = 0; };
|
||
struct D : B { ~D(); };
|
||
|
||
class_<
|
||
<strong>class_type<B></strong>, <strong>copyable<boost::noncopyable></strong>
|
||
> …;
|
||
|
||
class_<
|
||
<strong>D</strong>, <strong>held_type<std::auto_ptr<D> ></strong>, <strong>base_list<bases<B> ></strong>
|
||
> …;
|
||
</pre>
|
||
<!-- @ignore() -->
|
||
<div class="section" id="template-keywords">
|
||
<h4>2.4.1.1 Template Keywords</h4>
|
||
<p>The first step is to define keywords for each template parameter:</p>
|
||
<pre class="literal-block">
|
||
namespace boost { namespace python {
|
||
|
||
BOOST_PARAMETER_TEMPLATE_KEYWORD(class_type)
|
||
BOOST_PARAMETER_TEMPLATE_KEYWORD(base_list)
|
||
BOOST_PARAMETER_TEMPLATE_KEYWORD(held_type)
|
||
BOOST_PARAMETER_TEMPLATE_KEYWORD(copyable)
|
||
|
||
}}
|
||
</pre>
|
||
<!-- @example.prepend('#include <boost/parameter.hpp>') -->
|
||
<!-- @test('compile') -->
|
||
<p>The declaration of the <tt class="docutils literal">class_type</tt> keyword you see here is
|
||
equivalent to:</p>
|
||
<pre class="literal-block">
|
||
namespace boost { namespace python {
|
||
|
||
namespace tag { struct class_type; } // keyword tag type
|
||
template <class T>
|
||
struct class_type
|
||
: parameter::template_keyword<tag::class_type,T>
|
||
{};
|
||
|
||
}}
|
||
</pre>
|
||
<!-- @example.prepend('#include <boost/parameter.hpp>') -->
|
||
<!-- @test('compile') -->
|
||
<p>It defines a keyword tag type named <tt class="docutils literal"><span class="pre">tag::class_type</span></tt> and a
|
||
<em>parameter passing template</em> named <tt class="docutils literal">class_type</tt>.</p>
|
||
</div>
|
||
<div class="section" id="class-template-skeleton">
|
||
<h4>2.4.1.2 Class Template Skeleton</h4>
|
||
<p>The next step is to define the skeleton of our class template,
|
||
which has three optional parameters. Because the user may pass
|
||
arguments in any order, we don't know the actual identities of
|
||
these parameters, so it would be premature to use descriptive names
|
||
or write out the actual default values for any of them. Instead,
|
||
we'll give them generic names and use the special type
|
||
<tt class="docutils literal"><span class="pre">boost::parameter::void_</span></tt> as a default:</p>
|
||
<pre class="literal-block">
|
||
namespace boost { namespace python {
|
||
|
||
template <
|
||
class A0
|
||
, class A1 = parameter::void_
|
||
, class A2 = parameter::void_
|
||
, class A3 = parameter::void_
|
||
>
|
||
struct class_
|
||
{
|
||
<em>…</em>
|
||
};
|
||
|
||
}}
|
||
</pre>
|
||
<!-- @example.prepend('#include <boost/parameter.hpp>') -->
|
||
<!-- @example.replace_emphasis('') -->
|
||
<!-- @test('compile') -->
|
||
</div>
|
||
<div class="section" id="class-template-signatures">
|
||
<h4>2.4.1.3 Class Template Signatures</h4>
|
||
<p>Next, we need to build a type, known as a <a class="reference external" href="reference.html#parameterspec"><span class="concept">ParameterSpec</span></a>,
|
||
describing the “signature” of <tt class="docutils literal"><span class="pre">boost::python::class_</span></tt>. A
|
||
<a class="reference external" href="reference.html#parameterspec"><span class="concept">ParameterSpec</span></a> enumerates the required and optional parameters in
|
||
their positional order, along with any type requirements (note that
|
||
it does <em>not</em> specify defaults -- those will be dealt with
|
||
separately):</p>
|
||
<pre class="literal-block">
|
||
namespace boost { namespace python {
|
||
|
||
using boost::mpl::_;
|
||
|
||
typedef parameter::parameters<
|
||
required<tag::class_type, boost::is_class<_> >
|
||
, parameter::optional<tag::base_list, mpl::is_sequence<_> >
|
||
, parameter::optional<tag::held_type>
|
||
, parameter::optional<tag::copyable>
|
||
> class_signature;
|
||
|
||
}}
|
||
</pre>
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter.hpp>
|
||
#include <boost/mpl/is_sequence.hpp>
|
||
#include <boost/noncopyable.hpp>
|
||
#include <boost/type_traits/is_class.hpp>
|
||
#include <memory>
|
||
|
||
using namespace boost::parameter;
|
||
|
||
namespace boost { namespace python {
|
||
|
||
BOOST_PARAMETER_TEMPLATE_KEYWORD(class_type)
|
||
BOOST_PARAMETER_TEMPLATE_KEYWORD(base_list)
|
||
BOOST_PARAMETER_TEMPLATE_KEYWORD(held_type)
|
||
BOOST_PARAMETER_TEMPLATE_KEYWORD(copyable)
|
||
|
||
template <class B = int>
|
||
struct bases
|
||
{};
|
||
|
||
}}''') -->
|
||
</div>
|
||
<div class="section" id="argument-packs-and-parameter-extraction">
|
||
<span id="binding-intro"></span><h4>2.4.1.4 Argument Packs and Parameter Extraction</h4>
|
||
<p>Next, within the body of <tt class="docutils literal">class_</tt> , we use the <span class="concept">ParameterSpec</span>'s
|
||
nested <tt class="docutils literal">::bind< … ></tt> template to bundle the actual arguments into an
|
||
<a class="reference external" href="reference.html#argumentpack"><span class="concept">ArgumentPack</span></a> type, and then use the library's <tt class="docutils literal">value_type< … ></tt>
|
||
metafunction to extract “logical parameters”. <tt class="docutils literal">value_type< … ></tt> is
|
||
a lot like <tt class="docutils literal">binding< … ></tt>, but no reference is added to the actual
|
||
argument type. Note that defaults are specified by passing it an
|
||
optional third argument:</p>
|
||
<pre class="literal-block">
|
||
namespace boost { namespace python {
|
||
|
||
template <
|
||
class A0
|
||
, class A1 = parameter::void_
|
||
, class A2 = parameter::void_
|
||
, class A3 = parameter::void_
|
||
>
|
||
struct class_
|
||
{
|
||
// Create ArgumentPack
|
||
typedef typename
|
||
class_signature::bind<A0,A1,A2,A3>::type
|
||
args;
|
||
|
||
// Extract first logical parameter.
|
||
typedef typename parameter::value_type<
|
||
args, tag::class_type>::type class_type;
|
||
|
||
typedef typename parameter::value_type<
|
||
args, tag::base_list, bases<> >::type base_list;
|
||
|
||
typedef typename parameter::value_type<
|
||
args, tag::held_type, class_type>::type held_type;
|
||
|
||
typedef typename parameter::value_type<
|
||
args, tag::copyable, void>::type copyable;
|
||
};
|
||
|
||
}}
|
||
</pre>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="exercising-the-code-so-far">
|
||
<h3>2.4.2 Exercising the Code So Far</h3>
|
||
<div class="compound">
|
||
<p class="compound-first">Revisiting our original examples,</p>
|
||
<pre class="compound-middle literal-block">
|
||
typedef boost::python::class_<
|
||
class_type<B>, copyable<boost::noncopyable>
|
||
> c1;
|
||
|
||
typedef boost::python::class_<
|
||
D, held_type<std::auto_ptr<D> >, base_list<bases<B> >
|
||
> c2;
|
||
</pre>
|
||
<!-- @example.prepend('''
|
||
using boost::python::class_type;
|
||
using boost::python::copyable;
|
||
using boost::python::held_type;
|
||
using boost::python::base_list;
|
||
using boost::python::bases;
|
||
|
||
struct B {};
|
||
struct D {};''') -->
|
||
<p class="compound-middle">we can now examine the intended parameters:</p>
|
||
<pre class="compound-last literal-block">
|
||
BOOST_MPL_ASSERT((boost::is_same<c1::class_type, B>));
|
||
BOOST_MPL_ASSERT((boost::is_same<c1::base_list, bases<> >));
|
||
BOOST_MPL_ASSERT((boost::is_same<c1::held_type, B>));
|
||
BOOST_MPL_ASSERT((
|
||
boost::is_same<c1::copyable, boost::noncopyable>
|
||
));
|
||
|
||
BOOST_MPL_ASSERT((boost::is_same<c2::class_type, D>));
|
||
BOOST_MPL_ASSERT((boost::is_same<c2::base_list, bases<B> >));
|
||
BOOST_MPL_ASSERT((
|
||
boost::is_same<c2::held_type, std::auto_ptr<D> >
|
||
));
|
||
BOOST_MPL_ASSERT((boost::is_same<c2::copyable, void>));
|
||
</pre>
|
||
</div>
|
||
<!-- @test('compile', howmany='all') -->
|
||
</div>
|
||
<div class="section" id="deduced-template-parameters">
|
||
<h3>2.4.3 Deduced Template Parameters</h3>
|
||
<p>To apply a deduced parameter interface here, we need only make the
|
||
type requirements a bit tighter so the <tt class="docutils literal">held_type</tt> and
|
||
<tt class="docutils literal">copyable</tt> parameters can be crisply distinguished from the
|
||
others. <a class="reference external" href="../../../python/doc/index.html">Boost.Python</a> does this by requiring that <tt class="docutils literal">base_list</tt> be
|
||
a specialization of its <tt class="docutils literal">bases< … ></tt> template (as opposed to
|
||
being any old MPL sequence) and by requiring that <tt class="docutils literal">copyable</tt>, if
|
||
explicitly supplied, be <tt class="docutils literal"><span class="pre">boost::noncopyable</span></tt>. One easy way of
|
||
identifying specializations of <tt class="docutils literal">bases< … ></tt> is to derive them all
|
||
from the same class, as an implementation detail:</p>
|
||
<pre class="literal-block">
|
||
namespace boost { namespace python {
|
||
|
||
namespace detail { struct bases_base {}; }
|
||
|
||
template <class A0 = void, class A1 = void, class A2 = void <em>…</em> >
|
||
struct bases <strong>: detail::bases_base</strong>
|
||
{};
|
||
|
||
}}
|
||
</pre>
|
||
<!-- @example.replace_emphasis('') -->
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter.hpp>
|
||
#include <boost/mpl/is_sequence.hpp>
|
||
#include <boost/noncopyable.hpp>
|
||
#include <memory>
|
||
|
||
using namespace boost::parameter;
|
||
using boost::mpl::_;
|
||
|
||
namespace boost { namespace python {
|
||
|
||
BOOST_PARAMETER_TEMPLATE_KEYWORD(class_type)
|
||
BOOST_PARAMETER_TEMPLATE_KEYWORD(base_list)
|
||
BOOST_PARAMETER_TEMPLATE_KEYWORD(held_type)
|
||
BOOST_PARAMETER_TEMPLATE_KEYWORD(copyable)
|
||
|
||
}}''') -->
|
||
<p>Now we can rewrite our signature to make all three optional
|
||
parameters deducible:</p>
|
||
<pre class="literal-block">
|
||
typedef parameter::parameters<
|
||
required<tag::class_type, is_class<_> >
|
||
|
||
, parameter::optional<
|
||
deduced<tag::base_list>
|
||
, is_base_and_derived<detail::bases_base,_>
|
||
>
|
||
|
||
, parameter::optional<
|
||
deduced<tag::held_type>
|
||
, mpl::not_<
|
||
mpl::or_<
|
||
is_base_and_derived<detail::bases_base,_>
|
||
, is_same<noncopyable,_>
|
||
>
|
||
>
|
||
>
|
||
|
||
, parameter::optional<deduced<tag::copyable>, is_same<noncopyable,_> >
|
||
|
||
> class_signature;
|
||
</pre>
|
||
<!-- @example.prepend('''
|
||
#include <boost/type_traits/is_class.hpp>
|
||
namespace boost { namespace python {''') -->
|
||
<!-- @example.append('''
|
||
template <
|
||
class A0
|
||
, class A1 = parameter::void_
|
||
, class A2 = parameter::void_
|
||
, class A3 = parameter::void_
|
||
>
|
||
struct class_
|
||
{
|
||
// Create ArgumentPack
|
||
typedef typename
|
||
class_signature::bind<A0,A1,A2,A3>::type
|
||
args;
|
||
|
||
// Extract first logical parameter.
|
||
typedef typename parameter::value_type<
|
||
args, tag::class_type>::type class_type;
|
||
|
||
typedef typename parameter::value_type<
|
||
args, tag::base_list, bases<> >::type base_list;
|
||
|
||
typedef typename parameter::value_type<
|
||
args, tag::held_type, class_type>::type held_type;
|
||
|
||
typedef typename parameter::value_type<
|
||
args, tag::copyable, void>::type copyable;
|
||
};
|
||
|
||
}}''') -->
|
||
<p>It may seem like we've added a great deal of complexity, but the
|
||
benefits to our users are greater. Our original examples can now
|
||
be written without explicit parameter names:</p>
|
||
<pre class="literal-block">
|
||
typedef boost::python::class_<<strong>B</strong>, <strong>boost::noncopyable</strong>> c1;
|
||
|
||
typedef boost::python::class_<<strong>D</strong>, <strong>std::auto_ptr<D></strong>, <strong>bases<B></strong> > c2;
|
||
</pre>
|
||
<!-- @example.prepend('''
|
||
struct B {};
|
||
struct D {};
|
||
|
||
using boost::python::bases;''') -->
|
||
<!-- @example.append('''
|
||
BOOST_MPL_ASSERT((boost::is_same<c1::class_type, B>));
|
||
BOOST_MPL_ASSERT((boost::is_same<c1::base_list, bases<> >));
|
||
BOOST_MPL_ASSERT((boost::is_same<c1::held_type, B>));
|
||
BOOST_MPL_ASSERT((
|
||
boost::is_same<c1::copyable, boost::noncopyable>
|
||
));
|
||
|
||
BOOST_MPL_ASSERT((boost::is_same<c2::class_type, D>));
|
||
BOOST_MPL_ASSERT((boost::is_same<c2::base_list, bases<B> >));
|
||
BOOST_MPL_ASSERT((
|
||
boost::is_same<c2::held_type, std::auto_ptr<D> >
|
||
));
|
||
BOOST_MPL_ASSERT((boost::is_same<c2::copyable, void>));''') -->
|
||
<!-- @test('compile', howmany='all') -->
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="advanced-topics">
|
||
<h1><a class="toc-backref" href="#id31">3 Advanced Topics</a></h1>
|
||
<p>At this point, you should have a good grasp of the basics. In this
|
||
section we'll cover some more esoteric uses of the library.</p>
|
||
<div class="section" id="fine-grained-name-control">
|
||
<h2><a class="toc-backref" href="#id32">3.1 Fine-Grained Name Control</a></h2>
|
||
<p>If you don't like the leading-underscore naming convention used
|
||
to refer to keyword objects, or you need the name <tt class="docutils literal">tag</tt> for
|
||
something other than the keyword type namespace, there's another
|
||
way to use <tt class="docutils literal">BOOST_PARAMETER_NAME</tt>:</p>
|
||
<pre class="literal-block">
|
||
BOOST_PARAMETER_NAME(<strong>(</strong><em>object-name</em><strong>,</strong> <em>tag-namespace</em><strong>)</strong> <em>parameter-name</em>)
|
||
</pre>
|
||
<!-- @ignore() -->
|
||
<p>Here is a usage example:</p>
|
||
<pre class="literal-block">
|
||
BOOST_PARAMETER_NAME((<strong>pass_foo</strong>, <strong>keywords</strong>) <strong>foo</strong>)
|
||
|
||
BOOST_PARAMETER_FUNCTION(
|
||
(int), f,
|
||
<strong>keywords</strong>, (required (<strong>foo</strong>, *)))
|
||
{
|
||
return <strong>foo</strong> + 1;
|
||
}
|
||
|
||
int x = f(<strong>pass_foo</strong> = 41);
|
||
</pre>
|
||
<!-- @example.prepend('#include <boost/parameter.hpp>') -->
|
||
<!-- @example.append('''
|
||
int main()
|
||
{}''') -->
|
||
<!-- @test('run') -->
|
||
<p>Before you use this more verbose form, however, please read the
|
||
section on <a class="reference internal" href="#keyword-naming">best practices for keyword object naming</a>.</p>
|
||
</div>
|
||
<div class="section" id="more-argumentpacks">
|
||
<h2><a class="toc-backref" href="#id33">3.2 More <span class="concept">ArgumentPack</span>s</a></h2>
|
||
<p>We've already seen <span class="concept">ArgumentPack</span>s when we looked at
|
||
<a class="reference internal" href="#parameter-enabled-constructors">parameter-enabled constructors</a> and <a class="reference internal" href="#binding-intro">class templates</a>. As you
|
||
might have guessed, <span class="concept">ArgumentPack</span>s actually lie at the heart of
|
||
everything this library does; in this section we'll examine ways to
|
||
build and manipulate them more effectively.</p>
|
||
<div class="section" id="building-argumentpacks">
|
||
<h3>3.2.1 Building <span class="concept">ArgumentPack</span>s</h3>
|
||
<p>The simplest <span class="concept">ArgumentPack</span> is the result of assigning into a
|
||
keyword object:</p>
|
||
<pre class="literal-block">
|
||
BOOST_PARAMETER_NAME(index)
|
||
|
||
template <class ArgumentPack>
|
||
int print_index(ArgumentPack const& args)
|
||
{
|
||
std::cout << "index = " << args[_index] << std::endl;
|
||
return 0;
|
||
}
|
||
|
||
int x = print_index(_index = 3); // prints "index = 3"
|
||
</pre>
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter.hpp>
|
||
#include <iostream>''') -->
|
||
<p>Also, <span class="concept">ArgumentPack</span>s can be composed using the comma operator.
|
||
The extra parentheses below are used to prevent the compiler from
|
||
seeing two separate arguments to <tt class="docutils literal">print_name_and_index</tt>:</p>
|
||
<pre class="literal-block">
|
||
BOOST_PARAMETER_NAME(name)
|
||
|
||
template <class ArgumentPack>
|
||
int print_name_and_index(ArgumentPack const& args)
|
||
{
|
||
std::cout << "name = " << args[_name] << "; ";
|
||
return print_index(args);
|
||
}
|
||
|
||
int y = print_name_and_index((_index = 3, _name = "jones"));
|
||
</pre>
|
||
<p>To build an <span class="concept">ArgumentPack</span> with positional arguments, we can use a
|
||
<a class="reference external" href="reference.html#parameterspec"><span class="concept">ParameterSpec</span></a>. As introduced described in the section on <a class="reference internal" href="#class-template-signatures">Class
|
||
Template Signatures</a>, a <span class="concept">ParameterSpec</span> describes the positional
|
||
order of parameters and any associated type requirements. Just as
|
||
we can build an <span class="concept">ArgumentPack</span> <em>type</em> with its nested <tt class="docutils literal">::bind< …
|
||
></tt> template, we can build an <span class="concept">ArgumentPack</span> <em>object</em> by invoking
|
||
its function call operator:</p>
|
||
<pre class="literal-block">
|
||
parameter::parameters<
|
||
required<tag::name, is_convertible<_,char const*> >
|
||
, optional<tag::index, is_convertible<_,int> >
|
||
> spec;
|
||
|
||
char const sam[] = "sam";
|
||
int twelve = 12;
|
||
|
||
int z0 = print_name_and_index( <strong>spec(</strong>sam, twelve<strong>)</strong> );
|
||
|
||
int z1 = print_name_and_index(
|
||
<strong>spec(</strong>_index=12, _name="sam"<strong>)</strong>
|
||
);
|
||
</pre>
|
||
<!-- @example.prepend('''
|
||
namespace parameter = boost::parameter;
|
||
using parameter::required;
|
||
using parameter::optional;
|
||
using boost::is_convertible;
|
||
using boost::mpl::_;''') -->
|
||
<!-- @example.append('''
|
||
int main()
|
||
{}''') -->
|
||
<!-- @test('run', howmany='all') -->
|
||
<p>Note that because of the <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2002/n1385.htm">forwarding problem</a>, <tt class="docutils literal"><span class="pre">parameter::parameters::operator()</span></tt>
|
||
can't accept non-const rvalues.</p>
|
||
</div>
|
||
<div class="section" id="extracting-parameter-types">
|
||
<h3>3.2.2 Extracting Parameter Types</h3>
|
||
<p>If we want to know the types of the arguments passed to
|
||
<tt class="docutils literal">print_name_and_index</tt>, we have a couple of options. The
|
||
simplest and least error-prone approach is to forward them to a
|
||
function template and allow <em>it</em> to do type deduction:</p>
|
||
<pre class="literal-block">
|
||
BOOST_PARAMETER_NAME(name)
|
||
BOOST_PARAMETER_NAME(index)
|
||
|
||
template <class Name, class Index>
|
||
int deduce_arg_types_impl(Name& name, Index& index)
|
||
{
|
||
Name& n2 = name; // we know the types
|
||
Index& i2 = index;
|
||
return index;
|
||
}
|
||
|
||
template <class ArgumentPack>
|
||
int deduce_arg_types(ArgumentPack const& args)
|
||
{
|
||
return deduce_arg_types_impl(args[_name], args[_index|42]);
|
||
}
|
||
</pre>
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter.hpp>
|
||
#include <cassert>''') -->
|
||
<!-- @example.append('''
|
||
int a1 = deduce_arg_types((_name = "foo"));
|
||
int a2 = deduce_arg_types((_name = "foo", _index = 3));
|
||
|
||
int main()
|
||
{
|
||
assert(a1 == 42);
|
||
assert(a2 == 3);
|
||
}''') -->
|
||
<!-- @test('run') -->
|
||
<p>Occasionally one needs to deduce argument types without an extra
|
||
layer of function call. For example, suppose we wanted to return
|
||
twice the value of the <tt class="docutils literal">index</tt> parameter? In that
|
||
case we can use the <tt class="docutils literal">value_type< … ></tt> metafunction introduced
|
||
<a class="reference internal" href="#binding-intro">earlier</a>:</p>
|
||
<pre class="literal-block">
|
||
BOOST_PARAMETER_NAME(index)
|
||
|
||
template <class ArgumentPack>
|
||
typename parameter::value_type<ArgumentPack, tag::index, int>::type
|
||
twice_index(ArgumentPack const& args)
|
||
{
|
||
return 2 * args[_index|42];
|
||
}
|
||
|
||
int six = twice_index(_index = 3);
|
||
</pre>
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter.hpp>
|
||
#include <boost/type_traits/remove_reference.hpp>
|
||
#include <cassert>
|
||
|
||
namespace parameter = boost::parameter;
|
||
''') -->
|
||
<!-- @example.append('''
|
||
int main()
|
||
{
|
||
assert(six == 6);
|
||
}''') -->
|
||
<!-- @test('run', howmany='all') -->
|
||
<p>Note that if we had used <tt class="docutils literal">binding< … ></tt> rather than <tt class="docutils literal">value_type< …
|
||
></tt>, we would end up returning a reference to the temporary created in
|
||
the <tt class="docutils literal">2 * …</tt> expression.</p>
|
||
</div>
|
||
<div class="section" id="lazy-default-computation">
|
||
<h3>3.2.3 Lazy Default Computation</h3>
|
||
<p>When a default value is expensive to compute, it would be
|
||
preferable to avoid it until we're sure it's absolutely necessary.
|
||
<tt class="docutils literal">BOOST_PARAMETER_FUNCTION</tt> takes care of that problem for us, but
|
||
when using <span class="concept">ArgumentPack</span>s explicitly, we need a tool other than
|
||
<tt class="docutils literal">operator|</tt>:</p>
|
||
<pre class="literal-block">
|
||
BOOST_PARAMETER_NAME(s1)
|
||
BOOST_PARAMETER_NAME(s2)
|
||
BOOST_PARAMETER_NAME(s3)
|
||
|
||
template <class ArgumentPack>
|
||
std::string f(ArgumentPack const& args)
|
||
{
|
||
std::string const& s1 = args[_s1];
|
||
std::string const& s2 = args[_s2];
|
||
typename parameter::binding<
|
||
ArgumentPack,tag::s3,std::string
|
||
>::type s3 = args[_s3|(s1+s2)]; // always constructs s1+s2
|
||
return s3;
|
||
}
|
||
|
||
std::string x = f((_s1="hello,", _s2=" world", _s3="hi world"));
|
||
</pre>
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter.hpp>
|
||
#include <string>
|
||
|
||
namespace parameter = boost::parameter;''') -->
|
||
<!-- @example.append('''
|
||
int main()
|
||
{}''') -->
|
||
<!-- @test('run') -->
|
||
<p>In the example above, the string <tt class="docutils literal">"hello, world"</tt> is constructed
|
||
despite the fact that the user passed us a value for <tt class="docutils literal">s3</tt>. To
|
||
remedy that, we can compute the default value <em>lazily</em> (that is,
|
||
only on demand), by using <tt class="docutils literal"><span class="pre">boost::bind()</span></tt> to create a function
|
||
object.</p>
|
||
<!-- danielw: I'm leaving the text below in the source, because we might -->
|
||
<!-- want to change back to it after 1.34, and if I remove it now we -->
|
||
<!-- might forget about it. -->
|
||
<!-- by combining the logical-or (“``||``”) operator -->
|
||
<!-- with a function object built by the Boost Lambda_ library: [#bind]_ -->
|
||
<pre class="literal-block">
|
||
typename parameter::binding<
|
||
ArgumentPack, <a class="reference external" href="tag::s3">tag::s3</a>, std::string
|
||
>::type s3 = args[_s3
|
||
<strong>|| boost::bind(std::plus<std::string>(), boost::ref(s1), boost::ref(s2))</strong> ];
|
||
</pre>
|
||
<!-- @example.prepend('''
|
||
#include <boost/bind.hpp>
|
||
#include <boost/ref.hpp>
|
||
#include <boost/parameter.hpp>
|
||
#include <string>
|
||
#include <functional>
|
||
|
||
namespace parameter = boost::parameter;
|
||
|
||
BOOST_PARAMETER_NAME(s1)
|
||
BOOST_PARAMETER_NAME(s2)
|
||
BOOST_PARAMETER_NAME(s3)
|
||
|
||
template <class ArgumentPack>
|
||
std::string f(ArgumentPack const& args)
|
||
{
|
||
std::string const& s1 = args[_s1];
|
||
std::string const& s2 = args[_s2];''') -->
|
||
<!-- @example.append('''
|
||
return s3;
|
||
}
|
||
|
||
std::string x = f((_s1="hello,", _s2=" world", _s3="hi world"));
|
||
|
||
int main()
|
||
{}''') -->
|
||
<!-- @test('run') -->
|
||
<!-- .. _Lambda: ../../../lambda/index.html -->
|
||
<div class="sidebar">
|
||
<p class="first sidebar-title">Mnemonics</p>
|
||
<p class="last">To remember the difference between <tt class="docutils literal">|</tt> and <tt class="docutils literal">||</tt>, recall that
|
||
<tt class="docutils literal">||</tt> normally uses short-circuit evaluation: its second
|
||
argument is only evaluated if its first argument is <tt class="docutils literal">false</tt>.
|
||
Similarly, in <tt class="docutils literal"><span class="pre">color_map[param||f]</span></tt>, <tt class="docutils literal">f</tt> is only invoked if
|
||
no <tt class="docutils literal">color_map</tt> argument was supplied.</p>
|
||
</div>
|
||
<p>The expression <tt class="docutils literal"><span class="pre">bind(std::plus<std::string>(),</span> ref(s1), ref(s2))</tt> yields
|
||
a <em>function object</em> that, when invoked, adds the two strings together.
|
||
That function will only be invoked if no <tt class="docutils literal">s3</tt> argument is supplied by
|
||
the caller.</p>
|
||
<!-- The expression ``lambda::var(s1)+lambda::var(s2)`` yields a -->
|
||
<!-- *function object* that, when invoked, adds the two strings -->
|
||
<!-- together. That function will only be invoked if no ``s3`` argument -->
|
||
<!-- is supplied by the caller. -->
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="best-practices">
|
||
<h1><a class="toc-backref" href="#id34">4 Best Practices</a></h1>
|
||
<p>By now you should have a fairly good idea of how to use the
|
||
Parameter library. This section points out a few more-marginal
|
||
issues that will help you use the library more effectively.</p>
|
||
<div class="section" id="keyword-naming">
|
||
<h2><a class="toc-backref" href="#id35">4.1 Keyword Naming</a></h2>
|
||
<p><tt class="docutils literal">BOOST_PARAMETER_NAME</tt> prepends a leading underscore to the names
|
||
of all our keyword objects in order to avoid the following
|
||
usually-silent bug:</p>
|
||
<pre class="literal-block">
|
||
namespace people
|
||
{
|
||
namespace tag { struct name; struct age; }
|
||
|
||
namespace // unnamed
|
||
{
|
||
boost::parameter::keyword<tag::name>& <strong>name</strong>
|
||
= boost::parameter::keyword<tag::name>::instance;
|
||
boost::parameter::keyword<tag::age>& <strong>age</strong>
|
||
= boost::parameter::keyword<tag::age>::instance;
|
||
}
|
||
|
||
BOOST_PARAMETER_FUNCTION(
|
||
(void), g, tag, (optional (name, *, "bob")(age, *, 42)))
|
||
{
|
||
std::cout << name << ":" << age;
|
||
}
|
||
|
||
void f(int age)
|
||
{
|
||
<span class="vellipsis"> .
|
||
.
|
||
.
|
||
</span>
|
||
g(<strong>age</strong> = 3); // whoops!
|
||
}
|
||
}
|
||
</pre>
|
||
<!-- @ignore() -->
|
||
<p>Although in the case above, the user was trying to pass the value
|
||
<tt class="docutils literal">3</tt> as the <tt class="docutils literal">age</tt> parameter to <tt class="docutils literal">g</tt>, what happened instead
|
||
was that <tt class="docutils literal">f</tt>'s <tt class="docutils literal">age</tt> argument got reassigned the value 3,
|
||
and was then passed as a positional argument to <tt class="docutils literal">g</tt>. Since
|
||
<tt class="docutils literal">g</tt>'s first positional parameter is <tt class="docutils literal">name</tt>, the default value
|
||
for <tt class="docutils literal">age</tt> is used, and g prints <tt class="docutils literal">3:42</tt>. Our leading
|
||
underscore naming convention that makes this problem less likely
|
||
to occur.</p>
|
||
<p>In this particular case, the problem could have been detected if
|
||
f's <tt class="docutils literal">age</tt> parameter had been made <tt class="docutils literal">const</tt>, which is always a
|
||
good idea whenever possible. Finally, we recommend that you use
|
||
an enclosing namespace for all your code, but particularly for
|
||
names with leading underscores. If we were to leave out the
|
||
<tt class="docutils literal">people</tt> namespace above, names in the global namespace
|
||
beginning with leading underscores—which are reserved to your C++
|
||
compiler—might become irretrievably ambiguous with those in our
|
||
unnamed namespace.</p>
|
||
</div>
|
||
<div class="section" id="namespaces">
|
||
<h2><a class="toc-backref" href="#id36">4.2 Namespaces</a></h2>
|
||
<p>In our examples we've always declared keyword objects in (an
|
||
unnamed namespace within) the same namespace as the
|
||
Boost.Parameter-enabled functions using those keywords:</p>
|
||
<pre class="literal-block">
|
||
namespace lib
|
||
{
|
||
<strong>BOOST_PARAMETER_NAME(name)
|
||
BOOST_PARAMETER_NAME(index)</strong>
|
||
|
||
BOOST_PARAMETER_FUNCTION(
|
||
(int), f, tag,
|
||
(optional (name,*,"bob")(index,(int),1))
|
||
)
|
||
{
|
||
std::cout << name << ":" << index << std::endl;
|
||
return index;
|
||
}
|
||
}
|
||
</pre>
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter.hpp>
|
||
#include <iostream>''') -->
|
||
<!-- @namespace_setup = str(example) -->
|
||
<!-- @ignore() -->
|
||
<p>Users of these functions have a few choices:</p>
|
||
<ol class="arabic simple">
|
||
<li>Full qualification:</li>
|
||
</ol>
|
||
<blockquote>
|
||
<pre class="literal-block">
|
||
int x = <strong>lib::</strong>f(<strong>lib::</strong>_name = "jill", <strong>lib::</strong>_index = 1);
|
||
</pre>
|
||
<p>This approach is more verbose than many users would like.</p>
|
||
</blockquote>
|
||
<!-- @example.prepend(namespace_setup) -->
|
||
<!-- @example.append('int main() {}') -->
|
||
<!-- @test('run') -->
|
||
<ol class="arabic simple" start="2">
|
||
<li>Make keyword objects available through
|
||
<em>using-declarations</em>:</li>
|
||
</ol>
|
||
<blockquote>
|
||
<pre class="literal-block">
|
||
<strong>using lib::_name;
|
||
using lib::_index;</strong>
|
||
|
||
int x = lib::f(_name = "jill", _index = 1);
|
||
</pre>
|
||
<p>This version is much better at the actual call site, but the
|
||
<em>using-declarations</em> themselves can be verbose and hard-to
|
||
manage.</p>
|
||
</blockquote>
|
||
<!-- @example.prepend(namespace_setup) -->
|
||
<!-- @example.append('int main() {}') -->
|
||
<!-- @test('run') -->
|
||
<ol class="arabic simple" start="3">
|
||
<li>Bring in the entire namespace with a <em>using-directive</em>:</li>
|
||
</ol>
|
||
<blockquote>
|
||
<pre class="literal-block">
|
||
<strong>using namespace lib;</strong>
|
||
int x = <strong>f</strong>(_name = "jill", _index = 3);
|
||
</pre>
|
||
<p>This option is convenient, but it indiscriminately makes the
|
||
<em>entire</em> contents of <tt class="docutils literal">lib</tt> available without qualification.</p>
|
||
</blockquote>
|
||
<!-- @example.prepend(namespace_setup) -->
|
||
<!-- @example.append('int main() {}') -->
|
||
<!-- @test('run') -->
|
||
<p>If we add an additional namespace around keyword declarations,
|
||
though, we can give users more control:</p>
|
||
<pre class="literal-block">
|
||
namespace lib
|
||
{
|
||
<strong>namespace keywords
|
||
{</strong>
|
||
BOOST_PARAMETER_NAME(name)
|
||
BOOST_PARAMETER_NAME(index)
|
||
<strong>}</strong>
|
||
|
||
BOOST_PARAMETER_FUNCTION(
|
||
(int), f, <strong>keywords::</strong>tag,
|
||
(optional (name,*,"bob")(index,(int),1))
|
||
)
|
||
{
|
||
std::cout << name << ":" << index << std::endl;
|
||
return index;
|
||
}
|
||
}
|
||
</pre>
|
||
<!-- @example.prepend('''
|
||
#include <boost/parameter.hpp>
|
||
#include <iostream>''') -->
|
||
<p>Now users need only a single <em>using-directive</em> to bring in just the
|
||
names of all keywords associated with <tt class="docutils literal">lib</tt>:</p>
|
||
<pre class="literal-block">
|
||
<strong>using namespace lib::keywords;</strong>
|
||
int y = lib::f(_name = "bob", _index = 2);
|
||
</pre>
|
||
<!-- @example.append('int main() {}') -->
|
||
<!-- @test('run', howmany='all') -->
|
||
</div>
|
||
<div class="section" id="documentation">
|
||
<h2><a class="toc-backref" href="#id37">4.3 Documentation</a></h2>
|
||
<p>The interface idioms enabled by Boost.Parameter are completely new
|
||
(to C++), and as such are not served by pre-existing documentation
|
||
conventions.</p>
|
||
<div class="note">
|
||
<p class="first admonition-title">Note</p>
|
||
<p class="last">This space is empty because we haven't settled on any
|
||
best practices yet. We'd be very pleased to link to your
|
||
documentation if you've got a style that you think is worth
|
||
sharing.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="portability-considerations">
|
||
<h1><a class="toc-backref" href="#id38">5 Portability Considerations</a></h1>
|
||
<p>Use the <a class="reference external" 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" id="no-sfinae-support">
|
||
<h2><a class="toc-backref" href="#id39">5.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">#define</tt> the preprocessor
|
||
symbol <tt class="docutils literal">BOOST_NO_SFINAE</tt>, and parameter-enabled functions won't be
|
||
removed from the overload set based on their signatures.</p>
|
||
</div>
|
||
<div class="section" id="no-support-for-result-of">
|
||
<h2>5.2 No Support for <a class="reference external" href="../../../utility/utility.htm#result_of"><tt class="docutils literal">result_of</tt></a></h2>
|
||
<p><a class="reference internal" href="#lazy-default-computation">Lazy default computation</a> relies on the <tt class="docutils literal">result_of</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">result_of</tt>, <tt class="docutils literal">BOOST_NO_RESULT_OF</tt> will be
|
||
<tt class="docutils literal">#define</tt>d, and the compiler will expect the function object to
|
||
contain a nested type name, <tt class="docutils literal">result_type</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">result_type</tt> as a <tt class="docutils literal">typedef</tt>
|
||
and invokes the function via its <tt class="docutils literal">operator()</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" id="compiler-can-t-see-references-in-unnamed-namespace">
|
||
<h2><a class="toc-backref" href="#id41">5.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" id="python-binding">
|
||
<h1><a class="toc-backref" href="#id42">6 Python Binding</a></h1>
|
||
<p>Follow <a class="reference external" href="python.html">this link</a> for documentation on how to expose
|
||
Boost.Parameter-enabled functions to Python with <a class="reference external" href="../../../python/doc/index.html">Boost.Python</a>.</p>
|
||
</div>
|
||
<div class="section" id="reference">
|
||
<h1><a class="toc-backref" href="#id43">7 Reference</a></h1>
|
||
<p>Follow <a class="reference external" href="reference.html">this link</a> to the Boost.Parameter reference
|
||
documentation.</p>
|
||
</div>
|
||
<div class="section" id="glossary">
|
||
<h1><a class="toc-backref" href="#id44">8 Glossary</a></h1>
|
||
<table class="docutils field-list" frame="void" id="arguments" rules="none">
|
||
<col class="field-name" />
|
||
<col class="field-body" />
|
||
<tbody valign="top">
|
||
<tr class="field"><th class="field-name" colspan="2">Argument (or “actual argument”):</th></tr>
|
||
<tr><td> </td><td class="field-body">the value actually passed to a
|
||
function or class template</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<table class="docutils field-list" frame="void" id="parameter" rules="none">
|
||
<col class="field-name" />
|
||
<col class="field-body" />
|
||
<tbody valign="top">
|
||
<tr class="field"><th class="field-name" colspan="2">Parameter (or “formal parameter”):</th></tr>
|
||
<tr><td> </td><td class="field-body"><p class="first">the name used to refer to an
|
||
argument within a function or class template. For example, the
|
||
value of <tt class="docutils literal">f</tt>'s <em>parameter</em> <tt class="docutils literal">x</tt> is given by the <em>argument</em>
|
||
<tt class="docutils literal">3</tt>:</p>
|
||
<pre class="last literal-block">
|
||
int f(int x) { return x + 1 }
|
||
int y = f(3);
|
||
</pre>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
<div class="section" id="acknowledgements">
|
||
<h1><a class="toc-backref" href="#id45">9 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="#id3">[1]</a></td><td>As of Boost 1.33.0 the Graph library was still
|
||
using an <a class="reference external" 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">[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">[3]</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">int</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="conceptcpp" rules="none">
|
||
<colgroup><col class="label" /><col /></colgroup>
|
||
<tbody valign="top">
|
||
<tr><td class="label"><a class="fn-backref" href="#id7">[4]</a></td><td>This is a major motivation behind <a class="reference external" href="http://www.generic-programming.org/software/ConceptGCC/">ConceptC++</a>.</td></tr>
|
||
</tbody>
|
||
</table>
|
||
<!-- .. [#bind] The Lambda library is known not to work on `some -->
|
||
<!-- less-conformant compilers`__. When using one of those you could -->
|
||
<!-- use `Boost.Bind`_ to generate the function object:: -->
|
||
<!-- boost::bind(std::plus<std::string>(),s1,s2) -->
|
||
<table class="docutils footnote" frame="void" id="is-keyword-expression" rules="none">
|
||
<colgroup><col class="label" /><col /></colgroup>
|
||
<tbody valign="top">
|
||
<tr><td class="label">[5]</td><td><em>(<a class="fn-backref" href="#id13">1</a>, <a class="fn-backref" href="#id14">2</a>)</em> Here we're assuming there's a predicate
|
||
metafunction <tt class="docutils literal">is_keyword_expression</tt> that can be used to
|
||
identify models of Boost.Python's KeywordExpression concept.</td></tr>
|
||
</tbody>
|
||
</table>
|
||
<!-- .. __ http://www.boost.org/regression/release/user/lambda.html -->
|
||
<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">[6]</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">[7]</td><td>This capability depends on your compiler's support for SFINAE.
|
||
<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 external" href="../../../utility/enable_if.html"><tt class="docutils literal">enable_if</tt></a> utility. Most recent compilers support SFINAE;
|
||
on compilers that don't support it, the Boost config library
|
||
will <tt class="docutils literal">#define</tt> the symbol <tt class="docutils literal">BOOST_NO_SFINAE</tt>.
|
||
See
|
||
<a class="reference external" 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: 2011-11-08 21:40 UTC.
|
||
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
|
||
|
||
</div>
|
||
</body>
|
||
</html>
|