libs/parameter/doc/html/index.html

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
   7 <title>The Boost Parameter Library</title>
   8 <link rel="stylesheet" href="rst.css" type="text/css" />
   9 </head>
  10 <body>
  11 <div class="document" id="the-boost-parameter-library">
  12 <h1 class="title">The Boost Parameter Library</h1>
  13
  14 <p><a class="reference external" href="../../../../index.htm"><img alt="Boost" src="../../../../boost.png" /></a></p>
  15 <hr class="docutils" />
  16 <table class="docutils field-list" frame="void" rules="none">
  17 <col class="field-name" />
  18 <col class="field-body" />
  19 <tbody valign="top">
  20 <tr class="field"><th class="field-name">Abstract:</th><td class="field-body">Use this library to write functions and class templates that can
  21 accept arguments by name:</td>
  22 </tr>
  23 </tbody>
  24 </table>
  25 <pre class="literal-block">
  26 new_window(
  27     &quot;alert&quot;
  28   , <strong>_width=10</strong>
  29   , <strong>_titlebar=false</strong>
  30 );
  31
  32 smart_ptr&lt;
  33     Foo
  34   , <strong>deleter&lt;Deallocate&lt;Foo&gt; &gt;</strong>
  35   , <strong>copy_policy&lt;DeepCopy&gt;</strong>
  36 &gt; p(new Foo);
  37 </pre>
  38 <p>Since named arguments can be passed in any order, they are especially useful
  39 when a function or template has more than one parameter with a useful default
  40 value.  The library also supports <em>deduced</em> parameters: that is to say,
  41 parameters whose identity can be deduced from their types.</p>
  42 <!-- @jam_prefix.append('''
  43 project test
  44     : requirements <include>. <implicit-dependency>/boost//headers ;
  45 ''') -->
  46 <!-- @example.prepend('''
  47 #include <boost/parameter.hpp>
  48
  49 namespace test {
  50
  51     BOOST_PARAMETER_NAME(title)
  52     BOOST_PARAMETER_NAME(width)
  53     BOOST_PARAMETER_NAME(titlebar)
  54
  55     BOOST_PARAMETER_FUNCTION(
  56         (int), new_window, tag, (required (title,*)(width,*)(titlebar,*))
  57     )
  58     {
  59         return 0;
  60     }
  61
  62     BOOST_PARAMETER_TEMPLATE_KEYWORD(deleter)
  63     BOOST_PARAMETER_TEMPLATE_KEYWORD(copy_policy)
  64
  65     template <typename T>
  66     struct Deallocate
  67     {
  68     };
  69
  70     struct DeepCopy
  71     {
  72     };
  73
  74     namespace parameter = boost::parameter;
  75
  76     struct Foo
  77     {
  78     };
  79
  80     template <typename T, typename A0, typename A1>
  81     struct smart_ptr
  82     {
  83         smart_ptr(Foo*);
  84     };
  85 }
  86 using namespace test;
  87 int x =
  88 '''); -->
  89 <!-- @test('compile') -->
  90 <hr class="docutils" />
  91 <table class="docutils field-list" frame="void" rules="none">
  92 <col class="field-name" />
  93 <col class="field-body" />
  94 <tbody valign="top">
  95 <tr class="field"><th class="field-name">Authors:</th><td class="field-body">David Abrahams, Daniel Wallin</td>
  96 </tr>
  97 <tr class="field"><th class="field-name">Contact:</th><td class="field-body"><a class="reference external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference external" href="mailto:daniel&#64;boostpro.com">daniel&#64;boostpro.com</a></td>
  98 </tr>
  99 <tr class="field"><th class="field-name">organization:</th><td class="field-body"><a class="reference external" href="http://www.boostpro.com">BoostPro Computing</a></td>
 100 </tr>
 101 <tr class="field"><th class="field-name">date:</th><td class="field-body">$Date: 2005/07/17 19:53:01 $</td>
 102 </tr>
 103 <tr class="field"><th class="field-name">copyright:</th><td class="field-body">Copyright David Abrahams, Daniel Wallin
 104 2005-2009. Distributed under the Boost Software License,
 105 Version 1.0. (See accompanying file LICENSE_1_0.txt
 106 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>
 107 </tr>
 108 </tbody>
 109 </table>
 110 <hr class="docutils" />
 111 <p>[Note: this tutorial does not cover all details of the library.  Please see
 112 also the <a class="reference external" href="reference.html">reference documentation</a>]</p>
 113 <div class="contents topic" id="table-of-contents">
 114 <p class="topic-title first"><strong>Table of Contents</strong></p>
 115 <ul class="auto-toc simple">
 116 <li><a class="reference internal" href="#motivation" id="id22">1&nbsp;&nbsp;&nbsp;Motivation</a><ul class="auto-toc">
 117 <li><a class="reference internal" href="#named-function-parameters" id="id23">1.1&nbsp;&nbsp;&nbsp;Named Function Parameters</a></li>
 118 <li><a class="reference internal" href="#deduced-function-parameters" id="id24">1.2&nbsp;&nbsp;&nbsp;Deduced Function Parameters</a></li>
 119 <li><a class="reference internal" href="#class-template-parameter-support" id="id25">1.3&nbsp;&nbsp;&nbsp;Class Template Parameter Support</a></li>
 120 </ul>
 121 </li>
 122 <li><a class="reference internal" href="#tutorial" id="id26">2&nbsp;&nbsp;&nbsp;Tutorial</a><ul class="auto-toc">
 123 <li><a class="reference internal" href="#parameter-enabled-functions" id="id27">2.1&nbsp;&nbsp;&nbsp;Parameter-Enabled Functions</a></li>
 124 <li><a class="reference internal" href="#parameter-enabled-member-functions" id="id28">2.2&nbsp;&nbsp;&nbsp;Parameter-Enabled Member Functions</a></li>
 125 <li><a class="reference internal" href="#parameter-enabled-function-call-operators" id="id29">2.3&nbsp;&nbsp;&nbsp;Parameter-Enabled Function Call Operators</a></li>
 126 <li><a class="reference internal" href="#parameter-enabled-constructors" id="id30">2.4&nbsp;&nbsp;&nbsp;Parameter-Enabled Constructors</a></li>
 127 <li><a class="reference internal" href="#parameter-enabled-class-templates" id="id31">2.5&nbsp;&nbsp;&nbsp;Parameter-Enabled Class Templates</a></li>
 128 </ul>
 129 </li>
 130 <li><a class="reference internal" href="#advanced-topics" id="id32">3&nbsp;&nbsp;&nbsp;Advanced Topics</a><ul class="auto-toc">
 131 <li><a class="reference internal" href="#fine-grained-name-control" id="id33">3.1&nbsp;&nbsp;&nbsp;Fine-Grained Name Control</a></li>
 132 <li><a class="reference internal" href="#more-argumentpacks" id="id34">3.2&nbsp;&nbsp;&nbsp;More <span class="concept">ArgumentPack</span>s</a></li>
 133 </ul>
 134 </li>
 135 <li><a class="reference internal" href="#best-practices" id="id35">4&nbsp;&nbsp;&nbsp;Best Practices</a><ul class="auto-toc">
 136 <li><a class="reference internal" href="#keyword-naming" id="id36">4.1&nbsp;&nbsp;&nbsp;Keyword Naming</a></li>
 137 <li><a class="reference internal" href="#namespaces" id="id37">4.2&nbsp;&nbsp;&nbsp;Namespaces</a></li>
 138 <li><a class="reference internal" href="#documentation" id="id38">4.3&nbsp;&nbsp;&nbsp;Documentation</a></li>
 139 </ul>
 140 </li>
 141 <li><a class="reference internal" href="#portability-considerations" id="id39">5&nbsp;&nbsp;&nbsp;Portability Considerations</a><ul class="auto-toc">
 142 <li><a class="reference internal" href="#perfect-forwarding-support" id="id40">5.1&nbsp;&nbsp;&nbsp;Perfect Forwarding Support</a></li>
 143 <li><a class="reference internal" href="#boost-mp11-support" id="id41">5.2&nbsp;&nbsp;&nbsp;Boost.MP11 Support</a></li>
 144 <li><a class="reference internal" href="#no-sfinae-support" id="id42">5.3&nbsp;&nbsp;&nbsp;No SFINAE Support</a></li>
 145 <li><a class="reference internal" href="#no-support-for-result-of" id="id43">5.4&nbsp;&nbsp;&nbsp;No Support for <tt class="docutils literal">result_of</tt></a></li>
 146 <li><a class="reference internal" href="#compiler-can-t-see-references-in-unnamed-namespace" id="id44">5.5&nbsp;&nbsp;&nbsp;Compiler Can't See References In Unnamed Namespace</a></li>
 147 </ul>
 148 </li>
 149 <li><a class="reference internal" href="#python-binding" id="id45">6&nbsp;&nbsp;&nbsp;Python Binding</a></li>
 150 <li><a class="reference internal" href="#reference" id="id46">7&nbsp;&nbsp;&nbsp;Reference</a></li>
 151 <li><a class="reference internal" href="#glossary" id="id47">8&nbsp;&nbsp;&nbsp;Glossary</a><ul class="auto-toc">
 152 <li><a class="reference internal" href="#argument-or-actual-argument" id="id48">8.1&nbsp;&nbsp;&nbsp;Argument (or “actual argument”)</a></li>
 153 <li><a class="reference internal" href="#parameter-or-formal-parameter" id="id49">8.2&nbsp;&nbsp;&nbsp;Parameter (or “formal parameter”)</a></li>
 154 </ul>
 155 </li>
 156 <li><a class="reference internal" href="#acknowledgements" id="id50">9&nbsp;&nbsp;&nbsp;Acknowledgements</a></li>
 157 </ul>
 158 </div>
 159 <hr class="docutils" />
 160 <div class="section" id="motivation">
 161 <h1><a class="toc-backref" href="#id22">1&nbsp;&nbsp;&nbsp;Motivation</a></h1>
 162 <p>In C++, <a class="reference internal" href="#arguments">arguments</a> are normally given meaning by their positions with respect
 163 to a <a class="reference internal" href="#parameter">parameter</a> list: the first argument passed maps onto the first parameter
 164 in a function's definition, and so on.  That protocol is fine when there is at
 165 most one parameter with a default value, but when there are even a few useful
 166 defaults, the positional interface becomes burdensome:</p>
 167 <ul>
 168 <li><div class="first compound">
 169 <p class="compound-first">Since an argument's meaning is given by its position, we have to choose an
 170 (often arbitrary) order for parameters with default values, making some
 171 combinations of defaults unusable:</p>
 172 <pre class="compound-middle literal-block">
 173 window* new_window(
 174     char const* name
 175   , <strong>int border_width = default_border_width</strong>
 176   , bool movable = true
 177   , bool initially_visible = true
 178 );
 179
 180 bool const movability = false;
 181 window* w = new_window(&quot;alert box&quot;, movability);
 182 </pre>
 183 <p class="compound-middle">In the example above we wanted to make an unmoveable window with a default
 184 <tt class="docutils literal">border_width</tt>, but instead we got a moveable window with a
 185 <tt class="docutils literal">border_width</tt> of zero.  To get the desired effect, we'd need to write:</p>
 186 <pre class="compound-last literal-block">
 187 window* w = new_window(
 188     &quot;alert box&quot;, <strong>default_border_width</strong>, movability
 189 );
 190 </pre>
 191 </div>
 192 </li>
 193 <li><div class="first compound">
 194 <p class="compound-first">It can become difficult for readers to understand the meaning of arguments
 195 at the call site:</p>
 196 <pre class="compound-middle literal-block">
 197 window* w = new_window(&quot;alert&quot;, 1, true, false);
 198 </pre>
 199 <p class="compound-last">Is this window moveable and initially invisible, or unmoveable and
 200 initially visible?  The reader needs to remember the order of arguments to
 201 be sure.</p>
 202 </div>
 203 </li>
 204 <li><p class="first">The author of the call may not remember the order of the arguments either,
 205 leading to hard-to-find bugs.</p>
 206 </li>
 207 </ul>
 208 <!-- @ignore(3) -->
 209 <div class="section" id="named-function-parameters">
 210 <h2><a class="toc-backref" href="#id23">1.1&nbsp;&nbsp;&nbsp;Named Function Parameters</a></h2>
 211 <div class="compound">
 212 <p class="compound-first">This library addresses the problems outlined above by associating each
 213 parameter name with a keyword object.  Now users can identify arguments by
 214 name, rather than by position:</p>
 215 <pre class="compound-last literal-block">
 216 window* w = new_window(
 217     &quot;alert box&quot;
 218   , <strong>movable_=</strong>false
 219 ); // OK!
 220 </pre>
 221 </div>
 222 <!-- @ignore() -->
 223 </div>
 224 <div class="section" id="deduced-function-parameters">
 225 <h2><a class="toc-backref" href="#id24">1.2&nbsp;&nbsp;&nbsp;Deduced Function Parameters</a></h2>
 226 <div class="compound">
 227 <p class="compound-first">A <strong>deduced parameter</strong> can be passed in any position <em>without</em> supplying
 228 an explicit parameter name.  It's not uncommon for a function to have
 229 parameters that can be uniquely identified based on the types of arguments
 230 passed.  The <tt class="docutils literal">name</tt> parameter to <tt class="docutils literal">new_window</tt> is one such
 231 example.  None of the other arguments, if valid, can reasonably be
 232 converted to a <tt class="docutils literal">char const*</tt>.  With a deduced parameter interface, we
 233 could pass the window name in <em>any</em> argument position without causing
 234 ambiguity:</p>
 235 <pre class="compound-middle literal-block">
 236 window* w = new_window(
 237     movable_=false
 238   , <strong>&quot;alert box&quot;</strong>
 239 ); // OK!
 240 window* w = new_window(
 241     <strong>&quot;alert box&quot;</strong>
 242   , movable_=false
 243 ); // OK!
 244 </pre>
 245 <p class="compound-last">Appropriately used, a deduced parameter interface can free the user of the
 246 burden of even remembering the formal parameter names.</p>
 247 </div>
 248 <!-- @ignore() -->
 249 </div>
 250 <div class="section" id="class-template-parameter-support">
 251 <h2><a class="toc-backref" href="#id25">1.3&nbsp;&nbsp;&nbsp;Class Template Parameter Support</a></h2>
 252 <div class="compound">
 253 <p class="compound-first">The reasoning we've given for named and deduced parameter interfaces
 254 applies equally well to class templates as it does to functions.  Using
 255 the Parameter library, we can create interfaces that allow template
 256 arguments (in this case <tt class="docutils literal">shared</tt> and <tt class="docutils literal">Client</tt>) to be explicitly named,
 257 like this:</p>
 258 <pre class="compound-middle literal-block">
 259 smart_ptr&lt;
 260     <strong>ownership&lt;shared&gt;</strong>
 261   , <strong>value_type&lt;Client&gt;</strong>
 262 &gt; p;
 263 </pre>
 264 <p class="compound-middle">The syntax for passing named template arguments is not quite as natural as
 265 it is for function arguments (ideally, we'd be able to write
 266 <tt class="docutils literal">smart_ptr&lt;ownership = shared, …&gt;</tt>).  This small syntactic deficiency
 267 makes deduced parameters an especially big win when used with class
 268 templates:</p>
 269 <pre class="compound-last literal-block">
 270 // <em>p and q could be equivalent, given a deduced</em>
 271 // <em>parameter interface.</em>
 272 smart_ptr&lt;<strong>shared</strong>, <strong>Client</strong>&gt; p;
 273 smart_ptr&lt;<strong>Client</strong>, <strong>shared</strong>&gt; q;
 274 </pre>
 275 </div>
 276 <!-- @ignore(2) -->
 277 </div>
 278 </div>
 279 <div class="section" id="tutorial">
 280 <h1><a class="toc-backref" href="#id26">2&nbsp;&nbsp;&nbsp;Tutorial</a></h1>
 281 <p>This tutorial shows all the basics—how to build both named- and
 282 deduced-parameter interfaces to function templates and class
 283 templates—and several more advanced idioms as well.</p>
 284 <div class="section" id="parameter-enabled-functions">
 285 <h2><a class="toc-backref" href="#id27">2.1&nbsp;&nbsp;&nbsp;Parameter-Enabled Functions</a></h2>
 286 <p>In this section we'll show how the Parameter library can be used to
 287 build an expressive interface to the <a class="reference external" href="../../../graph/doc/index.html">Boost Graph library</a>'s
 288 <a class="reference external" href="../../../graph/doc/depth_first_search.html"><tt class="docutils literal">depth_first_search</tt></a> algorithm.<a class="footnote-reference" href="#old-interface" id="id3"><sup>1</sup></a></p>
 289 <!-- Revisit this
 290
 291 After laying some groundwork and describing the algorithm's abstract
 292 interface, we'll show you how to build a basic implementation with keyword
 293 support.  Then we'll add support for default arguments and we'll gradually
 294 refine the implementation with syntax improvements.  Finally we'll show
 295 how to streamline the implementation of named parameter interfaces,
 296 improve their participation in overload resolution, and optimize their
 297 runtime efficiency. -->
 298 <div class="section" id="headers-and-namespaces">
 299 <h3>2.1.1&nbsp;&nbsp;&nbsp;Headers And Namespaces</h3>
 300 <p>Most components of the Parameter library are declared in a header named for
 301 the component.  For example,</p>
 302 <pre class="literal-block">
 303 #include &lt;boost/parameter/keyword.hpp&gt;
 304 </pre>
 305 <p>will ensure <tt class="docutils literal"><span class="pre">boost::parameter::keyword</span></tt> is known to the compiler.  There
 306 is also a combined header, <tt class="docutils literal">boost/parameter.hpp</tt>, that includes most of
 307 the library's components.  For the the rest of this tutorial, unless we
 308 say otherwise, you can use the rule above to figure out which header to
 309 <tt class="docutils literal">#include</tt> to access any given component of the library.</p>
 310 <!-- @example.append('''
 311 using boost::parameter::keyword;
 312 ''') -->
 313 <!-- @test('compile') -->
 314 <p>Also, the examples below will also be written as if the namespace alias</p>
 315 <pre class="literal-block">
 316 namespace parameter = boost::parameter;
 317 </pre>
 318 <!-- @ignore() -->
 319 <p>has been declared: we'll write <tt class="docutils literal"><span class="pre">parameter::xxx</span></tt> instead of
 320 <tt class="docutils literal"><span class="pre">boost::parameter::xxx</span></tt>.</p>
 321 </div>
 322 <div class="section" id="the-abstract-interface-to-dfs">
 323 <h3>2.1.2&nbsp;&nbsp;&nbsp;The Abstract Interface to <tt class="docutils literal">depth_first_search</tt></h3>
 324 <p>The Graph library's <tt class="docutils literal">depth_first_search</tt> algorithm is a generic function accepting
 325 from one to four arguments by reference.  If all arguments were
 326 required, its signature might be as follows:</p>
 327 <pre class="literal-block">
 328 template &lt;
 329     typename Graph
 330   , typename DFSVisitor
 331   , typename Index
 332   , typename ColorMap
 333 &gt;
 334 void
 335     depth_first_search(
 336         Graph const&amp; graph
 337       , DFSVisitor visitor
 338       , typename graph_traits&lt;g&gt;::vertex_descriptor root_vertex
 339       , IndexMap index_map
 340       , ColorMap&amp; color
 341     );
 342 </pre>
 343 <!-- @ignore() -->
 344 <p>However, most of the parameters have a useful default value,
 345 as shown in the table below.</p>
 346 <table border="1" class="docutils" id="default-expressions">
 347 <span id="parameter-table"></span><caption><tt class="docutils literal">depth_first_search</tt> Parameters</caption>
 348 <colgroup>
 349 <col width="20%" />
 350 <col width="7%" />
 351 <col width="30%" />
 352 <col width="43%" />
 353 </colgroup>
 354 <thead valign="bottom">
 355 <tr><th class="head">Parameter
 356 Name</th>
 357 <th class="head">Data
 358 Flow</th>
 359 <th class="head">Type</th>
 360 <th class="head">Default Value
 361 (if any)</th>
 362 </tr>
 363 </thead>
 364 <tbody valign="top">
 365 <tr><td><tt class="docutils literal">graph</tt></td>
 366 <td>in</td>
 367 <td>Model of
 368 <a class="reference external" href="../../../graph/doc/IncidenceGraph.html"><span class="concept">Incidence Graph</span></a> and
 369 <a class="reference external" href="../../../graph/doc/VertexListGraph.html"><span class="concept">Vertex List Graph</span></a></td>
 370 <td>none - this argument is required.</td>
 371 </tr>
 372 <tr><td><tt class="docutils literal">visitor</tt></td>
 373 <td>in</td>
 374 <td>Model of <a class="reference external" href="../../../graph/doc/DFSVisitor.html"><span class="concept">DFS Visitor</span></a></td>
 375 <td><tt class="docutils literal"><span class="pre">boost::dfs_visitor&lt;&gt;()</span></tt></td>
 376 </tr>
 377 <tr><td><tt class="docutils literal">root_vertex</tt></td>
 378 <td>in</td>
 379 <td><tt class="docutils literal">graph</tt>'s vertex
 380 descriptor type.</td>
 381 <td><tt class="docutils literal"><span class="pre">*vertices(graph).first</span></tt></td>
 382 </tr>
 383 <tr><td><tt class="docutils literal">index_map</tt></td>
 384 <td>in</td>
 385 <td>Model of
 386 <a class="reference external" href="../../../property_map/doc/ReadablePropertyMap.html"><span class="concept">Readable Property Map</span></a>
 387 with key type :=
 388 <tt class="docutils literal">graph</tt>'s vertex
 389 descriptor and value
 390 type an integer type.</td>
 391 <td><tt class="docutils literal"><span class="pre">get(boost::vertex_index,graph)</span></tt></td>
 392 </tr>
 393 <tr><td><tt class="docutils literal">color_map</tt></td>
 394 <td>in /
 395 out</td>
 396 <td>Model of
 397 <a class="reference external" href="../../../property_map/doc/ReadWritePropertyMap.html"><span class="concept">Read/Write Property Map</span></a>
 398 with key type :=
 399 <tt class="docutils literal">graph</tt>'s vertex
 400 descriptor type.</td>
 401 <td>a <tt class="docutils literal"><span class="pre">boost::iterator_property_map</span></tt>
 402 created from a <tt class="docutils literal"><span class="pre">std::vector</span></tt> of
 403 <tt class="docutils literal">default_color_type</tt> of size
 404 <tt class="docutils literal">num_vertices(graph)</tt> and using
 405 <tt class="docutils literal">index_map</tt> for the index map.</td>
 406 </tr>
 407 </tbody>
 408 </table>
 409 <p>Don't be intimidated by the information in the second and third columns
 410 above.  For the purposes of this exercise, you don't need to understand
 411 them in detail.</p>
 412 </div>
 413 <div class="section" id="defining-the-keywords">
 414 <h3>2.1.3&nbsp;&nbsp;&nbsp;Defining the Keywords</h3>
 415 <p>The point of this exercise is to make it possible to call
 416 <tt class="docutils literal">depth_first_search</tt> with named arguments, leaving out any
 417 arguments for which the default is appropriate:</p>
 418 <pre class="literal-block">
 419 graphs::depth_first_search(g, <strong>color_map_=my_color_map</strong>);
 420 </pre>
 421 <!-- @ignore() -->
 422 <p>To make that syntax legal, there needs to be an object called
 423 “<tt class="docutils literal">color_map_</tt>” whose assignment operator can accept a
 424 <tt class="docutils literal">my_color_map</tt> argument.  In this step we'll create one such
 425 <strong>keyword object</strong> for each parameter.  Each keyword object will be
 426 identified by a unique <strong>keyword tag type</strong>.</p>
 427 <!-- Revisit this
 428
 429 We're going to define our interface in namespace ``graphs``.  Since users
 430 need access to the keyword objects, but not the tag types, we'll define
 431 the keyword objects so they're accessible through ``graphs``, and we'll
 432 hide the tag types away in a nested namespace, ``graphs::tag``.  The
 433 library provides a convenient macro for that purpose. -->
 434 <p>We're going to define our interface in namespace <tt class="docutils literal">graphs</tt>.  The
 435 library provides a convenient macro for defining keyword objects:</p>
 436 <pre class="literal-block">
 437 #include &lt;boost/parameter/name.hpp&gt;
 438
 439 namespace graphs {
 440
 441     BOOST_PARAMETER_NAME(graph)    // Note: no semicolon
 442     BOOST_PARAMETER_NAME(visitor)
 443     BOOST_PARAMETER_NAME(root_vertex)
 444     BOOST_PARAMETER_NAME(index_map)
 445     BOOST_PARAMETER_NAME(color_map)
 446 }
 447 </pre>
 448 <!-- @test('compile') -->
 449 <p>The declaration of the <tt class="docutils literal">graph</tt> keyword you see here is equivalent to:</p>
 450 <pre class="literal-block">
 451 namespace graphs {
 452     namespace tag {
 453
 454         // keyword tag type
 455         struct graph
 456         {
 457             typedef boost::parameter::forward_reference qualifier;
 458         };
 459     }
 460
 461     namespace // unnamed
 462     {
 463         // A reference to the keyword object
 464         boost::parameter::keyword&lt;tag::graph&gt; const&amp; _graph
 465             = boost::parameter::keyword&lt;tag::graph&gt;::instance;
 466     }
 467 }
 468 </pre>
 469 <!-- @example.prepend('#include <boost/parameter/keyword.hpp>') -->
 470 <!-- @test('compile') -->
 471 <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>
 472 reference named <tt class="docutils literal">_graph</tt>.</p>
 473 <p>This “fancy dance” involving an unnamed namespace and references is all done
 474 to avoid violating the One Definition Rule (ODR)<a class="footnote-reference" href="#odr" id="id5"><sup>2</sup></a> when the named
 475 parameter interface is used by function templates that are instantiated in
 476 multiple translation units (MSVC6.x users see <a class="reference internal" href="#compiler-can-t-see-references-in-unnamed-namespace">this note</a>).</p>
 477 </div>
 478 <div class="section" id="writing-the-function">
 479 <h3>2.1.4&nbsp;&nbsp;&nbsp;Writing the Function</h3>
 480 <p>Now that we have our keywords defined, the function template definition
 481 follows a simple pattern using the <tt class="docutils literal">BOOST_PARAMETER_FUNCTION</tt> macro:</p>
 482 <pre class="literal-block">
 483 #include &lt;boost/parameter/preprocessor.hpp&gt;
 484
 485 namespace graphs {
 486
 487     BOOST_PARAMETER_FUNCTION(
 488         (void),                 // 1. parenthesized return type
 489         depth_first_search,     // 2. name of the function template
 490         tag,                    // 3. namespace of tag types
 491         (required (graph, *) )  // 4. one required parameter, and
 492         (optional               //    four optional parameters,
 493                                 //    with defaults
 494             (visitor,     *, boost::dfs_visitor&lt;&gt;())
 495             (root_vertex, *, *vertices(graph).first)
 496             (index_map,   *, get(boost::vertex_index,graph))
 497             (color_map,   *,
 498                 default_color_map(num_vertices(graph), index_map)
 499             )
 500         )
 501     )
 502     {
 503         // ... body of function goes here...
 504         // use graph, visitor, index_map, and color_map
 505     }
 506 }
 507 </pre>
 508 <!-- @example.prepend('''
 509 #include <boost/parameter/name.hpp>
 510
 511 BOOST_PARAMETER_NAME(graph)
 512 BOOST_PARAMETER_NAME(visitor)
 513 BOOST_PARAMETER_NAME(in(root_vertex))
 514 BOOST_PARAMETER_NAME(in(index_map))
 515 BOOST_PARAMETER_NAME(in_out(color_map))
 516
 517 namespace boost {
 518
 519     template <typename T = int>
 520     struct dfs_visitor
 521     {
 522     };
 523
 524     int vertex_index = 0;
 525 }
 526 ''') -->
 527 <!-- @test('compile') -->
 528 <p>The arguments to <tt class="docutils literal">BOOST_PARAMETER_FUNCTION</tt> are:</p>
 529 <ol class="arabic simple">
 530 <li>The return type of the resulting function template.  Parentheses around
 531 the return type prevent any commas it might contain from confusing the
 532 preprocessor, and are always required.</li>
 533 <li>The name of the resulting function template.</li>
 534 <li>The name of a namespace where we can find tag types whose names match the
 535 function's parameter names.</li>
 536 <li>The function signature.</li>
 537 </ol>
 538 </div>
 539 <div class="section" id="function-signatures">
 540 <h3>2.1.5&nbsp;&nbsp;&nbsp;Function Signatures</h3>
 541 <p>Function signatures are described as one or two adjacent parenthesized terms
 542 (a <a class="reference external" href="../../../preprocessor/doc/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
 543 order in which they'd be expected if passed positionally.  Any required
 544 parameters must come first, but the <tt class="docutils literal">(required … )</tt> clause can be omitted
 545 when all the parameters are optional.</p>
 546 <div class="section" id="required-parameters">
 547 <h4>2.1.5.1&nbsp;&nbsp;&nbsp;Required Parameters</h4>
 548 <div class="compound">
 549 <p class="compound-first">Required parameters are given first—nested in a <tt class="docutils literal">(required … )</tt>
 550 clause—as a series of two-element tuples describing each parameter name
 551 and any requirements on the argument type.  In this case there is only a
 552 single required parameter, so there's just a single tuple:</p>
 553 <pre class="compound-middle literal-block">
 554 (required <strong>(graph, *)</strong> )
 555 </pre>
 556 <p class="compound-last">Since <tt class="docutils literal">depth_first_search</tt> doesn't require any particular type for its
 557 <tt class="docutils literal">graph</tt> parameter, we use an asterix to indicate that any type is
 558 allowed.  Required parameters must always precede any optional parameters
 559 in a signature, but if there are <em>no</em> required parameters, the
 560 <tt class="docutils literal">(required … )</tt> clause can be omitted entirely.</p>
 561 </div>
 562 <!-- @example.prepend('''
 563 #include <boost/parameter.hpp>
 564
 565 BOOST_PARAMETER_NAME(graph)
 566
 567 BOOST_PARAMETER_FUNCTION((void), f, tag,
 568 ''') -->
 569 <!-- @example.append(') {}') -->
 570 <!-- @test('compile') -->
 571 </div>
 572 <div class="section" id="optional-parameters">
 573 <h4>2.1.5.2&nbsp;&nbsp;&nbsp;Optional Parameters</h4>
 574 <div class="compound">
 575 <p class="compound-first">Optional parameters—nested in an <tt class="docutils literal">(optional … )</tt> clause—are given as a
 576 series of adjacent <em>three</em>-element tuples describing the parameter name,
 577 any requirements on the argument type, <em>and</em> and an expression
 578 representing the parameter's default value:</p>
 579 <pre class="compound-last literal-block">
 580 (optional
 581     <strong>(visitor,     *, boost::dfs_visitor&lt;&gt;())
 582     (root_vertex, *, *vertices(graph).first)
 583     (index_map,   *, get(boost::vertex_index,graph))
 584     (color_map,   *,
 585         default_color_map(num_vertices(graph), index_map)
 586     )</strong>
 587 )
 588 </pre>
 589 </div>
 590 <!-- @example.prepend('''
 591 #include <boost/parameter.hpp>
 592
 593 namespace boost {
 594
 595     int vertex_index = 0;
 596
 597     template <typename T = int>
 598     struct dfs_visitor
 599     {
 600     };
 601 }
 602
 603 BOOST_PARAMETER_NAME(graph)
 604 BOOST_PARAMETER_NAME(visitor)
 605 BOOST_PARAMETER_NAME(in(root_vertex))
 606 BOOST_PARAMETER_NAME(in(index_map))
 607 BOOST_PARAMETER_NAME(in_out(color_map))
 608
 609 BOOST_PARAMETER_FUNCTION((void), f, tag,
 610     (required (graph, \*))
 611 ''') -->
 612 <!-- @example.append(') {}') -->
 613 <!-- @test('compile') -->
 614 </div>
 615 <div class="section" id="handling-in-out-consume-move-from-and-forward-parameters">
 616 <h4>2.1.5.3&nbsp;&nbsp;&nbsp;Handling “In”, “Out”, “Consume / Move-From”, and “Forward” Parameters</h4>
 617 <div class="compound">
 618 <p class="compound-first">By default, Boost.Parameter treats all parameters as if they were
 619 <em>forward</em> <a class="reference external" href="http://www.modernescpp.com/index.php/c-core-guidelines-how-to-pass-function-parameters">parameters</a>, which functions would take in by rvalue reference
 620 and only <tt class="docutils literal"><span class="pre">std::forward</span></tt> or <tt class="docutils literal"><span class="pre">boost::forward</span></tt> to other functions.  Such
 621 parameters can be <tt class="docutils literal">const</tt> lvalues, mutable lvalues, <tt class="docutils literal">const</tt> rvalues,
 622 or mutable rvalues.  Therefore, the default configuration grants the most
 623 flexibility to user code.  However:</p>
 624 <ul class="compound-middle simple">
 625 <li>Users can configure one or more parameters to be <em>in</em> <a class="reference external" href="http://www.modernescpp.com/index.php/c-core-guidelines-how-to-pass-function-parameters">parameters</a>,
 626 which can fall into the same categories as <em>forward</em> <a class="reference external" href="http://www.modernescpp.com/index.php/c-core-guidelines-how-to-pass-function-parameters">parameters</a> but
 627 are now passed by <tt class="docutils literal">const</tt> lvalue reference and so must only be read
 628 from.  Continuing from the previous example, to indicate that
 629 <tt class="docutils literal">root_vertex</tt> and <tt class="docutils literal">index_map</tt> are read-only, we wrap their names
 630 in <tt class="docutils literal"><span class="pre">in(…)</span></tt>.</li>
 631 <li>Users can configure one or more parameters to be either <em>out</em>
 632 <a class="reference external" href="http://www.modernescpp.com/index.php/c-core-guidelines-how-to-pass-function-parameters">parameters</a>, which functions would strictly write to, or <em>in-out</em>
 633 <a class="reference external" href="http://www.modernescpp.com/index.php/c-core-guidelines-how-to-pass-function-parameters">parameters</a>, which functions would both read from and write
 634 to.  Such parameters can only be mutable lvalues.  In the example, to
 635 indicate that <tt class="docutils literal">color_map</tt> is read-write, we wrap its name in
 636 <tt class="docutils literal"><span class="pre">in_out(…)</span></tt>.  Note that Boost.Parameter sees no functional
 637 difference between <tt class="docutils literal"><span class="pre">out(…)</span></tt> and <tt class="docutils literal"><span class="pre">in_out(…)</span></tt>, so you may choose
 638 whichever makes your interfaces more self-documenting.</li>
 639 <li>Users can configure one or more parameters to be <em>consume</em> or
 640 <em>move-from</em> <a class="reference external" href="http://www.modernescpp.com/index.php/c-core-guidelines-how-to-pass-function-parameters">parameters</a>, which functions would take in by mutable
 641 rvalue reference and <tt class="docutils literal"><span class="pre">std::move</span></tt> or <tt class="docutils literal"><span class="pre">boost::move</span></tt> as the last
 642 access step.  Such parameters can only be mutable
 643 rvalues.  Boost.Parameter supports wrapping the corresponding names in
 644 <tt class="docutils literal"><span class="pre">consume(…)</span></tt> or <tt class="docutils literal"><span class="pre">move_from(…)</span></tt>.</li>
 645 </ul>
 646 <pre class="compound-middle literal-block">
 647 BOOST_PARAMETER_NAME(graph)
 648 BOOST_PARAMETER_NAME(visitor)
 649 BOOST_PARAMETER_NAME(<strong>in(root_vertex)</strong>)
 650 BOOST_PARAMETER_NAME(<strong>in(index_map)</strong>)
 651 BOOST_PARAMETER_NAME(<strong>in_out(color_map)</strong>)
 652 </pre>
 653 <p class="compound-last">In order to see what happens when parameters are bound to arguments that
 654 violate their category constraints, attempt to compile the <a class="reference external" href="../../test/compose.cpp">compose.cpp</a>
 655 test program with either the <tt class="docutils literal">LIBS_PARAMETER_TEST_COMPILE_FAILURE_0</tt>
 656 macro or the <tt class="docutils literal">LIBS_PARAMETER_TEST_COMPILE_FAILURE_1</tt> macro
 657 <tt class="docutils literal">#defined</tt>.  You should encounter a compiler error caused by a specific
 658 constraint violation.</p>
 659 </div>
 660 <!-- @example.prepend('''
 661 #include <boost/parameter.hpp>
 662
 663 namespace boost {
 664
 665     int vertex_index = 0;
 666
 667     template <typename T = int>
 668     struct dfs_visitor
 669     {
 670     };
 671 }
 672 ''') -->
 673 <!-- @example.append('''
 674 BOOST_PARAMETER_FUNCTION((void), f, tag,
 675     (required (graph, \*))
 676     (optional
 677         (visitor,     \*, boost::dfs_visitor<>())
 678         (root_vertex, \*, \*vertices(graph).first)
 679         (index_map,   \*, get(boost::vertex_index, graph))
 680         (color_map,   \*,
 681             default_color_map(num_vertices(graph), index_map)
 682         )
 683     )
 684 )
 685 {
 686 }
 687 ''') -->
 688 <!-- @test('compile') -->
 689 </div>
 690 <div class="section" id="positional-arguments">
 691 <h4>2.1.5.4&nbsp;&nbsp;&nbsp;Positional Arguments</h4>
 692 <p>When arguments are passed positionally (without the use of keywords), they
 693 will be mapped onto parameters in the order the parameters are given in the
 694 signature, so for example in this call</p>
 695 <pre class="literal-block">
 696 graphs::depth_first_search(x, y);
 697 </pre>
 698 <!-- @ignore() -->
 699 <p><tt class="docutils literal">x</tt> will always be interpreted as a graph and <tt class="docutils literal">y</tt> will always be
 700 interpreted as a visitor.</p>
 701 </div>
 702 <div class="section" id="default-expression-evaluation">
 703 <h4>2.1.5.5&nbsp;&nbsp;&nbsp;Default Expression Evaluation</h4>
 704 <div class="compound">
 705 <p class="compound-first">Note that in our example, the value of the graph parameter is used in the
 706 default expressions for <tt class="docutils literal">root_vertex</tt>, <tt class="docutils literal">index_map</tt>, and <tt class="docutils literal">color_map</tt>.</p>
 707 <pre class="compound-last literal-block">
 708 (required (<strong>graph</strong>, *) )
 709 (optional
 710     (visitor,     *, boost::dfs_visitor&lt;&gt;())
 711     (root_vertex, *, *vertices(<strong>graph</strong>).first)
 712     (index_map,   *, get(boost::vertex_index, <strong>graph</strong>))
 713     (color_map,   *,
 714         default_color_map(num_vertices(<strong>graph</strong>), index_map)
 715     )
 716 )
 717 </pre>
 718 </div>
 719 <!-- @ignore()
 720
 721 A default expression is evaluated in the context of all preceding
 722 parameters, so you can use any of their values by name. -->
 723 <div class="compound">
 724 <p class="compound-first">A default expression is never evaluated—or even instantiated—if an actual
 725 argument is passed for that parameter.  We can actually demonstrate that
 726 with our code so far by replacing the body of <tt class="docutils literal">depth_first_search</tt> with
 727 something that prints the arguments:</p>
 728 <pre class="compound-middle literal-block">
 729 #include &lt;boost/graph/depth_first_search.hpp&gt;  // for dfs_visitor
 730
 731 BOOST_PARAMETER_FUNCTION(
 732     (bool), depth_first_search, tag
 733     <em>…signature goes here…</em>
 734 )
 735 {
 736     std::cout &lt;&lt; &quot;graph=&quot; &lt;&lt; graph;
 737     std::cout &lt;&lt; std::endl;
 738     std::cout &lt;&lt; &quot;visitor=&quot; &lt;&lt; visitor;
 739     std::cout &lt;&lt; std::endl;
 740     std::cout &lt;&lt; &quot;root_vertex=&quot; &lt;&lt; root_vertex;
 741     std::cout &lt;&lt; std::endl;
 742     std::cout &lt;&lt; &quot;index_map=&quot; &lt;&lt; index_map;
 743     std::cout &lt;&lt; std::endl;
 744     std::cout &lt;&lt; &quot;color_map=&quot; &lt;&lt; color_map;
 745     std::cout &lt;&lt; std::endl;
 746     return true;
 747 }
 748
 749 #include &lt;boost/core/lightweight_test.hpp&gt;
 750
 751 int main()
 752 {
 753     char const* g = &quot;1&quot;;
 754     depth_first_search(1, 2, 3, 4, 5);
 755     depth_first_search(
 756         g, '2', _color_map = '5',
 757         _index_map = &quot;4&quot;, _root_vertex = &quot;3&quot;
 758     );
 759     return boost::report_errors();
 760 }
 761 </pre>
 762 <p class="compound-last">Despite the fact that default expressions such as
 763 <tt class="docutils literal"><span class="pre">vertices(graph).first</span></tt> are ill-formed for the given <tt class="docutils literal">graph</tt>
 764 arguments, both calls will compile, and each one will print exactly the
 765 same thing.</p>
 766 </div>
 767 <!-- @example.prepend('''
 768 #include <boost/parameter.hpp>
 769 #include <iostream>
 770
 771 BOOST_PARAMETER_NAME(graph)
 772 BOOST_PARAMETER_NAME(visitor)
 773 BOOST_PARAMETER_NAME(root_vertex)
 774 BOOST_PARAMETER_NAME(index_map)
 775 BOOST_PARAMETER_NAME(color_map)
 776 ''') -->
 777 <!-- @example.replace_emphasis('''
 778 , (required
 779       (graph, \*)
 780       (visitor, \*)
 781       (root_vertex, \*)
 782       (index_map, \*)
 783       (color_map, \*)
 784   )
 785   ''') -->
 786 <!-- @test('run') -->
 787 </div>
 788 <div class="section" id="signature-matching-and-overloading">
 789 <h4>2.1.5.6&nbsp;&nbsp;&nbsp;Signature Matching and Overloading</h4>
 790 <p>In fact, the function signature is so general that any call to
 791 <tt class="docutils literal">depth_first_search</tt> with fewer than five arguments will match our function,
 792 provided we pass <em>something</em> for the required <tt class="docutils literal">graph</tt> parameter.  That might
 793 not seem to be a problem at first; after all, if the arguments don't match the
 794 requirements imposed by the implementation of <tt class="docutils literal">depth_first_search</tt>, a
 795 compilation error will occur later, when its body is instantiated.</p>
 796 <p>There are at least three problems with very general function signatures.</p>
 797 <ol class="arabic simple">
 798 <li>By the time our <tt class="docutils literal">depth_first_search</tt> is instantiated, it has been
 799 selected as the best matching overload.  Some other <tt class="docutils literal">depth_first_search</tt>
 800 overload might've worked had it been chosen instead.  By the time we see a
 801 compilation error, there's no chance to change that decision.</li>
 802 <li>Even if there are no overloads, error messages generated at instantiation
 803 time usually expose users to confusing implementation details.  For
 804 example, users might see references to names generated by
 805 <tt class="docutils literal">BOOST_PARAMETER_FUNCTION</tt> such as
 806 <tt class="docutils literal"><span class="pre">graphs::detail::depth_first_search_with_named_params</span></tt> (or worse—think
 807 of the kinds of errors you get from your STL implementation when you make
 808 a mistake).<a class="footnote-reference" href="#conceptsts" id="id7"><sup>4</sup></a></li>
 809 <li>The problems with exposing such permissive function template signatures
 810 have been the subject of much discussion, especially in the presence of
 811 <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#225">unqualified calls</a>.  If all we want is to avoid unintentional
 812 argument-dependent lookup (ADL), we can isolate <tt class="docutils literal">depth_first_search</tt> in
 813 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
 814 found via ADL?</li>
 815 </ol>
 816 <p>It's usually a good idea to prevent functions from being considered for
 817 overload resolution when the passed argument types aren't appropriate.  The
 818 library already does this when the required <tt class="docutils literal">graph</tt> parameter is not
 819 supplied, but we're not likely to see a depth first search that doesn't take a
 820 graph to operate on.  Suppose, instead, that we found a different depth first
 821 search algorithm that could work on graphs that don't model
 822 <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
 823 ambiguous:</p>
 824 <pre class="literal-block">
 825 // new overload
 826 BOOST_PARAMETER_FUNCTION((void), depth_first_search, (tag),
 827     (required (graph,*))( … )
 828 )
 829 {
 830     // new algorithm implementation
 831 }
 832
 833 …
 834
 835 // ambiguous!
 836 depth_first_search(boost::adjacency_list&lt;&gt;(), 2, &quot;hello&quot;);
 837 </pre>
 838 <!-- @ignore() -->
 839 <div class="section" id="predicate-requirements">
 840 <h5>2.1.5.6.1&nbsp;&nbsp;&nbsp;Predicate Requirements</h5>
 841 <p>We really don't want the compiler to consider the original version of
 842 <tt class="docutils literal">depth_first_search</tt> because the <tt class="docutils literal">root_vertex</tt> argument, <tt class="docutils literal">&quot;hello&quot;</tt>,
 843 doesn't meet the <a class="reference internal" href="#parameter-table">requirement</a> that it match the <tt class="docutils literal">graph</tt> parameter's vertex
 844 descriptor type.  Instead, this call should just invoke our new overload.  To
 845 take the original <tt class="docutils literal">depth_first_search</tt> overload out of contention, we first
 846 encode this requirement as follows:</p>
 847 <pre class="literal-block">
 848 struct vertex_descriptor_predicate
 849 {
 850     template &lt;typename T, typename Args&gt;
 851     struct apply
 852       : boost::mpl::if_&lt;
 853             boost::is_convertible&lt;
 854                 T
 855               , typename boost::graph_traits&lt;
 856                     typename boost::parameter::value_type&lt;
 857                         Args
 858                       , graphs::graph
 859                     &gt;::type
 860                 &gt;::vertex_descriptor
 861             &gt;
 862           , boost::mpl::true_
 863           , boost::mpl::false_
 864         &gt;
 865     {
 866     };
 867 };
 868 </pre>
 869 <p>This encoding is an <a class="reference external" href="../../../mpl/doc/refmanual/metafunction-class.html">MPL Binary Metafunction Class</a>, a type with a nested
 870 <tt class="docutils literal">apply</tt> metafunction that takes in two template arguments.  For the first
 871 template argument, Boost.Parameter will pass in the type on which we will
 872 impose the requirement.  For the second template argument, Boost.Parameter
 873 will pass in the entire argument pack, making it possible to extract the
 874 type of each of the other <tt class="docutils literal">depth_first_search</tt> parameters via the
 875 <tt class="docutils literal">value_type</tt> metafunction and the corresponding keyword tag type.  The
 876 result <tt class="docutils literal">type</tt> of the <tt class="docutils literal">apply</tt> metafunction will be equivalent to
 877 <tt class="docutils literal"><span class="pre">boost::mpl::true_</span></tt> if <tt class="docutils literal">T</tt> fulfills our requirement as imposed by the
 878 <tt class="docutils literal"><span class="pre">boost::is_convertible</span></tt> statement; otherwise, the result will be
 879 equivalent to <tt class="docutils literal"><span class="pre">boost::mpl::false_</span></tt>.</p>
 880 <p>At this point, we can append the name of our metafunction class, in
 881 parentheses, to the appropriate <tt class="docutils literal">*</tt> element of the function signature.</p>
 882 <pre class="literal-block">
 883 (root_vertex
 884   , *(<strong>vertex_descriptor_predicate</strong>)
 885   , *vertices(graph).first
 886 )
 887 </pre>
 888 <!-- @ignore() -->
 889 <p>Now the original <tt class="docutils literal">depth_first_search</tt> will only be called when the
 890 <tt class="docutils literal">root_vertex</tt> argument can be converted to the graph's vertex descriptor
 891 type, and our example that <em>was</em> ambiguous will smoothly call the new
 892 overload.</p>
 893 <p>We can encode the requirements on other arguments using the same concept; only
 894 the implementation of the nested <tt class="docutils literal">apply</tt> metafunction needs to be tweaked
 895 for each argument.  There's no space to give a complete description of graph
 896 library details here, but suffice it to show that the next few metafunction
 897 classes provide the necessary checks.</p>
 898 <pre class="literal-block">
 899 struct graph_predicate
 900 {
 901     template &lt;typename T, typename Args&gt;
 902     struct apply
 903       : boost::mpl::eval_if&lt;
 904             boost::is_convertible&lt;
 905                 typename boost::graph_traits&lt;T&gt;::traversal_category
 906               , boost::incidence_graph_tag
 907             &gt;
 908           , boost::mpl::if_&lt;
 909                 boost::is_convertible&lt;
 910                     typename boost::graph_traits&lt;T&gt;::traversal_category
 911                   , boost::vertex_list_graph_tag
 912                 &gt;
 913               , boost::mpl::true_
 914               , boost::mpl::false_
 915             &gt;
 916         &gt;
 917     {
 918     };
 919 };
 920
 921 struct index_map_predicate
 922 {
 923     template &lt;typename T, typename Args&gt;
 924     struct apply
 925       : boost::mpl::eval_if&lt;
 926             boost::is_integral&lt;
 927                 typename boost::property_traits&lt;T&gt;::value_type
 928             &gt;
 929           , boost::mpl::if_&lt;
 930                 boost::is_same&lt;
 931                     typename boost::property_traits&lt;T&gt;::key_type
 932                   , typename boost::graph_traits&lt;
 933                         typename boost::parameter::value_type&lt;
 934                             Args
 935                           , graphs::graph
 936                         &gt;::type
 937                     &gt;::vertex_descriptor
 938                 &gt;
 939               , boost::mpl::true_
 940               , boost::mpl::false_
 941             &gt;
 942         &gt;
 943     {
 944     };
 945 };
 946
 947 struct color_map_predicate
 948 {
 949     template &lt;typename T, typename Args&gt;
 950     struct apply
 951       : boost::mpl::if_&lt;
 952             boost::is_same&lt;
 953                 typename boost::property_traits&lt;T&gt;::key_type
 954               , typename boost::graph_traits&lt;
 955                     typename boost::parameter::value_type&lt;
 956                         Args
 957                       , graphs::graph
 958                     &gt;::type
 959                 &gt;::vertex_descriptor
 960             &gt;
 961           , boost::mpl::true_
 962           , boost::mpl::false_
 963         &gt;
 964     {
 965     };
 966 };
 967 </pre>
 968 <p>Likewise, computing the default value for the <tt class="docutils literal">color_map</tt> parameter is no
 969 trivial matter, so it's best to factor the computation out to a separate
 970 function template.</p>
 971 <pre class="literal-block">
 972 template &lt;typename Size, typename IndexMap&gt;
 973 boost::iterator_property_map&lt;
 974     std::vector&lt;boost::default_color_type&gt;::iterator
 975   , IndexMap
 976   , boost::default_color_type
 977   , boost::default_color_type&amp;
 978 &gt;&amp;
 979     default_color_map(Size num_vertices, IndexMap const&amp; index_map)
 980 {
 981     static std::vector&lt;boost::default_color_type&gt; colors(num_vertices);
 982     static boost::iterator_property_map&lt;
 983         std::vector&lt;boost::default_color_type&gt;::iterator
 984       , IndexMap
 985       , boost::default_color_type
 986       , boost::default_color_type&amp;
 987     &gt; m(colors.begin(), index_map);
 988     return m;
 989 }
 990 </pre>
 991 <p>The signature encloses each predicate metafunction in parentheses <em>preceded
 992 by an asterix</em>, as follows:</p>
 993 <pre class="literal-block">
 994 BOOST_PARAMETER_FUNCTION((void), depth_first_search, graphs,
 995 (required
 996     (graph, *(<strong>graph_predicate</strong>))
 997 )
 998 (optional
 999     (visitor
1000       , *  // not easily checkable
1001       , boost::dfs_visitor&lt;&gt;()
1002     )
1003     (root_vertex
1004       , (<strong>vertex_descriptor_predicate</strong>)
1005       , *vertices(graph).first
1006     )
1007     (index_map
1008       , *(<strong>index_map_predicate</strong>)
1009       , get(boost::vertex_index, graph)
1010     )
1011     (color_map
1012       , *(<strong>color_map_predicate</strong>)
1013       , default_color_map(num_vertices(graph), index_map)
1014     )
1015 )
1016 )
1017 </pre>
1018 <!-- @example.prepend('''
1019 #include <boost/parameter.hpp>
1020 #include <boost/graph/adjacency_list.hpp>
1021 #include <boost/graph/depth_first_search.hpp>
1022 #include <boost/graph/graph_traits.hpp>
1023 #include <boost/property_map/property_map.hpp>
1024 #include <boost/mpl/and.hpp>
1025 #include <boost/type_traits/is_convertible.hpp>
1026 #include <boost/type_traits/is_integral.hpp>
1027 #include <boost/type_traits/is_same.hpp>
1028 #include <vector>
1029 #include <utility>
1030
1031 BOOST_PARAMETER_NAME((_graph, graphs) graph)
1032 BOOST_PARAMETER_NAME((_visitor, graphs) visitor)
1033 BOOST_PARAMETER_NAME((_root_vertex, graphs) in(root_vertex))
1034 BOOST_PARAMETER_NAME((_index_map, graphs) in(index_map))
1035 BOOST_PARAMETER_NAME((_color_map, graphs) in_out(color_map))
1036 ''') -->
1037 <!-- @example.append('''
1038 {
1039 }
1040
1041 #include <boost/core/lightweight_test.hpp>
1042 #include <boost/graph/adjacency_list.hpp>
1043 #include <utility>
1044
1045 int main()
1046 {
1047     typedef boost::adjacency_list<
1048         boost::vecS, boost::vecS, boost::directedS
1049     > G;
1050     enum {u, v, w, x, y, z, N};
1051     typedef std::pair<int, int> E;
1052     E edges[] = {
1053         E(u, v), E(u, x), E(x, v), E(y, x),
1054         E(v, y), E(w, y), E(w,z), E(z, z)
1055     };
1056     G g(edges, edges + sizeof(edges) / sizeof(E), N);
1057
1058     depth_first_search(g);
1059     depth_first_search(g, _root_vertex = static_cast<int>(x));
1060     return boost::report_errors();
1061 }
1062 ''') -->
1063 <!-- @test('run') -->
1064 <p>It usually isn't necessary to so completely encode the type requirements on
1065 arguments to generic functions.  However, doing so is worth the effort: your
1066 code will be more self-documenting and will often provide a better user
1067 experience.  You'll also have an easier transition to the C++20 standard with
1068 <a class="reference internal" href="#conceptsts">language support for constraints and concepts</a>.</p>
1069 </div>
1070 <div class="section" id="more-on-type-requirements">
1071 <h5>2.1.5.6.2&nbsp;&nbsp;&nbsp;More on Type Requirements</h5>
1072 <p>Encoding type requirements onto a function's parameters is essential for
1073 enabling the function to have deduced parameter interface.  Let's revisit the
1074 <tt class="docutils literal">new_window</tt> example for a moment:</p>
1075 <pre class="literal-block">
1076 window* w = new_window(
1077     movable_=false
1078   , &quot;alert box&quot;
1079 );
1080 window* w = new_window(
1081     &quot;alert box&quot;
1082   , movable_=false
1083 );
1084 </pre>
1085 <!-- @ignore() -->
1086 <p>The goal this time is to be able to invoke the <tt class="docutils literal">new_window</tt> function without
1087 specifying the keywords.  For each parameter that has a required type, we can
1088 enclose that type in parentheses, then <em>replace</em> the <tt class="docutils literal">*</tt> element of the
1089 parameter signature:</p>
1090 <pre class="literal-block">
1091 BOOST_PARAMETER_NAME((name_, keywords) name)
1092 BOOST_PARAMETER_NAME((movable_, keywords) movable)
1093
1094 BOOST_PARAMETER_FUNCTION((window*), new_window, keywords,
1095     (deduced
1096         (required
1097             (name, <em>(char const*)</em>)
1098             (movable, <em>(bool)</em>)
1099         )
1100     )
1101 )
1102 {
1103     // ...
1104 }
1105 </pre>
1106 <!-- @ignore() -->
1107 <p>The following statements will now work and are equivalent to each other as
1108 well as the previous statements:</p>
1109 <pre class="literal-block">
1110 window* w = new_window(false, &quot;alert box&quot;);
1111 window* w = new_window(&quot;alert box&quot;, false);
1112 </pre>
1113 <!-- @ignore() -->
1114 </div>
1115 </div>
1116 <div class="section" id="deduced-parameters">
1117 <h4>2.1.5.7&nbsp;&nbsp;&nbsp;Deduced Parameters</h4>
1118 <p>To further illustrate deduced parameter support, consider the example of the
1119 <a class="reference external" href="../../../python/doc/v2/def.html"><tt class="docutils literal">def</tt></a> function from <a class="reference external" href="../../../python/doc/index.html">Boost.Python</a>.  Its signature is roughly as follows:</p>
1120 <pre class="literal-block">
1121 template &lt;
1122     typename Function
1123   , typename KeywordExpression
1124   , typename CallPolicies
1125 &gt;
1126 void def(
1127     // Required parameters
1128     char const* name, Function func
1129
1130     // Optional, deduced parameters
1131   , char const* docstring = &quot;&quot;
1132   , KeywordExpression keywords = no_keywords()
1133   , CallPolicies policies = default_call_policies()
1134 );
1135 </pre>
1136 <!-- @ignore() -->
1137 <p>Try not to be too distracted by the use of the term “keywords” in this
1138 example: although it means something analogous in Boost.Python to what
1139 it means in the Parameter library, for the purposes of this exercise
1140 you can think of it as being completely different.</p>
1141 <p>When calling <tt class="docutils literal">def</tt>, only two arguments are required.  The association
1142 between any additional arguments and their parameters can be determined by the
1143 types of the arguments actually passed, so the caller is neither required to
1144 remember argument positions or explicitly specify parameter names for those
1145 arguments.  To generate this interface using <tt class="docutils literal">BOOST_PARAMETER_FUNCTION</tt>, we
1146 need only enclose the deduced parameters in a <tt class="docutils literal">(deduced …)</tt> clause, as
1147 follows:</p>
1148 <pre class="literal-block">
1149 char const*&amp; blank_char_ptr()
1150 {
1151     static char const* larr = &quot;&quot;;
1152     return larr;
1153 }
1154
1155 BOOST_PARAMETER_FUNCTION(
1156     (bool), def, tag,
1157
1158     (required (name, (char const*)) (func,*) )  // nondeduced
1159
1160     <strong>(deduced</strong>
1161         (optional
1162             (docstring, (char const*), &quot;&quot;)
1163
1164             (keywords
1165                 // see<a class="footnote-reference" href="#is-keyword-expression" id="id13"><sup>5</sup></a>
1166               , *(is_keyword_expression&lt;boost::mpl::_&gt;)
1167               , no_keywords()
1168             )
1169
1170             (policies
1171               , *(
1172                     boost::mpl::eval_if&lt;
1173                         boost::is_convertible&lt;boost::mpl::_,char const*&gt;
1174                       , boost::mpl::false_
1175                       , boost::mpl::if_&lt;
1176                             // see<a class="footnote-reference" href="#is-keyword-expression" id="id14"><sup>5</sup></a>
1177                             is_keyword_expression&lt;boost::mpl::_&gt;
1178                           , boost::mpl::false_
1179                           , boost::mpl::true_
1180                         &gt;
1181                     &gt;
1182                 )
1183               , default_call_policies()
1184             )
1185         )
1186     <strong>)</strong>
1187 )
1188 {
1189     <em>…</em>
1190 }
1191 </pre>
1192 <!-- @example.replace_emphasis('return true;') -->
1193 <!-- @example.prepend('''
1194 #include <boost/parameter.hpp>
1195
1196 BOOST_PARAMETER_NAME(name)
1197 BOOST_PARAMETER_NAME(func)
1198 BOOST_PARAMETER_NAME(docstring)
1199 BOOST_PARAMETER_NAME(keywords)
1200 BOOST_PARAMETER_NAME(policies)
1201
1202 struct default_call_policies
1203 {
1204 };
1205
1206 struct no_keywords
1207 {
1208 };
1209
1210 struct keywords
1211 {
1212 };
1213
1214 template <typename T>
1215 struct is_keyword_expression
1216   : boost::mpl::false_
1217 {
1218 };
1219
1220 template <>
1221 struct is_keyword_expression<keywords>
1222   : boost::mpl::true_
1223 {
1224 };
1225
1226 default_call_policies some_policies;
1227
1228 void f()
1229 {
1230 }
1231
1232 #include <boost/mpl/placeholders.hpp>
1233 #include <boost/mpl/if.hpp>
1234 #include <boost/mpl/eval_if.hpp>
1235 #include <boost/type_traits/is_convertible.hpp>
1236
1237 ''') -->
1238 <div class="admonition-syntax-note admonition">
1239 <p class="first admonition-title">Syntax Note</p>
1240 <p class="last">A <tt class="docutils literal">(deduced …)</tt> clause always contains a <tt class="docutils literal">(required …)</tt> and/or an
1241 <tt class="docutils literal">(optional …)</tt> subclause, and must follow any <tt class="docutils literal">(required …)</tt> or
1242 <tt class="docutils literal">(optional …)</tt> clauses indicating nondeduced parameters at the outer
1243 level.</p>
1244 </div>
1245 <p>With the declaration above, the following two calls are equivalent:</p>
1246 <pre class="literal-block">
1247 char const* f_name = &quot;f&quot;;
1248 def(
1249     f_name
1250   , &amp;f
1251   , <strong>some_policies</strong>
1252   , <strong>&quot;Documentation for f&quot;</strong>
1253 );
1254 def(
1255     f_name
1256   , &amp;f
1257   , <strong>&quot;Documentation for f&quot;</strong>
1258   , <strong>some_policies</strong>
1259 );
1260 </pre>
1261 <!-- @example.prepend('''
1262 int main()
1263 {
1264 ''') -->
1265 <p>If the user wants to pass a <tt class="docutils literal">policies</tt> argument that was also, for some
1266 reason, convertible to <tt class="docutils literal">char const*</tt>, she can always specify the parameter
1267 name explicitly, as follows:</p>
1268 <pre class="literal-block">
1269 def(
1270     f_name
1271   , &amp;f
1272   , <strong>_policies = some_policies</strong>
1273   , &quot;Documentation for f&quot;
1274 );
1275 </pre>
1276 <!-- @example.append('}') -->
1277 <!-- @test('compile', howmany='all') -->
1278 <p>The <a class="reference external" href="../../test/deduced.cpp">deduced.cpp</a> and <a class="reference external" href="../../test/deduced_dependent_predicate.cpp">deduced_dependent_predicate.cpp</a> test programs
1279 demonstrate additional usage of deduced parameter support.</p>
1280 </div>
1281 <div class="section" id="parameter-dependent-return-types">
1282 <h4>2.1.5.8&nbsp;&nbsp;&nbsp;Parameter-Dependent Return Types</h4>
1283 <p>For some algorithms, the return type depends on at least one of the argument
1284 types.  However, there is one gotcha to avoid when encoding this return type
1285 while using <tt class="docutils literal">BOOST_PARAMETER_FUNCTION</tt> or other code generation macros.  As
1286 an example, given the following definitions:</p>
1287 <pre class="literal-block">
1288 BOOST_PARAMETER_NAME(x)
1289 BOOST_PARAMETER_NAME(y)
1290 BOOST_PARAMETER_NAME(z)
1291 </pre>
1292 <!-- @ignore() -->
1293 <p>Let our algorithm simply return one of its arguments.  If we naïvely implement
1294 its return type in terms of <tt class="docutils literal"><span class="pre">parameter::value_type</span></tt>:</p>
1295 <pre class="literal-block">
1296 BOOST_PARAMETER_FUNCTION(
1297     (typename parameter::value_type&lt;Args,tag::y&gt;::type), return_y, tag,
1298     (deduced
1299         (required
1300             (x, (std::map&lt;char const*,std::string&gt;))
1301             (y, (char const*))
1302         )
1303         (optional
1304             (z, (int), 4)
1305         )
1306     )
1307 )
1308 {
1309     return y;
1310 }
1311 </pre>
1312 <!-- @ignore() -->
1313 <p>Then using <tt class="docutils literal">return_y</tt> in any manner other than with positional arguments
1314 will result in a compiler error:</p>
1315 <pre class="literal-block">
1316 std::map&lt;char const*,std::string&gt; k2s;
1317 assert(&quot;foo&quot; == return_y(2, k2s, &quot;foo&quot;));  // error!
1318 </pre>
1319 <!-- @ignore() -->
1320 <p>The problem is that even though <tt class="docutils literal">y</tt> is a required parameter,
1321 <tt class="docutils literal">BOOST_PARAMETER_FUNCTION</tt> will generate certain overloads for which the
1322 argument pack type <tt class="docutils literal">Args</tt> does not actually contain the keyword tag type
1323 <tt class="docutils literal"><span class="pre">tag::y</span></tt>.  The solution is to use SFINAE to preclude generation of those
1324 overloads.  Since <tt class="docutils literal"><span class="pre">parameter::value_type</span></tt> is a metafunction, our tool for
1325 the job is <tt class="docutils literal">lazy_enable_if</tt>:</p>
1326 <pre class="literal-block">
1327 BOOST_PARAMETER_FUNCTION(
1328     (
1329         // Whenever using 'enable_if', 'disable_if', and so on,
1330         // do not add the 'typename' keyword in front.
1331         boost::lazy_enable_if&lt;
1332             typename mpl::has_key&lt;Args,tag::y&gt;::type
1333           , parameter::value_type&lt;Args,tag::y&gt;
1334         &gt;
1335         // Whenever using 'enable_if', 'disable_if', and so on,
1336         // do not add '::type' here.
1337     ), return_y, tag,
1338     (deduced
1339         (required
1340             (x, (std::map&lt;char const*,std::string&gt;))
1341             (y, (char const*))
1342         )
1343         (optional
1344             (z, (int), 4)
1345         )
1346     )
1347 )
1348 {
1349     return y;
1350 }
1351 </pre>
1352 <!-- @ignore() -->
1353 <p>For a working demonstration, see <a class="reference external" href="../../test/preprocessor_deduced.cpp">preprocessor_deduced.cpp</a>.</p>
1354 </div>
1355 </div>
1356 </div>
1357 <div class="section" id="parameter-enabled-member-functions">
1358 <h2><a class="toc-backref" href="#id28">2.2&nbsp;&nbsp;&nbsp;Parameter-Enabled Member Functions</a></h2>
1359 <p>The <tt class="docutils literal">BOOST_PARAMETER_MEMBER_FUNCTION</tt> and
1360 <tt class="docutils literal">BOOST_PARAMETER_CONST_MEMBER_FUNCTION</tt> macros accept exactly the same
1361 arguments as <tt class="docutils literal">BOOST_PARAMETER_FUNCTION</tt>, but are designed to be used within
1362 the body of a class:</p>
1363 <pre class="literal-block">
1364 BOOST_PARAMETER_NAME(arg1)
1365 BOOST_PARAMETER_NAME(arg2)
1366
1367 struct callable2
1368 {
1369     BOOST_PARAMETER_CONST_MEMBER_FUNCTION(
1370         (void), call, tag, (required (arg1,(int))(arg2,(int)))
1371     )
1372     {
1373         std::cout &lt;&lt; arg1 &lt;&lt; &quot;, &quot; &lt;&lt; arg2;
1374         std::cout &lt;&lt; std::endl;
1375     }
1376 };
1377
1378 #include &lt;boost/core/lightweight_test.hpp&gt;
1379
1380 int main()
1381 {
1382     callable2 c2;
1383     callable2 const&amp; c2_const = c2;
1384     c2_const.call(1, 2);
1385     return boost::report_errors();
1386 }
1387 </pre>
1388 <!-- @example.prepend('''
1389 #include <boost/parameter.hpp>
1390 #include <iostream>
1391 using namespace boost::parameter;
1392 ''') -->
1393 <!-- @test('run') -->
1394 <p>These macros don't directly allow a function's interface to be separated from
1395 its implementation, but you can always forward arguments on to a separate
1396 implementation function:</p>
1397 <pre class="literal-block">
1398 struct callable2
1399 {
1400     BOOST_PARAMETER_CONST_MEMBER_FUNCTION(
1401         (void), call, tag, (required (arg1,(int))(arg2,(int)))
1402     )
1403     {
1404         call_impl(arg1, arg2);
1405     }
1406
1407  private:
1408     void call_impl(int, int);  // implemented elsewhere.
1409 };
1410 </pre>
1411 <!-- @example.prepend('''
1412 #include <boost/parameter.hpp>
1413
1414 BOOST_PARAMETER_NAME(arg1)
1415 BOOST_PARAMETER_NAME(arg2)
1416 using namespace boost::parameter;
1417 ''') -->
1418 <!-- @test('compile') -->
1419 <div class="section" id="static-member-functions">
1420 <h3>2.2.1&nbsp;&nbsp;&nbsp;Static Member Functions</h3>
1421 <p>To expose a static member function, simply insert the keyword “<tt class="docutils literal">static</tt>”
1422 before the function name:</p>
1423 <pre class="literal-block">
1424 BOOST_PARAMETER_NAME(arg1)
1425
1426 struct somebody
1427 {
1428     BOOST_PARAMETER_MEMBER_FUNCTION(
1429         (void), <strong>static</strong> f, tag, (optional (arg1,(int),0))
1430     )
1431     {
1432         std::cout &lt;&lt; arg1 &lt;&lt; std::endl;
1433     }
1434 };
1435
1436 #include &lt;boost/core/lightweight_test.hpp&gt;
1437
1438 int main()
1439 {
1440     somebody::f();
1441     somebody::f(4);
1442     return boost::report_errors();
1443 }
1444 </pre>
1445 <!-- @example.prepend('''
1446 #include <boost/parameter.hpp>
1447 #include <iostream>
1448 using namespace boost::parameter;
1449 ''') -->
1450 <!-- @test('run') -->
1451 </div>
1452 </div>
1453 <div class="section" id="parameter-enabled-function-call-operators">
1454 <h2><a class="toc-backref" href="#id29">2.3&nbsp;&nbsp;&nbsp;Parameter-Enabled Function Call Operators</a></h2>
1455 <p>The <tt class="docutils literal">BOOST_PARAMETER_FUNCTION_CALL_OPERATOR</tt> and
1456 <tt class="docutils literal">BOOST_PARAMETER_CONST_FUNCTION_CALL_OPERATOR</tt> macros accept the same
1457 arguments as the <tt class="docutils literal">BOOST_PARAMETER_MEMBER_FUNCTION</tt> and
1458 <tt class="docutils literal">BOOST_PARAMETER_CONST_MEMBER_FUNCTION</tt> macros except for the function name,
1459 because these macros allow instances of the enclosing classes to be treated as
1460 function objects:</p>
1461 <pre class="literal-block">
1462 BOOST_PARAMETER_NAME(first_arg)
1463 BOOST_PARAMETER_NAME(second_arg)
1464
1465 struct callable2
1466 {
1467     BOOST_PARAMETER_CONST_FUNCTION_CALL_OPERATOR(
1468         (void), tag, (required (first_arg,(int))(second_arg,(int)))
1469     )
1470     {
1471         std::cout &lt;&lt; first_arg &lt;&lt; &quot;, &quot;;
1472         std::cout &lt;&lt; second_arg &lt;&lt; std::endl;
1473     }
1474 };
1475
1476 #include &lt;boost/core/lightweight_test.hpp&gt;
1477
1478 int main()
1479 {
1480     callable2 c2;
1481     callable2 const&amp; c2_const = c2;
1482     c2_const(1, 2);
1483     return boost::report_errors();
1484 }
1485 </pre>
1486 <!-- @example.prepend('''
1487 #include <boost/parameter.hpp>
1488 #include <iostream>
1489 using namespace boost::parameter;
1490 ''') -->
1491 <!-- @test('run') -->
1492 </div>
1493 <div class="section" id="parameter-enabled-constructors">
1494 <h2><a class="toc-backref" href="#id30">2.4&nbsp;&nbsp;&nbsp;Parameter-Enabled Constructors</a></h2>
1495 <p>The lack of a “delegating constructor” feature in C++
1496 (<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>)
1497 limits somewhat the quality of interface this library can provide
1498 for defining parameter-enabled constructors.  The usual workaround
1499 for a lack of constructor delegation applies: one must factor the
1500 common logic into one or more base classes.</p>
1501 <p>Let's build a parameter-enabled constructor that simply prints its
1502 arguments.  The first step is to write a base class whose
1503 constructor accepts a single argument known as an <a class="reference external" href="reference.html#argumentpack"><span class="concept">ArgumentPack</span></a>:
1504 a bundle of references to the actual arguments, tagged with their
1505 keywords.  The values of the actual arguments are extracted from
1506 the <span class="concept">ArgumentPack</span> by <em>indexing</em> it with keyword objects:</p>
1507 <pre class="literal-block">
1508 BOOST_PARAMETER_NAME(name)
1509 BOOST_PARAMETER_NAME(index)
1510
1511 struct myclass_impl
1512 {
1513     template &lt;typename ArgumentPack&gt;
1514     myclass_impl(ArgumentPack const&amp; args)
1515     {
1516         std::cout &lt;&lt; &quot;name = &quot; &lt;&lt; args[_name];
1517         std::cout &lt;&lt; &quot;; index = &quot; &lt;&lt; args[_index | 42];
1518         std::cout &lt;&lt; std::endl;
1519     }
1520 };
1521 </pre>
1522 <!-- @example.prepend('''
1523 #include <boost/parameter.hpp>
1524 #include <iostream>
1525 ''') -->
1526 <p>Note that the bitwise or (“<tt class="docutils literal">|</tt>”) operator has a special meaning when
1527 applied to keyword objects that are passed to an <span class="concept">ArgumentPack</span>'s indexing
1528 operator: it is used to indicate a default value.  In this case if there is no
1529 <tt class="docutils literal">index</tt> parameter in the <span class="concept">ArgumentPack</span>, <tt class="docutils literal">42</tt> will be used instead.</p>
1530 <p>Now we are ready to write the parameter-enabled constructor interface:</p>
1531 <pre class="literal-block">
1532 struct myclass : myclass_impl
1533 {
1534     BOOST_PARAMETER_CONSTRUCTOR(
1535         myclass, (myclass_impl), tag
1536       , (required (name,*)) (optional (index,*))
1537     ) // no semicolon
1538 };
1539 </pre>
1540 <p>Since we have supplied a default value for <tt class="docutils literal">index</tt> but not for <tt class="docutils literal">name</tt>,
1541 only <tt class="docutils literal">name</tt> is required.  We can exercise our new interface as follows:</p>
1542 <pre class="literal-block">
1543 myclass x(&quot;bob&quot;, 3);                      // positional
1544 myclass y(_index = 12, _name = &quot;sally&quot;);  // named
1545 myclass z(&quot;june&quot;);                        // positional/defaulted
1546 </pre>
1547 <!-- @example.wrap('''
1548 #include <boost/core/lightweight_test.hpp>
1549
1550 int main() {
1551 ''', ' return boost::report_errors(); }') -->
1552 <!-- @test('run', howmany='all') -->
1553 <p>For more on <span class="concept">ArgumentPack</span> manipulation, see the <a class="reference internal" href="#advanced-topics">Advanced Topics</a> section.</p>
1554 </div>
1555 <div class="section" id="parameter-enabled-class-templates">
1556 <h2><a class="toc-backref" href="#id31">2.5&nbsp;&nbsp;&nbsp;Parameter-Enabled Class Templates</a></h2>
1557 <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>
1558 <pre class="literal-block">
1559 template &lt;
1560     ValueType, BaseList = bases&lt;&gt;
1561   , HeldType = ValueType, Copyable = void
1562 &gt;
1563 class class_;
1564 </pre>
1565 <!-- @ignore() -->
1566 <p>Only the first argument, <tt class="docutils literal">ValueType</tt>, is required.</p>
1567 <div class="section" id="named-template-parameters">
1568 <h3>2.5.1&nbsp;&nbsp;&nbsp;Named Template Parameters</h3>
1569 <p>First, we'll build an interface that allows users to pass arguments
1570 positionally or by name:</p>
1571 <pre class="literal-block">
1572 struct B
1573 {
1574     virtual ~B() = 0;
1575 };
1576
1577 struct D : B
1578 {
1579     ~D();
1580 };
1581
1582 class_&lt;
1583     <strong>class_type&lt;B&gt;</strong>
1584   , <strong>copyable&lt;boost::noncopyable&gt;</strong>
1585 &gt; …;
1586
1587 class_&lt;
1588     <strong>D</strong>
1589   , <strong>held_type&lt;std::auto_ptr&lt;D&gt; &gt;</strong>
1590   , <strong>base_list&lt;bases&lt;B&gt; &gt;</strong>
1591 &gt; …;
1592 </pre>
1593 <!-- @ignore() -->
1594 <div class="section" id="template-keywords">
1595 <h4>2.5.1.1&nbsp;&nbsp;&nbsp;Template Keywords</h4>
1596 <p>The first step is to define keywords for each template parameter:</p>
1597 <pre class="literal-block">
1598 namespace boost { namespace python {
1599
1600     BOOST_PARAMETER_TEMPLATE_KEYWORD(class_type)
1601     BOOST_PARAMETER_TEMPLATE_KEYWORD(base_list)
1602     BOOST_PARAMETER_TEMPLATE_KEYWORD(held_type)
1603     BOOST_PARAMETER_TEMPLATE_KEYWORD(copyable)
1604 }}
1605 </pre>
1606 <!-- @example.prepend('#include <boost/parameter.hpp>') -->
1607 <!-- @test('compile') -->
1608 <p>The declaration of the <tt class="docutils literal">class_type</tt> keyword you see here is equivalent to:</p>
1609 <pre class="literal-block">
1610 namespace boost { namespace python {
1611     namespace tag {
1612
1613         struct class_type;  // keyword tag type
1614     }
1615
1616     template &lt;typename T&gt;
1617     struct class_type
1618       : parameter::template_keyword&lt;tag::class_type,T&gt;
1619     {
1620     };
1621 }}
1622 </pre>
1623 <!-- @example.prepend('#include <boost/parameter.hpp>') -->
1624 <!-- @test('compile') -->
1625 <p>It defines a keyword tag type named <tt class="docutils literal"><span class="pre">tag::class_type</span></tt> and a
1626 <em>parameter passing template</em> named <tt class="docutils literal">class_type</tt>.</p>
1627 </div>
1628 <div class="section" id="class-template-skeleton">
1629 <h4>2.5.1.2&nbsp;&nbsp;&nbsp;Class Template Skeleton</h4>
1630 <p>The next step is to define the skeleton of our class template, which has three
1631 optional parameters.  Because the user may pass arguments in any order, we
1632 don't know the actual identities of these parameters, so it would be premature
1633 to use descriptive names or write out the actual default values for any of
1634 them.  Instead, we'll give them generic names and use the special type
1635 <tt class="docutils literal"><span class="pre">boost::parameter::void_</span></tt> as a default:</p>
1636 <pre class="literal-block">
1637 namespace boost { namespace python {
1638
1639     template &lt;
1640         typename A0
1641       , typename A1 = boost::parameter::void_
1642       , typename A2 = boost::parameter::void_
1643       , typename A3 = boost::parameter::void_
1644     &gt;
1645     struct class_
1646     {
1647         <em>…</em>
1648     };
1649 }}
1650 </pre>
1651 <!-- @example.prepend('#include <boost/parameter.hpp>') -->
1652 <!-- @example.replace_emphasis('') -->
1653 <!-- @test('compile') -->
1654 </div>
1655 <div class="section" id="class-template-signatures">
1656 <h4>2.5.1.3&nbsp;&nbsp;&nbsp;Class Template Signatures</h4>
1657 <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
1658 “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
1659 required and optional parameters in their positional order, along with any
1660 type requirements (note that it does <em>not</em> specify defaults -- those will be
1661 dealt with separately):</p>
1662 <pre class="literal-block">
1663 namespace boost { namespace python {
1664
1665     using boost::mpl::_;
1666
1667     typedef parameter::parameters&lt;
1668         required&lt;tag::class_type, boost::is_class&lt;_&gt; &gt;
1669       , parameter::optional&lt;tag::base_list, mpl::is_sequence&lt;_&gt; &gt;
1670       , parameter::optional&lt;tag::held_type&gt;
1671       , parameter::optional&lt;tag::copyable&gt;
1672     &gt; class_signature;
1673 }}
1674 </pre>
1675 <!-- @example.prepend('''
1676 #include <boost/parameter.hpp>
1677 #include <boost/mpl/is_sequence.hpp>
1678 #include <boost/noncopyable.hpp>
1679 #include <boost/type_traits/is_class.hpp>
1680 #include <memory>
1681
1682 using namespace boost::parameter;
1683
1684 namespace boost { namespace python {
1685
1686     BOOST_PARAMETER_TEMPLATE_KEYWORD(class_type)
1687     BOOST_PARAMETER_TEMPLATE_KEYWORD(base_list)
1688     BOOST_PARAMETER_TEMPLATE_KEYWORD(held_type)
1689     BOOST_PARAMETER_TEMPLATE_KEYWORD(copyable)
1690
1691     template <typename B = int>
1692     struct bases
1693     {
1694     };
1695 }}
1696 ''') -->
1697 </div>
1698 <div class="section" id="argument-packs-and-parameter-extraction">
1699 <span id="binding-intro"></span><h4>2.5.1.4&nbsp;&nbsp;&nbsp;Argument Packs and Parameter Extraction</h4>
1700 <p>Next, within the body of <tt class="docutils literal">class_</tt> , we use the <span class="concept">ParameterSpec</span>'s
1701 nested <tt class="docutils literal">::bind&lt; … &gt;</tt> template to bundle the actual arguments into an
1702 <a class="reference external" href="reference.html#argumentpack"><span class="concept">ArgumentPack</span></a> type, and then use the library's <tt class="docutils literal">value_type&lt; … &gt;</tt>
1703 metafunction to extract “logical parameters”.  <tt class="docutils literal">value_type&lt; … &gt;</tt> is
1704 a lot like <tt class="docutils literal">binding&lt; … &gt;</tt>, but no reference is added to the actual
1705 argument type.  Note that defaults are specified by passing it an
1706 optional third argument:</p>
1707 <pre class="literal-block">
1708 namespace boost { namespace python {
1709
1710     template &lt;
1711         typename A0
1712       , typename A1 = boost::parameter::void_
1713       , typename A2 = boost::parameter::void_
1714       , typename A3 = boost::parameter::void_
1715     &gt;
1716     struct class_
1717     {
1718         // Create ArgumentPack
1719         typedef typename class_signature::template bind&lt;
1720             A0, A1, A2, A3
1721         &gt;::type args;
1722
1723         // Extract first logical parameter.
1724         typedef typename parameter::value_type&lt;
1725             args, tag::class_type
1726         &gt;::type class_type;
1727
1728         typedef typename parameter::value_type&lt;
1729             args, tag::base_list, bases&lt;&gt;
1730         &gt;::type base_list;
1731
1732         typedef typename parameter::value_type&lt;
1733             args, tag::held_type, class_type
1734         &gt;::type held_type;
1735
1736         typedef typename parameter::value_type&lt;
1737             args, tag::copyable, void
1738         &gt;::type copyable;
1739     };
1740 }}
1741 </pre>
1742 </div>
1743 </div>
1744 <div class="section" id="exercising-the-code-so-far">
1745 <h3>2.5.2&nbsp;&nbsp;&nbsp;Exercising the Code So Far</h3>
1746 <div class="compound">
1747 <p class="compound-first">Revisiting our original examples,</p>
1748 <pre class="compound-middle literal-block">
1749 typedef boost::python::class_&lt;
1750     class_type&lt;B&gt;, copyable&lt;boost::noncopyable&gt;
1751 &gt; c1;
1752
1753 typedef boost::python::class_&lt;
1754     D
1755   , held_type&lt;std::auto_ptr&lt;D&gt; &gt;
1756   , base_list&lt;bases&lt;B&gt; &gt;
1757 &gt; c2;
1758 </pre>
1759 <!-- @example.prepend('''
1760 using boost::python::class_type;
1761 using boost::python::copyable;
1762 using boost::python::held_type;
1763 using boost::python::base_list;
1764 using boost::python::bases;
1765
1766 struct B
1767 {
1768 };
1769
1770 struct D
1771 {
1772 };
1773 ''') -->
1774 <p class="compound-middle">we can now examine the intended parameters:</p>
1775 <pre class="compound-last literal-block">
1776 BOOST_MPL_ASSERT((boost::is_same&lt;c1::class_type, B&gt;));
1777 BOOST_MPL_ASSERT((boost::is_same&lt;c1::base_list, bases&lt;&gt; &gt;));
1778 BOOST_MPL_ASSERT((boost::is_same&lt;c1::held_type, B&gt;));
1779 BOOST_MPL_ASSERT((
1780     boost::is_same&lt;c1::copyable, boost::noncopyable&gt;
1781 ));
1782
1783 BOOST_MPL_ASSERT((boost::is_same&lt;c2::class_type, D&gt;));
1784 BOOST_MPL_ASSERT((boost::is_same&lt;c2::base_list, bases&lt;B&gt; &gt;));
1785 BOOST_MPL_ASSERT((
1786     boost::is_same&lt;c2::held_type, std::auto_ptr&lt;D&gt; &gt;
1787 ));
1788 BOOST_MPL_ASSERT((boost::is_same&lt;c2::copyable, void&gt;));
1789 </pre>
1790 </div>
1791 <!-- @test('compile', howmany='all') -->
1792 </div>
1793 <div class="section" id="deduced-template-parameters">
1794 <h3>2.5.3&nbsp;&nbsp;&nbsp;Deduced Template Parameters</h3>
1795 <p>To apply a deduced parameter interface here, we need only make the type
1796 requirements a bit tighter so the <tt class="docutils literal">held_type</tt> and <tt class="docutils literal">copyable</tt> parameters
1797 can be crisply distinguished from the others.  <a class="reference external" href="../../../python/doc/index.html">Boost.Python</a> does this by
1798 requiring that <tt class="docutils literal">base_list</tt> be a specialization of its <tt class="docutils literal">bases&lt; … &gt;</tt>
1799 template (as opposed to being any old MPL sequence) and by requiring that
1800 <tt class="docutils literal">copyable</tt>, if explicitly supplied, be <tt class="docutils literal"><span class="pre">boost::noncopyable</span></tt>.  One easy way
1801 of identifying specializations of <tt class="docutils literal">bases&lt; … &gt;</tt> is to derive them all from
1802 the same class, as an implementation detail:</p>
1803 <pre class="literal-block">
1804 namespace boost { namespace python {
1805     namespace detail {
1806
1807         struct bases_base
1808         {
1809         };
1810     }
1811
1812     template &lt;
1813         typename A0 = void, typename A1 = void, typename A2 = void <em>…</em>
1814     &gt;
1815     struct bases <strong>: detail::bases_base</strong>
1816     {
1817     };
1818 }}
1819 </pre>
1820 <!-- @example.replace_emphasis('') -->
1821 <!-- @example.prepend('''
1822 #include <boost/parameter.hpp>
1823 #include <boost/mpl/is_sequence.hpp>
1824 #include <boost/noncopyable.hpp>
1825 #include <memory>
1826
1827 using namespace boost::parameter;
1828 using boost::mpl::_;
1829
1830 namespace boost { namespace python {
1831
1832     BOOST_PARAMETER_TEMPLATE_KEYWORD(class_type)
1833     BOOST_PARAMETER_TEMPLATE_KEYWORD(base_list)
1834     BOOST_PARAMETER_TEMPLATE_KEYWORD(held_type)
1835     BOOST_PARAMETER_TEMPLATE_KEYWORD(copyable)
1836 }}
1837 ''') -->
1838 <p>Now we can rewrite our signature to make all three optional parameters
1839 deducible:</p>
1840 <pre class="literal-block">
1841 typedef parameter::parameters&lt;
1842     required&lt;tag::class_type, is_class&lt;_&gt; &gt;
1843
1844   , parameter::optional&lt;
1845         deduced&lt;tag::base_list&gt;
1846       , is_base_and_derived&lt;detail::bases_base,_&gt;
1847     &gt;
1848
1849   , parameter::optional&lt;
1850         deduced&lt;tag::held_type&gt;
1851       , mpl::not_&lt;
1852             mpl::or_&lt;
1853                 is_base_and_derived&lt;detail::bases_base,_&gt;
1854               , is_same&lt;noncopyable,_&gt;
1855             &gt;
1856         &gt;
1857     &gt;
1858
1859   , parameter::optional&lt;
1860         deduced&lt;tag::copyable&gt;
1861       , is_same&lt;noncopyable,_&gt;
1862     &gt;
1863
1864 &gt; class_signature;
1865 </pre>
1866 <!-- @example.prepend('''
1867 #include <boost/type_traits/is_class.hpp>
1868 namespace boost { namespace python {
1869 ''') -->
1870 <!-- @example.append('''
1871     template <
1872         typename A0
1873       , typename A1 = boost::parameter::void_
1874       , typename A2 = boost::parameter::void_
1875       , typename A3 = boost::parameter::void_
1876     >
1877     struct class_
1878     {
1879         // Create ArgumentPack
1880         typedef typename class_signature::bind<
1881             A0, A1, A2, A3
1882         >::type args;
1883
1884         // Extract first logical parameter.
1885         typedef typename parameter::value_type<
1886             args, tag::class_type
1887         >::type class_type;
1888
1889         typedef typename parameter::value_type<
1890             args, tag::base_list, bases<>
1891         >::type base_list;
1892
1893         typedef typename parameter::value_type<
1894             args, tag::held_type, class_type
1895         >::type held_type;
1896
1897         typedef typename parameter::value_type<
1898             args, tag::copyable, void
1899         >::type copyable;
1900     };
1901 }}
1902 ''') -->
1903 <p>It may seem like we've added a great deal of complexity, but the benefits to
1904 our users are greater.  Our original examples can now be written without
1905 explicit parameter names:</p>
1906 <pre class="literal-block">
1907 typedef boost::python::class_&lt;<strong>B</strong>, <strong>boost::noncopyable</strong>&gt; c1;
1908
1909 typedef boost::python::class_&lt;
1910     <strong>D</strong>, <strong>std::auto_ptr&lt;D&gt;</strong>, <strong>bases&lt;B&gt;</strong>
1911 &gt; c2;
1912 </pre>
1913 <!-- @example.prepend('''
1914 struct B
1915 {
1916 };
1917
1918 struct D
1919 {
1920 };
1921
1922 using boost::python::bases;
1923 ''') -->
1924 <!-- @example.append('''
1925 BOOST_MPL_ASSERT((boost::is_same<c1::class_type, B>));
1926 BOOST_MPL_ASSERT((boost::is_same<c1::base_list, bases<> >));
1927 BOOST_MPL_ASSERT((boost::is_same<c1::held_type, B>));
1928 BOOST_MPL_ASSERT((
1929     boost::is_same<c1::copyable, boost::noncopyable>
1930 ));
1931
1932 BOOST_MPL_ASSERT((boost::is_same<c2::class_type, D>));
1933 BOOST_MPL_ASSERT((boost::is_same<c2::base_list, bases<B> >));
1934 BOOST_MPL_ASSERT((
1935     boost::is_same<c2::held_type, std::auto_ptr<D> >
1936 ));
1937 BOOST_MPL_ASSERT((boost::is_same<c2::copyable, void>));
1938 ''') -->
1939 <!-- @test('compile', howmany='all') -->
1940 </div>
1941 </div>
1942 </div>
1943 <div class="section" id="advanced-topics">
1944 <h1><a class="toc-backref" href="#id32">3&nbsp;&nbsp;&nbsp;Advanced Topics</a></h1>
1945 <p>At this point, you should have a good grasp of the basics.  In this section
1946 we'll cover some more esoteric uses of the library.</p>
1947 <div class="section" id="fine-grained-name-control">
1948 <h2><a class="toc-backref" href="#id33">3.1&nbsp;&nbsp;&nbsp;Fine-Grained Name Control</a></h2>
1949 <p>If you don't like the leading-underscore naming convention used to refer to
1950 keyword objects, or you need the name <tt class="docutils literal">tag</tt> for something other than the
1951 keyword type namespace, there's another way to use <tt class="docutils literal">BOOST_PARAMETER_NAME</tt>:</p>
1952 <pre class="literal-block">
1953 BOOST_PARAMETER_NAME(
1954     <strong>(</strong>
1955         <em>object-name</em>
1956       <strong>,</strong> <em>tag-namespace</em>
1957     <strong>)</strong> <em>parameter-name</em>
1958 )
1959 </pre>
1960 <!-- @ignore() -->
1961 <p>Here is a usage example:</p>
1962 <pre class="literal-block">
1963 BOOST_PARAMETER_NAME(
1964     (
1965         <strong>pass_foo</strong>, <strong>keywords</strong>
1966     ) <strong>foo</strong>
1967 )
1968
1969 BOOST_PARAMETER_FUNCTION(
1970     (int), f,
1971     <strong>keywords</strong>, (required (<strong>foo</strong>, *))
1972 )
1973 {
1974     return <strong>foo</strong> + 1;
1975 }
1976
1977 int x = f(<strong>pass_foo</strong> = 41);
1978 </pre>
1979 <!-- @example.prepend('#include <boost/parameter.hpp>') -->
1980 <!-- @example.append('''
1981 int main()
1982 {
1983     return 0;
1984 }
1985 ''') -->
1986 <!-- @test('run') -->
1987 <p>Before you use this more verbose form, however, please read the section on
1988 <a class="reference internal" href="#keyword-naming">best practices for keyword object naming</a>.</p>
1989 </div>
1990 <div class="section" id="more-argumentpacks">
1991 <h2><a class="toc-backref" href="#id34">3.2&nbsp;&nbsp;&nbsp;More <span class="concept">ArgumentPack</span>s</a></h2>
1992 <p>We've already seen <span class="concept">ArgumentPack</span>s when we looked at
1993 <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
1994 might have guessed, <span class="concept">ArgumentPack</span>s actually lie at the heart of
1995 everything this library does; in this section we'll examine ways to
1996 build and manipulate them more effectively.</p>
1997 <div class="section" id="building-argumentpacks">
1998 <h3>3.2.1&nbsp;&nbsp;&nbsp;Building <span class="concept">ArgumentPack</span>s</h3>
1999 <p>The simplest <span class="concept">ArgumentPack</span> is the result of assigning into a keyword object:</p>
2000 <pre class="literal-block">
2001 BOOST_PARAMETER_NAME(index)
2002
2003 template &lt;typename ArgumentPack&gt;
2004 int print_index(ArgumentPack const&amp; args)
2005 {
2006     std::cout &lt;&lt; &quot;index = &quot; &lt;&lt; args[_index];
2007     std::cout &lt;&lt; std::endl;
2008     return 0;
2009 }
2010
2011 int x = print_index(_index = 3);  // prints &quot;index = 3&quot;
2012 </pre>
2013 <!-- @example.prepend('''
2014 #include <boost/parameter.hpp>
2015 #include <iostream>
2016 ''') -->
2017 <p>Also, <span class="concept">ArgumentPack</span>s can be composed using the comma operator.  The extra
2018 parentheses below are used to prevent the compiler from seeing two separate
2019 arguments to <tt class="docutils literal">print_name_and_index</tt>:</p>
2020 <pre class="literal-block">
2021 BOOST_PARAMETER_NAME(name)
2022
2023 template &lt;typename ArgumentPack&gt;
2024 int print_name_and_index(ArgumentPack const&amp; args)
2025 {
2026     std::cout &lt;&lt; &quot;name = &quot; &lt;&lt; args[_name];
2027     std::cout &lt;&lt; &quot;; &quot;;
2028     return print_index(args);
2029 }
2030
2031 int y = print_name_and_index((_index = 3, _name = &quot;jones&quot;));
2032 </pre>
2033 <p>The <a class="reference external" href="../../test/compose.cpp">compose.cpp</a> test program shows more examples of this feature.</p>
2034 <p>To build an <span class="concept">ArgumentPack</span> with positional arguments, we can use a
2035 <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
2036 Signatures</a>, a <span class="concept">ParameterSpec</span> describes the positional order of parameters
2037 and any associated type requirements.  Just as we can build an <span class="concept">ArgumentPack</span>
2038 <em>type</em> with its nested <tt class="docutils literal">::bind&lt; … &gt;</tt> template, we can build an
2039 <span class="concept">ArgumentPack</span> <em>object</em> by invoking its function call operator:</p>
2040 <pre class="literal-block">
2041 parameter::parameters&lt;
2042     required&lt;tag::name, is_convertible&lt;_,char const*&gt; &gt;
2043   , optional&lt;tag::index, is_convertible&lt;_,int&gt; &gt;
2044 &gt; spec;
2045
2046 char const sam[] = &quot;sam&quot;;
2047 int twelve = 12;
2048
2049 int z0 = print_name_and_index(
2050     <strong>spec(</strong> sam, twelve <strong>)</strong>
2051 );
2052
2053 int z1 = print_name_and_index(
2054     <strong>spec(</strong> _index=12, _name=&quot;sam&quot; <strong>)</strong>
2055 );
2056 </pre>
2057 <!-- @example.prepend('''
2058 namespace parameter = boost::parameter;
2059 using parameter::required;
2060 using parameter::optional;
2061 using boost::is_convertible;
2062 using boost::mpl::_;
2063 ''') -->
2064 <!-- @example.append('''
2065 int main()
2066 {
2067     return 0;
2068 }
2069 ''') -->
2070 <!-- @test('run', howmany='all') -->
2071 </div>
2072 <div class="section" id="extracting-parameter-types">
2073 <h3>3.2.2&nbsp;&nbsp;&nbsp;Extracting Parameter Types</h3>
2074 <p>If we want to know the types of the arguments passed to
2075 <tt class="docutils literal">print_name_and_index</tt>, we have a couple of options.  The
2076 simplest and least error-prone approach is to forward them to a
2077 function template and allow <em>it</em> to do type deduction:</p>
2078 <pre class="literal-block">
2079 BOOST_PARAMETER_NAME(name)
2080 BOOST_PARAMETER_NAME(index)
2081
2082 template &lt;typename Name, typename Index&gt;
2083 int deduce_arg_types_impl(Name&amp;&amp; name, Index&amp;&amp; index)
2084 {
2085     // we know the types
2086     Name&amp;&amp; n2 = boost::forward&lt;Name&gt;(name);
2087     Index&amp;&amp; i2 = boost::forward&lt;Index&gt;(index);
2088     return index;
2089 }
2090
2091 template &lt;typename ArgumentPack&gt;
2092 int deduce_arg_types(ArgumentPack const&amp; args)
2093 {
2094     return deduce_arg_types_impl(args[_name], args[_index | 42]);
2095 }
2096 </pre>
2097 <!-- @example.prepend('''
2098 #include <boost/parameter.hpp>
2099 ''') -->
2100 <!-- @example.append('''
2101 #include <boost/core/lightweight_test.hpp>
2102
2103 int main()
2104 {
2105     int a1 = deduce_arg_types((_name = "foo"));
2106     int a2 = deduce_arg_types((_name = "foo", _index = 3));
2107     BOOST_TEST_EQ(a1, 42);
2108     BOOST_TEST_EQ(a2, 3);
2109     return boost::report_errors();
2110 }
2111 ''') -->
2112 <!-- @test('run') -->
2113 <p>Occasionally one needs to deduce argument types without an extra layer of
2114 function call.  For example, suppose we wanted to return twice the value of
2115 the <tt class="docutils literal">index</tt> parameter?  In that case we can use the <tt class="docutils literal">value_type&lt; … &gt;</tt>
2116 metafunction introduced <a class="reference internal" href="#binding-intro">earlier</a>:</p>
2117 <pre class="literal-block">
2118 BOOST_PARAMETER_NAME(index)
2119
2120 template &lt;typename ArgumentPack&gt;
2121 typename boost::parameter::value_type&lt;ArgumentPack,tag::index,int&gt;::type
2122     twice_index(ArgumentPack const&amp; args)
2123 {
2124     return 2 * args[_index | 42];
2125 }
2126 </pre>
2127 <!-- @example.prepend('''
2128 #include <boost/parameter.hpp>
2129 ''') -->
2130 <!-- @example.append('''
2131 #include <boost/core/lightweight_test.hpp>
2132
2133 int main()
2134 {
2135     int six = twice_index(_index = 3);
2136     BOOST_TEST_EQ(six, 6);
2137     return boost::report_errors();
2138 }
2139 ''') -->
2140 <!-- @test('run', howmany='all') -->
2141 <p>Note that if we had used <tt class="docutils literal">binding&lt; … &gt;</tt> rather than <tt class="docutils literal">value_type&lt; … &gt;</tt>, we
2142 would end up returning a reference to the temporary created in the <tt class="docutils literal">2 * …</tt>
2143 expression.</p>
2144 </div>
2145 <div class="section" id="lazy-default-computation">
2146 <h3>3.2.3&nbsp;&nbsp;&nbsp;Lazy Default Computation</h3>
2147 <p>When a default value is expensive to compute, it would be preferable to avoid
2148 it until we're sure it's absolutely necessary.  <tt class="docutils literal">BOOST_PARAMETER_FUNCTION</tt>
2149 takes care of that problem for us, but when using <span class="concept">ArgumentPack</span>s
2150 explicitly, we need a tool other than <tt class="docutils literal">operator|</tt>:</p>
2151 <pre class="literal-block">
2152 BOOST_PARAMETER_NAME(s1)
2153 BOOST_PARAMETER_NAME(s2)
2154 BOOST_PARAMETER_NAME(s3)
2155
2156 template &lt;typename ArgumentPack&gt;
2157 std::string f(ArgumentPack const&amp; args)
2158 {
2159     std::string const&amp; s1 = args[_s1];
2160     std::string const&amp; s2 = args[_s2];
2161     typename parameter::binding&lt;
2162         ArgumentPack,tag::s3,std::string
2163     &gt;::type s3 = args[_s3 | (s1 + s2)];  // always constructs s1 + s2
2164     return s3;
2165 }
2166
2167 std::string x = f((
2168     _s1=&quot;hello,&quot;, _s2=&quot; world&quot;, _s3=&quot;hi world&quot;
2169 ));
2170 </pre>
2171 <!-- @example.prepend('''
2172 #include <boost/parameter.hpp>
2173 #include <string>
2174
2175 namespace parameter = boost::parameter;
2176 ''') -->
2177 <!-- @example.append('''
2178 int main()
2179 {
2180     return 0;
2181 }
2182 ''') -->
2183 <!-- @test('run') -->
2184 <p>In the example above, the string <tt class="docutils literal">&quot;hello, world&quot;</tt> is constructed despite the
2185 fact that the user passed us a value for <tt class="docutils literal">s3</tt>.  To remedy that, we can
2186 compute the default value <em>lazily</em> (that is, only on demand), by using
2187 <tt class="docutils literal"><span class="pre">boost::bind()</span></tt> to create a function object.</p>
2188 <!-- danielw: I'm leaving the text below in the source, because we might -->
2189 <!-- want to change back to it after 1.34, and if I remove it now we -->
2190 <!-- might forget about it. -->
2191 <!-- by combining the logical-or (“``||``”) operator -->
2192 <!-- with a function object built by the Boost Lambda_ library: [#bind]_ -->
2193 <pre class="literal-block">
2194 typename parameter::binding&lt;
2195     ArgumentPack,tag::s3,std::string
2196 &gt;::type s3 = args[
2197     _s3 <strong>|| boost::bind(
2198         std::plus&lt;std::string&gt;(), boost::ref(s1), boost::ref(s2)
2199     )</strong>
2200 ];
2201 </pre>
2202 <!-- @example.prepend('''
2203 #include <boost/bind.hpp>
2204 #include <boost/ref.hpp>
2205 #include <boost/parameter.hpp>
2206 #include <string>
2207 #include <functional>
2208
2209 namespace parameter = boost::parameter;
2210
2211 BOOST_PARAMETER_NAME(s1)
2212 BOOST_PARAMETER_NAME(s2)
2213 BOOST_PARAMETER_NAME(s3)
2214
2215 template <typename ArgumentPack>
2216 std::string f(ArgumentPack const& args)
2217 {
2218     std::string const& s1 = args[_s1];
2219     std::string const& s2 = args[_s2];
2220 ''') -->
2221 <!-- @example.append('''
2222     return s3;
2223 }
2224
2225 std::string x = f((_s1="hello,", _s2=" world", _s3="hi world"));
2226
2227 int main()
2228 {
2229     return 0;
2230 }
2231 ''') -->
2232 <!-- @test('run') -->
2233 <!-- .. _Lambda: ../../../lambda/index.html -->
2234 <div class="sidebar">
2235 <p class="first sidebar-title">Mnemonics</p>
2236 <p class="last">To remember the difference between <tt class="docutils literal">|</tt> and <tt class="docutils literal">||</tt>, recall that <tt class="docutils literal">||</tt>
2237 normally uses short-circuit evaluation: its second argument is only
2238 evaluated if its first argument is <tt class="docutils literal">false</tt>.  Similarly, in
2239 <tt class="docutils literal">color_map[param || f]</tt>, <tt class="docutils literal">f</tt> is only invoked if no <tt class="docutils literal">color_map</tt>
2240 argument was supplied.</p>
2241 </div>
2242 <p>The expression <tt class="docutils literal"><span class="pre">bind(std::plus&lt;std::string&gt;(),</span> ref(s1), ref(s2))</tt> yields a
2243 <em>function object</em> that, when invoked, adds the two strings together.  That
2244 function will only be invoked if no <tt class="docutils literal">s3</tt> argument is supplied by the caller.</p>
2245 <!-- The expression ``lambda::var(s1) + lambda::var(s2)`` yields a -->
2246 <!-- *function object* that, when invoked, adds the two strings -->
2247 <!-- together.  That function will only be invoked if no ``s3`` argument -->
2248 <!-- is supplied by the caller. -->
2249 </div>
2250 </div>
2251 </div>
2252 <div class="section" id="best-practices">
2253 <h1><a class="toc-backref" href="#id35">4&nbsp;&nbsp;&nbsp;Best Practices</a></h1>
2254 <p>By now you should have a fairly good idea of how to use the Parameter
2255 library.  This section points out a few more-marginal issues that will help
2256 you use the library more effectively.</p>
2257 <div class="section" id="keyword-naming">
2258 <h2><a class="toc-backref" href="#id36">4.1&nbsp;&nbsp;&nbsp;Keyword Naming</a></h2>
2259 <p><tt class="docutils literal">BOOST_PARAMETER_NAME</tt> prepends a leading underscore to the names of all our
2260 keyword objects in order to avoid the following usually-silent bug:</p>
2261 <pre class="literal-block">
2262 namespace people
2263 {
2264     namespace tag
2265     {
2266         struct name
2267         {
2268             typedef boost::parameter::forward_reference qualifier;
2269         };
2270
2271         struct age
2272         {
2273             typedef boost::parameter::forward_reference qualifier;
2274         };
2275     }
2276
2277     namespace // unnamed
2278     {
2279         boost::parameter::keyword&lt;tag::name&gt;&amp; <strong>name</strong>
2280             = boost::parameter::keyword&lt;tag::name&gt;::instance;
2281         boost::parameter::keyword&lt;tag::age&gt;&amp; <strong>age</strong>
2282             = boost::parameter::keyword&lt;tag::age&gt;::instance;
2283     }
2284
2285     BOOST_PARAMETER_FUNCTION(
2286         (void), g, tag, (optional (name, *, &quot;bob&quot;)(age, *, 42))
2287     )
2288     {
2289         std::cout &lt;&lt; name &lt;&lt; &quot;:&quot; &lt;&lt; age;
2290     }
2291
2292     void f(int age)
2293     {
2294         <span class="vellipsis">        .
2295         .
2296         .
2297         </span>
2298         g(<strong>age</strong> = 3);  // whoops!
2299     }
2300 }
2301 </pre>
2302 <!-- @ignore() -->
2303 <p>Although in the case above, the user was trying to pass the value <tt class="docutils literal">3</tt> as the
2304 <tt class="docutils literal">age</tt> parameter to <tt class="docutils literal">g</tt>, what happened instead was that <tt class="docutils literal">f</tt>'s <tt class="docutils literal">age</tt>
2305 argument got reassigned the value 3, and was then passed as a positional
2306 argument to <tt class="docutils literal">g</tt>.  Since <tt class="docutils literal">g</tt>'s first positional parameter is <tt class="docutils literal">name</tt>, the
2307 default value for <tt class="docutils literal">age</tt> is used, and g prints <tt class="docutils literal">3:42</tt>.  Our leading
2308 underscore naming convention makes this problem less likely to occur.</p>
2309 <p>In this particular case, the problem could have been detected if f's <tt class="docutils literal">age</tt>
2310 parameter had been made <tt class="docutils literal">const</tt>, which is always a good idea whenever
2311 possible.  Finally, we recommend that you use an enclosing namespace for all
2312 your code, but particularly for names with leading underscores.  If we were to
2313 leave out the <tt class="docutils literal">people</tt> namespace above, names in the global namespace
2314 beginning with leading underscores—which are reserved to your C++
2315 compiler—might become irretrievably ambiguous with those in our
2316 unnamed namespace.</p>
2317 </div>
2318 <div class="section" id="namespaces">
2319 <h2><a class="toc-backref" href="#id37">4.2&nbsp;&nbsp;&nbsp;Namespaces</a></h2>
2320 <p>In our examples we've always declared keyword objects in (an unnamed namespace
2321 within) the same namespace as the Boost.Parameter-enabled functions using
2322 those keywords:</p>
2323 <pre class="literal-block">
2324 namespace lib {
2325
2326     <strong>BOOST_PARAMETER_NAME(name)
2327     BOOST_PARAMETER_NAME(index)</strong>
2328
2329     BOOST_PARAMETER_FUNCTION(
2330         (int), f, tag,
2331         (optional (name,*,&quot;bob&quot;)(index,(int),1))
2332     )
2333     {
2334         std::cout &lt;&lt; name &lt;&lt; &quot;:&quot; &lt;&lt; index;
2335         std::cout &lt;&lt; std::endl;
2336         return index;
2337     }
2338 }
2339 </pre>
2340 <!-- @example.prepend('''
2341 #include <boost/parameter.hpp>
2342 #include <iostream>
2343 ''') -->
2344 <!-- @namespace_setup = str(example) -->
2345 <!-- @ignore() -->
2346 <p>Users of these functions have a few choices:</p>
2347 <ol class="arabic">
2348 <li><p class="first">Full qualification:</p>
2349 <pre class="literal-block">
2350 int x = <strong>lib::</strong>f(
2351     <strong>lib::</strong>_name = &quot;jill&quot;
2352   , <strong>lib::</strong>_index = 1
2353 );
2354 </pre>
2355 <p>This approach is more verbose than many users would like.</p>
2356 </li>
2357 </ol>
2358 <!-- @example.prepend(namespace_setup) -->
2359 <!-- @example.append('int main() { return 0; }') -->
2360 <!-- @test('run') -->
2361 <ol class="arabic" start="2">
2362 <li><p class="first">Make keyword objects available through <em>using-declarations</em>:</p>
2363 <pre class="literal-block">
2364 <strong>using lib::_name;
2365 using lib::_index;</strong>
2366
2367 int x = lib::f(_name = &quot;jill&quot;, _index = 1);
2368 </pre>
2369 <p>This version is much better at the actual call site, but the
2370 <em>using-declarations</em> themselves can be verbose and hard to manage.</p>
2371 </li>
2372 </ol>
2373 <!-- @example.prepend(namespace_setup) -->
2374 <!-- @example.append('int main() { return 0; }') -->
2375 <!-- @test('run') -->
2376 <ol class="arabic" start="3">
2377 <li><p class="first">Bring in the entire namespace with a <em>using-directive</em>:</p>
2378 <pre class="literal-block">
2379 <strong>using namespace lib;</strong>
2380 int x = <strong>f</strong>(_name = &quot;jill&quot;, _index = 3);
2381 </pre>
2382 <p>This option is convenient, but it indiscriminately makes the <em>entire</em>
2383 contents of <tt class="docutils literal">lib</tt> available without qualification.</p>
2384 </li>
2385 </ol>
2386 <!-- @example.prepend(namespace_setup) -->
2387 <!-- @example.append('int main() { return 0; }') -->
2388 <!-- @test('run') -->
2389 <p>If we add an additional namespace around keyword declarations, though, we can
2390 give users more control:</p>
2391 <pre class="literal-block">
2392 namespace lib {
2393     <strong>namespace keywords {</strong>
2394
2395         BOOST_PARAMETER_NAME(name)
2396         BOOST_PARAMETER_NAME(index)
2397     <strong>}</strong>
2398
2399     BOOST_PARAMETER_FUNCTION(
2400         (int), f, <strong>keywords::</strong>tag,
2401         (optional (name,*,&quot;bob&quot;)(index,(int),1))
2402     )
2403     {
2404         std::cout &lt;&lt; name &lt;&lt; &quot;:&quot; &lt;&lt; index;
2405         std::cout &lt;&lt; std::endl;
2406         return index;
2407     }
2408 }
2409 </pre>
2410 <!-- @example.prepend('''
2411 #include <boost/parameter.hpp>
2412 #include <iostream>
2413 ''') -->
2414 <p>Now users need only a single <em>using-directive</em> to bring in just the names of
2415 all keywords associated with <tt class="docutils literal">lib</tt>:</p>
2416 <pre class="literal-block">
2417 <strong>using namespace lib::keywords;</strong>
2418 int y = lib::f(_name = &quot;bob&quot;, _index = 2);
2419 </pre>
2420 <!-- @example.append('int main() { return 0; }') -->
2421 <!-- @test('run', howmany='all') -->
2422 </div>
2423 <div class="section" id="documentation">
2424 <h2><a class="toc-backref" href="#id38">4.3&nbsp;&nbsp;&nbsp;Documentation</a></h2>
2425 <p>The interface idioms enabled by Boost.Parameter are completely new (to C++),
2426 and as such are not served by pre-existing documentation conventions.</p>
2427 <div class="note">
2428 <p class="first admonition-title">Note</p>
2429 <p class="last">This space is empty because we haven't settled on any best practices
2430 yet.  We'd be very pleased to link to your documentation if you've got a
2431 style that you think is worth sharing.</p>
2432 </div>
2433 </div>
2434 </div>
2435 <div class="section" id="portability-considerations">
2436 <h1><a class="toc-backref" href="#id39">5&nbsp;&nbsp;&nbsp;Portability Considerations</a></h1>
2437 <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
2438 the Parameter library to see how it fares on your favorite
2439 compiler.  Additionally, you may need to be aware of the following
2440 issues and workarounds for particular compilers.</p>
2441 <div class="section" id="perfect-forwarding-support">
2442 <h2><a class="toc-backref" href="#id40">5.1&nbsp;&nbsp;&nbsp;Perfect Forwarding Support</a></h2>
2443 <p>If your compiler supports <a class="reference external" href="http://www.justsoftwaresolutions.co.uk/cplusplus/rvalue_references_and_perfect_forwarding.html">perfect forwarding</a>, then the Parameter library
2444 will <tt class="docutils literal">#define</tt> the macro <tt class="docutils literal">BOOST_PARAMETER_HAS_PERFECT_FORWARDING</tt> unless
2445 you disable it manually.  If your compiler does not provide this support, then
2446 <tt class="docutils literal"><span class="pre">parameter::parameters::operator()</span></tt> will treat rvalue references as lvalue
2447 <tt class="docutils literal">const</tt> references to work around the <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2002/n1385.htm">forwarding problem</a>, so in certain
2448 cases you must wrap <a class="reference external" href="../../../core/doc/html/core/ref.html"><tt class="docutils literal"><span class="pre">boost::ref</span></tt></a> or <a class="reference external" href="http://en.cppreference.com/w/cpp/utility/functional/ref"><tt class="docutils literal"><span class="pre">std::ref</span></tt></a> around any arguments that will
2449 be bound to out parameters.  The <a class="reference external" href="../../test/evaluate_category.cpp">evaluate_category.cpp</a> and
2450 <a class="reference external" href="../../test/preprocessor_eval_category.cpp">preprocessor_eval_category.cpp</a> test programs demonstrate this support.</p>
2451 </div>
2452 <div class="section" id="boost-mp11-support">
2453 <h2><a class="toc-backref" href="#id41">5.2&nbsp;&nbsp;&nbsp;Boost.MP11 Support</a></h2>
2454 <p>If your compiler is sufficiently compliant with the C++11 standard, then the
2455 Parameter library will <tt class="docutils literal">#define</tt> the macro <tt class="docutils literal">BOOST_PARAMETER_CAN_USE_MP11</tt>
2456 unless you disable it manually.  The <a class="reference external" href="../../test/singular.cpp">singular.cpp</a>, <a class="reference external" href="../../test/compose.cpp">compose.cpp</a>,
2457 <a class="reference external" href="../../test/optional_deduced_sfinae.cpp">optional_deduced_sfinae.cpp</a>, and <a class="reference external" href="../../test/deduced_dependent_predicate.cpp">deduced_dependent_predicate.cpp</a> test programs
2458 demonstrate support for <a class="reference external" href="../../../mp11/doc/html/mp11.html">Boost.MP11</a>.</p>
2459 </div>
2460 <div class="section" id="no-sfinae-support">
2461 <h2><a class="toc-backref" href="#id42">5.3&nbsp;&nbsp;&nbsp;No SFINAE Support</a></h2>
2462 <p>Some older compilers don't support SFINAE.  If your compiler meets that
2463 criterion, then Boost headers will <tt class="docutils literal">#define</tt> the preprocessor symbol
2464 <tt class="docutils literal">BOOST_NO_SFINAE</tt>, and parameter-enabled functions won't be removed
2465 from the overload set based on their signatures.  The <a class="reference external" href="../../test/sfinae.cpp">sfinae.cpp</a> and
2466 <a class="reference external" href="../../test/optional_deduced_sfinae.cpp">optional_deduced_sfinae.cpp</a> test programs demonstrate SFINAE support.</p>
2467 </div>
2468 <div class="section" id="no-support-for-result-of">
2469 <h2>5.4&nbsp;&nbsp;&nbsp;No Support for <a class="reference external" href="../../../utility/utility.htm#result_of"><tt class="docutils literal">result_of</tt></a></h2>
2470 <p><a class="reference internal" href="#lazy-default-computation">Lazy default computation</a> relies on the <tt class="docutils literal">result_of</tt> class template to
2471 compute the types of default arguments given the type of the function object
2472 that constructs them.  On compilers that don't support <tt class="docutils literal">result_of</tt>,
2473 <tt class="docutils literal">BOOST_NO_RESULT_OF</tt> will be <tt class="docutils literal">#define</tt>d, and the compiler will expect
2474 the function object to contain a nested type name, <tt class="docutils literal">result_type</tt>, that
2475 indicates its return type when invoked without arguments.  To use an ordinary
2476 function as a default generator on those compilers, you'll need to wrap it in
2477 a class that provides <tt class="docutils literal">result_type</tt> as a <tt class="docutils literal">typedef</tt> and invokes the
2478 function via its <tt class="docutils literal">operator()</tt>.</p>
2479 <!-- Can't Declare |ParameterSpec| via ``typedef``
2480 =============================================
2481
2482 In principle you can declare a |ParameterSpec| as a ``typedef`` for a
2483 specialization of ``parameters<…>``, but Microsoft Visual C++ 6.x has been
2484 seen to choke on that usage.  The workaround is to use inheritance and
2485 declare your |ParameterSpec| as a class:
2486
2487 .. parsed-literal::
2488
2489     **struct dfs_parameters
2490       :** parameter::parameters<
2491             tag::graph, tag::visitor, tag::root_vertex
2492           , tag::index_map, tag::color_map
2493         >
2494     **{
2495     };**
2496
2497 Default Arguments Unsupported on Nested Templates
2498 =============================================
2499
2500 As of this writing, Borland compilers don't support the use of default
2501 template arguments on member class templates.  As a result, you have to
2502 supply ``BOOST_PARAMETER_MAX_ARITY`` arguments to every use of
2503 ``parameters<…>::match``.  Since the actual defaults used are unspecified,
2504 the workaround is to use |BOOST_PARAMETER_MATCH|_ to declare default
2505 arguments for SFINAE.
2506
2507 .. |BOOST_PARAMETER_MATCH| replace:: ``BOOST_PARAMETER_MATCH`` -->
2508 </div>
2509 <div class="section" id="compiler-can-t-see-references-in-unnamed-namespace">
2510 <h2><a class="toc-backref" href="#id44">5.5&nbsp;&nbsp;&nbsp;Compiler Can't See References In Unnamed Namespace</a></h2>
2511 <p>If you use Microsoft Visual C++ 6.x, you may find that the compiler has
2512 trouble finding your keyword objects.  This problem has been observed, but
2513 only on this one compiler, and it disappeared as the test code evolved, so
2514 we suggest you use it only as a last resort rather than as a preventative
2515 measure.  The solution is to add <em>using-declarations</em> to force the names
2516 to be available in the enclosing namespace without qualification:</p>
2517 <pre class="literal-block">
2518 namespace graphs {
2519
2520     using graphs::graph;
2521     using graphs::visitor;
2522     using graphs::root_vertex;
2523     using graphs::index_map;
2524     using graphs::color_map;
2525 }
2526 </pre>
2527 </div>
2528 </div>
2529 <div class="section" id="python-binding">
2530 <h1><a class="toc-backref" href="#id45">6&nbsp;&nbsp;&nbsp;Python Binding</a></h1>
2531 <p>Follow <a class="reference external" href="../../../parameter_python/doc/html/index.html">this link</a> for documentation on how to expose
2532 Boost.Parameter-enabled functions to Python with <a class="reference external" href="../../../python/doc/index.html">Boost.Python</a>.</p>
2533 </div>
2534 <div class="section" id="reference">
2535 <h1><a class="toc-backref" href="#id46">7&nbsp;&nbsp;&nbsp;Reference</a></h1>
2536 <p>Follow <a class="reference external" href="reference.html">this link</a> to the Boost.Parameter reference documentation.</p>
2537 </div>
2538 <div class="section" id="glossary">
2539 <h1><a class="toc-backref" href="#id47">8&nbsp;&nbsp;&nbsp;Glossary</a></h1>
2540 <div class="section" id="argument-or-actual-argument">
2541 <span id="arguments"></span><h2><a class="toc-backref" href="#id48">8.1&nbsp;&nbsp;&nbsp;Argument (or “actual argument”)</a></h2>
2542 <p>the value actually passed to a function or class template.</p>
2543 </div>
2544 <div class="section" id="parameter-or-formal-parameter">
2545 <span id="parameter"></span><h2><a class="toc-backref" href="#id49">8.2&nbsp;&nbsp;&nbsp;Parameter (or “formal parameter”)</a></h2>
2546 <p>the name used to refer to an argument within a function or class
2547 template.  For example, the value of <tt class="docutils literal">f</tt>'s <em>parameter</em> <tt class="docutils literal">x</tt> is given by the
2548 <em>argument</em> <tt class="docutils literal">3</tt>:</p>
2549 <pre class="literal-block">
2550 int f(int x) { return x + 1; }
2551 int y = f(3);
2552 </pre>
2553 </div>
2554 </div>
2555 <div class="section" id="acknowledgements">
2556 <h1><a class="toc-backref" href="#id50">9&nbsp;&nbsp;&nbsp;Acknowledgements</a></h1>
2557 <p>The authors would like to thank all the Boosters who participated in the
2558 review of this library and its documentation, most especially our review
2559 manager, Doug Gregor.</p>
2560 <hr class="docutils" />
2561 <table class="docutils footnote" frame="void" id="old-interface" rules="none">
2562 <colgroup><col class="label" /><col /></colgroup>
2563 <tbody valign="top">
2564 <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
2565 <a class="reference external" href="../../../graph/doc/bgl_named_params.html">older named parameter mechanism</a>, but there are plans to change it to
2566 use Boost.Parameter (this library) in an upcoming release, while keeping
2567 the old interface available for backward-compatibility.</td></tr>
2568 </tbody>
2569 </table>
2570 <table class="docutils footnote" frame="void" id="odr" rules="none">
2571 <colgroup><col class="label" /><col /></colgroup>
2572 <tbody valign="top">
2573 <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++
2574 program must have the same definition in all translation units (object
2575 files) that make up a program.</td></tr>
2576 </tbody>
2577 </table>
2578 <table class="docutils footnote" frame="void" id="vertex-descriptor" rules="none">
2579 <colgroup><col class="label" /><col /></colgroup>
2580 <tbody valign="top">
2581 <tr><td class="label">[3]</td><td>If you're not familiar with the Boost Graph Library,
2582 don't worry about the meaning of any Graph-library-specific details you
2583 encounter.  In this case you could replace all mentions of vertex
2584 descriptor types with <tt class="docutils literal">int</tt> in the text, and your understanding of the
2585 Parameter library wouldn't suffer.</td></tr>
2586 </tbody>
2587 </table>
2588 <table class="docutils footnote" frame="void" id="conceptsts" rules="none">
2589 <colgroup><col class="label" /><col /></colgroup>
2590 <tbody valign="top">
2591 <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://en.cppreference.com/w/cpp/language/constraints">C++20 constraints</a>.</td></tr>
2592 </tbody>
2593 </table>
2594 <!-- .. [#bind] The Lambda library is known not to work on `some -->
2595 <!-- less-conformant compilers`__.  When using one of those you could -->
2596 <!-- use `Boost.Bind`_ to generate the function object\:\: -->
2597 <!-- boost\:\:bind(std\:\:plus<std\:\:string>(),s1,s2) -->
2598 <table class="docutils footnote" frame="void" id="is-keyword-expression" rules="none">
2599 <colgroup><col class="label" /><col /></colgroup>
2600 <tbody valign="top">
2601 <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
2602 metafunction <tt class="docutils literal">is_keyword_expression</tt> that can be used to identify
2603 models of Boost.Python's KeywordExpression concept.</td></tr>
2604 </tbody>
2605 </table>
2606 <!-- .. __ http://www.boost.org/regression/release/user/lambda.html -->
2607 <table class="docutils footnote" frame="void" id="using" rules="none">
2608 <colgroup><col class="label" /><col /></colgroup>
2609 <tbody valign="top">
2610 <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
2611 lives in an outer namespace by applying a <em>using-declaration</em>:</p>
2612 <pre class="literal-block">
2613 namespace foo_overloads {
2614
2615     // foo declarations here
2616     void foo() { ... }
2617     ...
2618 }
2619 using foo_overloads::foo;
2620 </pre>
2621 <p class="last">This technique for avoiding unintentional argument-dependent lookup is due
2622 to Herb Sutter.</p>
2623 </td></tr>
2624 </tbody>
2625 </table>
2626 <table class="docutils footnote" frame="void" id="sfinae" rules="none">
2627 <colgroup><col class="label" /><col /></colgroup>
2628 <tbody valign="top">
2629 <tr><td class="label">[7]</td><td>This capability depends on your compiler's support for
2630 SFINAE.  <strong>SFINAE</strong>: <strong>S</strong>ubstitution <strong>F</strong>ailure <strong>I</strong>s <strong>N</strong>ot
2631 <strong>A</strong>n <strong>E</strong>rror.  If type substitution during the instantiation of a
2632 function template results in an invalid type, no compilation error is
2633 emitted; instead the overload is removed from the overload set.  By
2634 producing an invalid type in the function signature depending on the
2635 result of some condition, we can decide whether or not an overload is
2636 considered during overload resolution.  The technique is formalized in the
2637 <a class="reference external" href="../../../core/doc/html/core/enable_if.html"><tt class="docutils literal">enable_if</tt></a> utility.  Most recent compilers support SFINAE; on compilers
2638 that don't support it, the Boost config library will <tt class="docutils literal">#define</tt> the
2639 symbol <tt class="docutils literal">BOOST_NO_SFINAE</tt>.  See
2640 <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
2641 on SFINAE.</td></tr>
2642 </tbody>
2643 </table>
2644 </div>
2645 </div>
2646 <div class="footer">
2647 <hr class="footer" />
2648 Generated on: 2019-12-10 00:22 UTC.
2649 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.
2650
2651 </div>
2652 </body>
2653 </html>