| <?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.6: 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>. <source>/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:dalwan01@student.umu.se">dalwan01@student.umu.se</a></td> |
| </tr> |
| <tr class="field"><th class="field-name">Organization:</th><td class="field-body"><a class="reference external" href="http://www.boost-consulting.com">Boost Consulting</a></td> |
| </tr> |
| <tr class="field"><th class="field-name">Date:</th><td class="field-body">$Date: 2005/07/18 20:34:31 $</td> |
| </tr> |
| <tr class="field"><th class="field-name">Copyright:</th><td class="field-body">Copyright David Abrahams, Daniel Wallin 2005. |
| Distributed under the Boost Software License, |
| Version 1.0. (See accompanying file LICENSE_1_0.txt |
| or copy at <a class="reference 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"><span class="pre">result_of</span></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"><span class="pre">border_width</span></tt>, but instead we got a moveable |
| window with a <tt class="docutils literal"><span class="pre">border_width</span></tt> of zero. To get the desired |
| effect, we'd need to write:</p> |
| <pre class="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"><span class="pre">name</span></tt> parameter to |
| <tt class="docutils literal"><span class="pre">new_window</span></tt> is one such example. None of the other arguments, |
| if valid, can reasonably be converted to a <tt class="docutils literal"><span class="pre">char</span> <span class="pre">const*</span></tt>. 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"><span class="pre">shared</span></tt> and |
| <tt class="docutils literal"><span class="pre">Client</span></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"><span class="pre">depth_first_search</span></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"><span class="pre">boost/parameter.hpp</span></tt>, that includes most of the library's |
| components. For the the rest of this tutorial, unless we say |
| otherwise, you can use the rule above to figure out which header |
| to <tt class="docutils literal"><span class="pre">#include</span></tt> to access any given component of the library.</p> |
| <!-- @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"><span class="pre">depth_first_search</span></tt></h3> |
| <p>The Graph library's <tt class="docutils literal"><span class="pre">depth_first_search</span></tt> algorithm is a generic function accepting |
| from one to four arguments by reference. If all arguments were |
| required, its signature might be as follows:</p> |
| <pre class="literal-block"> |
| template < |
| class Graph, class DFSVisitor, class Index, class ColorMap |
| > |
| void depth_first_search( |
| , Graph const& graph |
| , DFSVisitor visitor |
| , typename graph_traits<g>::vertex_descriptor root_vertex |
| , IndexMap index_map |
| , ColorMap& color); |
| </pre> |
| <!-- @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"><span class="pre">depth_first_search</span></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"><span class="pre">graph</span></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"><span class="pre">visitor</span></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"><span class="pre">root_vertex</span></tt></td> |
| <td>in</td> |
| <td><tt class="docutils literal"><span class="pre">graph</span></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"><span class="pre">index_map</span></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"><span class="pre">graph</span></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"><span class="pre">color_map</span></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"><span class="pre">graph</span></tt>'s |
| vertex descriptor type.</td> |
| <td>an <tt class="docutils literal"><span class="pre">iterator_property_map</span></tt> |
| created from a <tt class="docutils literal"><span class="pre">std::vector</span></tt> of |
| <tt class="docutils literal"><span class="pre">default_color_type</span></tt> of size |
| <tt class="docutils literal"><span class="pre">num_vertices(graph)</span></tt> and using |
| <tt class="docutils literal"><span class="pre">index_map</span></tt> for the index map.</td> |
| </tr> |
| </tbody> |
| </table> |
| <p>Don't be intimidated by the 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"><span class="pre">depth_first_search</span></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"><span class="pre">color_map_</span></tt>” whose assignment operator can accept a |
| <tt class="docutils literal"><span class="pre">my_color_map</span></tt> argument. In this step we'll create one such |
| <strong>keyword object</strong> for each parameter. Each keyword object will be |
| identified by a unique <strong>keyword tag type</strong>.</p> |
| <!-- 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"><span class="pre">graphs</span></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"><span class="pre">graph</span></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"><span class="pre">_graph</span></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"><span class="pre">BOOST_PARAMETER_FUNCTION</span></tt> macro:</p> |
| <pre class="literal-block"> |
| #include <boost/parameter/preprocessor.hpp> |
| |
| namespace graphs |
| { |
| BOOST_PARAMETER_FUNCTION( |
| (void), // 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"><span class="pre">BOOST_PARAMETER_FUNCTION</span></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"><span class="pre">(required</span> <span class="pre">…</span> <span class="pre">)</span></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"><span class="pre">(required</span> <span class="pre">…</span> <span class="pre">)</span></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"><span class="pre">depth_first_search</span></tt> doesn't require any particular type |
| for its <tt class="docutils literal"><span class="pre">graph</span></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"><span class="pre">(required</span> <span class="pre">…</span> <span class="pre">)</span></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"><span class="pre">(optional</span> <span class="pre">…</span> <span class="pre">)</span></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"><span class="pre">visitor</span></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"><span class="pre">T</span> <span class="pre">const&</span></tt> for |
| some <tt class="docutils literal"><span class="pre">T</span></tt>. Parameters whose values are expected to be modified, |
| however, must be passed by reference to <em>non</em>-<tt class="docutils literal"><span class="pre">const</span></tt>. To |
| indicate that <tt class="docutils literal"><span class="pre">color_map</span></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"><span class="pre">color_map</span></tt> were strictly going to be modified but not examined, |
| we could have written <tt class="docutils literal"><span class="pre">out(color_map)</span></tt>. There is no functional |
| difference between <tt class="docutils literal"><span class="pre">out</span></tt> and <tt class="docutils literal"><span class="pre">in_out</span></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"><span class="pre">x</span></tt> will always be interpreted as a graph and <tt class="docutils literal"><span class="pre">y</span></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"><span class="pre">root_vertex</span></tt>, |
| <tt class="docutils literal"><span class="pre">index_map</span></tt> and <tt class="docutils literal"><span class="pre">color_map</span></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"><span class="pre">depth_first_search</span></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"><span class="pre">graph</span></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"><span class="pre">depth_first_search</span></tt> with fewer than five arguments will match |
| our function, provided we pass <em>something</em> for the required |
| <tt class="docutils literal"><span class="pre">graph</span></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"><span class="pre">depth_first_search</span></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"><span class="pre">depth_first_search</span></tt> is instantiated, it has |
| been selected as the best matching overload. Some other |
| <tt class="docutils literal"><span class="pre">depth_first_search</span></tt> overload might've worked had it been |
| chosen instead. By the time we see a compilation error, there's |
| no chance to change that decision.</li> |
| <li>Even if there are no overloads, error messages generated at |
| instantiation time usually expose users to confusing |
| implementation details. For example, users might see references |
| to names generated by <tt class="docutils literal"><span class="pre">BOOST_PARAMETER_FUNCTION</span></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://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-defects.html#225">unqualified calls</a>. If all we want is to |
| avoid unintentional argument-dependent lookup (ADL), we can |
| isolate <tt class="docutils literal"><span class="pre">depth_first_search</span></tt> in a namespace containing no |
| types<a class="footnote-reference" href="#using" id="id8"><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"><span class="pre">graph</span></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"><span class="pre">depth_first_search</span></tt> because the <tt class="docutils literal"><span class="pre">root_vertex</span></tt> argument, |
| <tt class="docutils literal"><span class="pre">"hello"</span></tt>, doesn't meet the <a class="reference internal" href="#parameter-table">requirement</a> that it match the |
| <tt class="docutils literal"><span class="pre">graph</span></tt> parameter's vertex descriptor type. Instead, this call |
| should just invoke our new overload. To take the original |
| <tt class="docutils literal"><span class="pre">depth_first_search</span></tt> overload out of contention, we need to tell |
| the library about this requirement by replacing the <tt class="docutils literal"><span class="pre">*</span></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"><span class="pre">depth_first_search</span></tt> will only be called when |
| the <tt class="docutils literal"><span class="pre">root_vertex</span></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"><span class="pre">graph</span></tt> argument is available in the |
| signature—and in the function body—as <tt class="docutils literal"><span class="pre">graph_type</span></tt>. In |
| general, to access the type of any parameter <em>foo</em>, write <em>foo</em><tt class="docutils literal"><span class="pre">_type</span></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"><span class="pre">root_vertex</span></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"> |
| BOOST_PARAMETER_FUNCTION( |
| (void), depth_first_search, graphs |
| |
| , (required |
| (graph |
| , <strong>*(boost::mpl::and_< |
| boost::is_convertible< |
| boost::graph_traits<_>::traversal_category |
| , boost::incidence_graph_tag |
| > |
| , boost::is_convertible< |
| boost::graph_traits<_>::traversal_category |
| , boost::vertex_list_graph_tag |
| > |
| >)</strong> )) |
| |
| (optional |
| (visitor, *, boost::dfs_visitor<>()) // not checkable |
| |
| (root_vertex |
| , (typename boost::graph_traits<graphs::graph::_>::vertex_descriptor) |
| , *vertices(graph).first) |
| |
| (index_map |
| , <strong>*(boost::mpl::and_< |
| boost::is_integral< |
| boost::property_traits<_>::value_type |
| > |
| , boost::is_same< |
| typename boost::graph_traits<graphs::graph::_>::vertex_descriptor |
| , boost::property_traits<_>::key_type |
| > |
| >)</strong> |
| , get(boost::vertex_index,graph)) |
| |
| (in_out(color_map) |
| , <strong>*(boost::is_same< |
| typename boost::graph_traits<graphs::graph::_>::vertex_descriptor |
| , boost::property_traits<_>::key_type |
| >)</strong> |
| , default_color_map(num_vertices(graph), index_map) ) |
| ) |
| ) |
| </pre> |
| <!-- @example.prepend(''' |
| #include <boost/parameter.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::_; |
| |
| namespace boost |
| { |
| struct incidence_graph_tag {}; |
| struct vertex_list_graph_tag {}; |
| |
| int vertex_index = 0; |
| |
| template <class T> |
| struct graph_traits |
| { |
| typedef int traversal_category; |
| typedef int vertex_descriptor; |
| }; |
| |
| template <class T> |
| struct property_traits |
| { |
| typedef int value_type; |
| typedef int key_type; |
| }; |
| |
| template <class T = int> |
| struct dfs_visitor |
| {}; |
| }''') --> |
| <!-- @example.append(''' |
| {}''') --> |
| <!-- @test('compile') --> |
| <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"><span class="pre">def</span></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"><span class="pre">def</span></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"><span class="pre">BOOST_PARAMETER_FUNCTION</span></tt>, we need |
| only enclose the deduced parameters in a <tt class="docutils literal"><span class="pre">(deduced</span> <span class="pre">…)</span></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"><span class="pre">(deduced</span> <span class="pre">…)</span></tt> clause always contains a <tt class="docutils literal"><span class="pre">(required</span> <span class="pre">…)</span></tt> |
| and/or an <tt class="docutils literal"><span class="pre">(optional</span> <span class="pre">…)</span></tt> subclause, and must follow any |
| <tt class="docutils literal"><span class="pre">(required</span> <span class="pre">…)</span></tt> or <tt class="docutils literal"><span class="pre">(optional</span> <span class="pre">…)</span></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"><span class="pre">policies</span></tt> argument that was also, |
| for some reason, convertible to <tt class="docutils literal"><span class="pre">char</span> <span class="pre">const*</span></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"><span class="pre">BOOST_PARAMETER_MEMBER_FUNCTION</span></tt> and |
| <tt class="docutils literal"><span class="pre">BOOST_PARAMETER_CONST_MEMBER_FUNCTION</span></tt> macros accept exactly the |
| same arguments as <tt class="docutils literal"><span class="pre">BOOST_PARAMETER_FUNCTION</span></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), operator(), tag, (required (arg1,(int))(arg2,(int)))) |
| { |
| std::cout << arg1 << ", " << arg2 << std::endl; |
| } |
| }; |
| </pre> |
| <!-- @example.prepend(''' |
| #include <boost/parameter.hpp> |
| #include <iostream>''') --> |
| <!-- @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), operator(), 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)''') --> |
| <!-- @test('compile') --> |
| </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"><span class="pre">|</span></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"><span class="pre">index</span></tt> parameter in |
| the <span class="concept">ArgumentPack</span>, <tt class="docutils literal"><span class="pre">42</span></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"><span class="pre">index</span></tt> but not for |
| <tt class="docutils literal"><span class="pre">name</span></tt>, only <tt class="docutils literal"><span class="pre">name</span></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"><span class="pre">ValueType</span></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"><span class="pre">class_type</span></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"><span class="pre">class_type</span></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, is_class<_> > |
| , optional<tag::base_list, mpl::is_sequence<_> > |
| , optional<tag::held_type> |
| , optional<tag::copyable> |
| > class_signature; |
| |
| }} |
| </pre> |
| <!-- @example.prepend(''' |
| #include <boost/parameter.hpp> |
| #include <boost/mpl/is_sequence.hpp> |
| #include <boost/noncopyable.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"><span class="pre">class_</span></tt> , we use the <span class="concept">ParameterSpec</span>'s nested <tt class="docutils literal"><span class="pre">::bind<</span> <span class="pre">…</span> <span class="pre">></span></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"><span class="pre">binding<</span> |
| <span class="pre">…</span> <span class="pre">></span></tt> metafunction to extract “logical parameters”. Note that |
| defaults are specified by supplying an optional third argument to |
| <tt class="docutils literal"><span class="pre">binding<</span> <span class="pre">…</span> <span class="pre">></span></tt>:</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::binding< |
| args, tag::class_type>::type class_type; |
| |
| typedef typename parameter::binding< |
| args, tag::base_list, bases<> >::type base_list; |
| |
| typedef typename parameter::binding< |
| args, tag::held_type, class_type>::type held_type; |
| |
| typedef typename parameter::binding< |
| 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"><span class="pre">held_type</span></tt> and |
| <tt class="docutils literal"><span class="pre">copyable</span></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"><span class="pre">base_list</span></tt> be |
| a specialization of its <tt class="docutils literal"><span class="pre">bases<</span> <span class="pre">…</span> <span class="pre">></span></tt> template (as opposed to |
| being any old MPL sequence) and by requiring that <tt class="docutils literal"><span class="pre">copyable</span></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"><span class="pre">bases<</span> <span class="pre">…</span> <span class="pre">></span></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<_> > |
| |
| , optional< |
| deduced<tag::base_list> |
| , is_base_and_derived<detail::bases_base,_> |
| > |
| |
| , optional< |
| deduced<tag::held_type> |
| , mpl::not_< |
| mpl::or_< |
| is_base_and_derived<detail::bases_base,_> |
| , is_same<noncopyable,_> |
| > |
| > |
| > |
| |
| , optional<deduced<tag::copyable>, is_same<noncopyable,_> > |
| |
| > class_signature; |
| </pre> |
| <!-- @example.prepend(''' |
| 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::binding< |
| args, tag::class_type>::type class_type; |
| |
| typedef typename parameter::binding< |
| args, tag::base_list, bases<> >::type base_list; |
| |
| typedef typename parameter::binding< |
| args, tag::held_type, class_type>::type held_type; |
| |
| typedef typename parameter::binding< |
| 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"><span class="pre">tag</span></tt> for |
| something other than the keyword type namespace, there's another |
| way to use <tt class="docutils literal"><span class="pre">BOOST_PARAMETER_NAME</span></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"><span class="pre">print_name_and_index</span></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"><span class="pre">::bind<</span> <span class="pre">…</span> |
| <span class="pre">></span></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://std.dkuug.dk/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"><span class="pre">print_name_and_index</span></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"><span class="pre">index</span></tt> parameter? In that |
| case we can use the <tt class="docutils literal"><span class="pre">binding<</span> <span class="pre">…</span> <span class="pre">></span></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 remove_reference< |
| typename parameter::binding<ArgumentPack, tag::index, int>::type |
| >::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; |
| using boost::remove_reference;''') --> |
| <p>Note that the <tt class="docutils literal"><span class="pre">remove_reference<</span> <span class="pre">…</span> <span class="pre">></span></tt> dance is necessary because |
| <tt class="docutils literal"><span class="pre">binding<</span> <span class="pre">…</span> <span class="pre">></span></tt> will return a reference type when the argument |
| is bound in the argument pack. If we don't strip the reference we |
| end up returning a reference to the temporary created in the <tt class="docutils literal"><span class="pre">2</span> <span class="pre">*</span> <span class="pre">…</span></tt> |
| expression. A convenient shortcut would be to use the <tt class="docutils literal"><span class="pre">value_type<</span> <span class="pre">…</span> <span class="pre">></span></tt> |
| metafunction:</p> |
| <pre class="literal-block"> |
| template <class ArgumentPack> |
| typename <strong>parameter::value_type<ArgumentPack, tag::index, int></strong>::type |
| twice_index(ArgumentPack const& args) |
| { |
| return 2 * args[_index|42]; |
| } |
| </pre> |
| <!-- @example.wrap('namespace with_value_type {', ''' |
| int six = twice_index(_index = 3); |
| }''') --> |
| <!-- TODO: binding<> returns a reference. We should use value_type<> here. --> |
| <!-- @example.append(''' |
| int main() |
| { |
| assert(six == 6); |
| assert(with_value_type::six == 6); |
| }''') --> |
| <!-- @test('run', howmany='all') --> |
| </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"><span class="pre">BOOST_PARAMETER_FUNCTION</span></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"><span class="pre">operator|</span></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"><span class="pre">"hello,</span> <span class="pre">world"</span></tt> is constructed |
| despite the fact that the user passed us a value for <tt class="docutils literal"><span class="pre">s3</span></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"> |
| using boost::bind; |
| using boost::ref; |
| |
| typename parameter::binding< |
| ArgumentPack, tag::s3, std::string |
| >::type s3 = args[_s3 <strong>|| bind(std::plus<std::string>(), ref(s1), 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"><span class="pre">|</span></tt> and <tt class="docutils literal"><span class="pre">||</span></tt>, recall that |
| <tt class="docutils literal"><span class="pre">||</span></tt> normally uses short-circuit evaluation: its second |
| argument is only evaluated if its first argument is <tt class="docutils literal"><span class="pre">false</span></tt>. |
| Similarly, in <tt class="docutils literal"><span class="pre">color_map[param||f]</span></tt>, <tt class="docutils literal"><span class="pre">f</span></tt> is only invoked if |
| no <tt class="docutils literal"><span class="pre">color_map</span></tt> argument was supplied.</p> |
| </div> |
| <p>The expression <tt class="docutils literal"><span class="pre">bind(std::plus<std::string>(),</span> <span class="pre">ref(s1),</span> <span class="pre">ref(s2))</span></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"><span class="pre">s3</span></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"><span class="pre">BOOST_PARAMETER_NAME</span></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"><span class="pre">3</span></tt> as the <tt class="docutils literal"><span class="pre">age</span></tt> parameter to <tt class="docutils literal"><span class="pre">g</span></tt>, what happened instead |
| was that <tt class="docutils literal"><span class="pre">f</span></tt>'s <tt class="docutils literal"><span class="pre">age</span></tt> argument got reassigned the value 3, |
| and was then passed as a positional argument to <tt class="docutils literal"><span class="pre">g</span></tt>. Since |
| <tt class="docutils literal"><span class="pre">g</span></tt>'s first positional parameter is <tt class="docutils literal"><span class="pre">name</span></tt>, the default value |
| for <tt class="docutils literal"><span class="pre">age</span></tt> is used, and g prints <tt class="docutils literal"><span class="pre">3:42</span></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"><span class="pre">age</span></tt> parameter had been made <tt class="docutils literal"><span class="pre">const</span></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"><span class="pre">people</span></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"><span class="pre">lib</span></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"><span class="pre">lib</span></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"><span class="pre">#define</span></tt> the preprocessor |
| symbol <tt class="docutils literal"><span class="pre">BOOST_NO_SFINAE</span></tt>, and parameter-enabled functions won't be |
| removed from the overload set based on their signatures.</p> |
| </div> |
| <div class="section" 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"><span class="pre">result_of</span></tt></a></h2> |
| <p><a class="reference internal" href="#lazy-default-computation">Lazy default computation</a> relies on the <tt class="docutils literal"><span class="pre">result_of</span></tt> class |
| template to compute the types of default arguments given the type |
| of the function object that constructs them. On compilers that |
| don't support <tt class="docutils literal"><span class="pre">result_of</span></tt>, <tt class="docutils literal"><span class="pre">BOOST_NO_RESULT_OF</span></tt> will be |
| <tt class="docutils literal"><span class="pre">#define</span></tt>d, and the compiler will expect the function object to |
| contain a nested type name, <tt class="docutils literal"><span class="pre">result_type</span></tt>, that indicates its |
| return type when invoked without arguments. To use an ordinary |
| function as a default generator on those compilers, you'll need to |
| wrap it in a class that provides <tt class="docutils literal"><span class="pre">result_type</span></tt> as a <tt class="docutils literal"><span class="pre">typedef</span></tt> |
| and invokes the function via its <tt class="docutils literal"><span class="pre">operator()</span></tt>.</p> |
| <!-- Can't Declare |ParameterSpec| via ``typedef`` |
| ============================================= |
| |
| In principle you can declare a |ParameterSpec| as a ``typedef`` |
| for a specialization of ``parameters<…>``, but Microsoft Visual C++ |
| 6.x has been seen to choke on that usage. The workaround is to use |
| inheritance and declare your |ParameterSpec| as a class: |
| |
| .. parsed-literal:: |
| |
| **struct dfs_parameters |
| :** parameter::parameters< |
| tag::graph, tag::visitor, tag::root_vertex |
| , tag::index_map, tag::color_map |
| > **{};** |
| |
| |
| Default Arguments Unsupported on Nested Templates |
| ================================================= |
| |
| As of this writing, Borland compilers don't support the use of |
| default template arguments on member class templates. As a result, |
| you have to supply ``BOOST_PARAMETER_MAX_ARITY`` arguments to every |
| use of ``parameters<…>::match``. Since the actual defaults used |
| are unspecified, the workaround is to use |
| |BOOST_PARAMETER_MATCH|_ to declare default arguments for SFINAE. |
| |
| .. |BOOST_PARAMETER_MATCH| replace:: ``BOOST_PARAMETER_MATCH`` --> |
| </div> |
| <div class="section" 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"><span class="pre">f</span></tt>'s <em>parameter</em> <tt class="docutils literal"><span class="pre">x</span></tt> is given by the <em>argument</em> |
| <tt class="docutils literal"><span class="pre">3</span></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"><span class="pre">int</span></tt> in the text, and your understanding of the Parameter |
| library wouldn't suffer.</td></tr> |
| </tbody> |
| </table> |
| <table class="docutils footnote" frame="void" id="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"><span class="pre">is_keyword_expression</span></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"><span class="pre">enable_if</span></tt></a> utility. Most recent compilers support SFINAE; |
| on compilers that don't support it, the Boost config library |
| will <tt class="docutils literal"><span class="pre">#define</span></tt> the symbol <tt class="docutils literal"><span class="pre">BOOST_NO_SFINAE</span></tt>. |
| See |
| <a class="reference 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: 2009-05-31 01: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> |