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 21accept arguments by name:</td> 22</tr> 23</tbody> 24</table> 25<pre class="literal-block"> 26new_window( 27 "alert" 28 , <strong>_width=10</strong> 29 , <strong>_titlebar=false</strong> 30); 31 32smart_ptr< 33 Foo 34 , <strong>deleter<Deallocate<Foo> ></strong> 35 , <strong>copy_policy<DeepCopy></strong> 36> p(new Foo); 37</pre> 38<p>Since named arguments can be passed in any order, they are especially useful 39when a function or template has more than one parameter with a useful default 40value. The library also supports <em>deduced</em> parameters: that is to say, 41parameters whose identity can be deduced from their types.</p> 42<!-- @jam_prefix.append(''' 43project test 44 : requirements <include>. <implicit-dependency>/boost//headers ; 45''') --> 46<!-- @example.prepend(''' 47#include <boost/parameter.hpp> 48 49namespace 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} 86using namespace test; 87int 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@boost-consulting.com">dave@boost-consulting.com</a>, <a class="reference external" href="mailto:daniel@boostpro.com">daniel@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 1042005-2009. Distributed under the Boost Software License, 105Version 1.0. (See accompanying file LICENSE_1_0.txt 106or 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 112also 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 Motivation</a><ul class="auto-toc"> 117<li><a class="reference internal" href="#named-function-parameters" id="id23">1.1 Named Function Parameters</a></li> 118<li><a class="reference internal" href="#deduced-function-parameters" id="id24">1.2 Deduced Function Parameters</a></li> 119<li><a class="reference internal" href="#class-template-parameter-support" id="id25">1.3 Class Template Parameter Support</a></li> 120</ul> 121</li> 122<li><a class="reference internal" href="#tutorial" id="id26">2 Tutorial</a><ul class="auto-toc"> 123<li><a class="reference internal" href="#parameter-enabled-functions" id="id27">2.1 Parameter-Enabled Functions</a></li> 124<li><a class="reference internal" href="#parameter-enabled-member-functions" id="id28">2.2 Parameter-Enabled Member Functions</a></li> 125<li><a class="reference internal" href="#parameter-enabled-function-call-operators" id="id29">2.3 Parameter-Enabled Function Call Operators</a></li> 126<li><a class="reference internal" href="#parameter-enabled-constructors" id="id30">2.4 Parameter-Enabled Constructors</a></li> 127<li><a class="reference internal" href="#parameter-enabled-class-templates" id="id31">2.5 Parameter-Enabled Class Templates</a></li> 128</ul> 129</li> 130<li><a class="reference internal" href="#advanced-topics" id="id32">3 Advanced Topics</a><ul class="auto-toc"> 131<li><a class="reference internal" href="#fine-grained-name-control" id="id33">3.1 Fine-Grained Name Control</a></li> 132<li><a class="reference internal" href="#more-argumentpacks" id="id34">3.2 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 Best Practices</a><ul class="auto-toc"> 136<li><a class="reference internal" href="#keyword-naming" id="id36">4.1 Keyword Naming</a></li> 137<li><a class="reference internal" href="#namespaces" id="id37">4.2 Namespaces</a></li> 138<li><a class="reference internal" href="#documentation" id="id38">4.3 Documentation</a></li> 139</ul> 140</li> 141<li><a class="reference internal" href="#portability-considerations" id="id39">5 Portability Considerations</a><ul class="auto-toc"> 142<li><a class="reference internal" href="#perfect-forwarding-support" id="id40">5.1 Perfect Forwarding Support</a></li> 143<li><a class="reference internal" href="#boost-mp11-support" id="id41">5.2 Boost.MP11 Support</a></li> 144<li><a class="reference internal" href="#no-sfinae-support" id="id42">5.3 No SFINAE Support</a></li> 145<li><a class="reference internal" href="#no-support-for-result-of" id="id43">5.4 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 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 Python Binding</a></li> 150<li><a class="reference internal" href="#reference" id="id46">7 Reference</a></li> 151<li><a class="reference internal" href="#glossary" id="id47">8 Glossary</a><ul class="auto-toc"> 152<li><a class="reference internal" href="#argument-or-actual-argument" id="id48">8.1 Argument (or “actual argument”)</a></li> 153<li><a class="reference internal" href="#parameter-or-formal-parameter" id="id49">8.2 Parameter (or “formal parameter”)</a></li> 154</ul> 155</li> 156<li><a class="reference internal" href="#acknowledgements" id="id50">9 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 Motivation</a></h1> 162<p>In C++, <a class="reference internal" href="#arguments">arguments</a> are normally given meaning by their positions with respect 163to a <a class="reference internal" href="#parameter">parameter</a> list: the first argument passed maps onto the first parameter 164in a function's definition, and so on. That protocol is fine when there is at 165most one parameter with a default value, but when there are even a few useful 166defaults, 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 171combinations of defaults unusable:</p> 172<pre class="compound-middle literal-block"> 173window* 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 180bool const movability = false; 181window* w = new_window("alert box", 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"> 187window* w = new_window( 188 "alert box", <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 195at the call site:</p> 196<pre class="compound-middle literal-block"> 197window* w = new_window("alert", 1, true, false); 198</pre> 199<p class="compound-last">Is this window moveable and initially invisible, or unmoveable and 200initially visible? The reader needs to remember the order of arguments to 201be 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, 205leading 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 Named Function Parameters</a></h2> 211<div class="compound"> 212<p class="compound-first">This library addresses the problems outlined above by associating each 213parameter name with a keyword object. Now users can identify arguments by 214name, rather than by position:</p> 215<pre class="compound-last literal-block"> 216window* w = new_window( 217 "alert box" 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 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 228an explicit parameter name. It's not uncommon for a function to have 229parameters that can be uniquely identified based on the types of arguments 230passed. The <tt class="docutils literal">name</tt> parameter to <tt class="docutils literal">new_window</tt> is one such 231example. None of the other arguments, if valid, can reasonably be 232converted to a <tt class="docutils literal">char const*</tt>. With a deduced parameter interface, we 233could pass the window name in <em>any</em> argument position without causing 234ambiguity:</p> 235<pre class="compound-middle literal-block"> 236window* w = new_window( 237 movable_=false 238 , <strong>"alert box"</strong> 239); // OK! 240window* w = new_window( 241 <strong>"alert box"</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 246burden 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 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 254applies equally well to class templates as it does to functions. Using 255the Parameter library, we can create interfaces that allow template 256arguments (in this case <tt class="docutils literal">shared</tt> and <tt class="docutils literal">Client</tt>) to be explicitly named, 257like this:</p> 258<pre class="compound-middle literal-block"> 259smart_ptr< 260 <strong>ownership<shared></strong> 261 , <strong>value_type<Client></strong> 262> p; 263</pre> 264<p class="compound-middle">The syntax for passing named template arguments is not quite as natural as 265it is for function arguments (ideally, we'd be able to write 266<tt class="docutils literal">smart_ptr<ownership = shared, …></tt>). This small syntactic deficiency 267makes deduced parameters an especially big win when used with class 268templates:</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> 272smart_ptr<<strong>shared</strong>, <strong>Client</strong>> p; 273smart_ptr<<strong>Client</strong>, <strong>shared</strong>> 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 Tutorial</a></h1> 281<p>This tutorial shows all the basics—how to build both named- and 282deduced-parameter interfaces to function templates and class 283templates—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 Parameter-Enabled Functions</a></h2> 286<p>In this section we'll show how the Parameter library can be used to 287build 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 291After laying some groundwork and describing the algorithm's abstract 292interface, we'll show you how to build a basic implementation with keyword 293support. Then we'll add support for default arguments and we'll gradually 294refine the implementation with syntax improvements. Finally we'll show 295how to streamline the implementation of named parameter interfaces, 296improve their participation in overload resolution, and optimize their 297runtime efficiency. --> 298<div class="section" id="headers-and-namespaces"> 299<h3>2.1.1 Headers And Namespaces</h3> 300<p>Most components of the Parameter library are declared in a header named for 301the component. For example,</p> 302<pre class="literal-block"> 303#include <boost/parameter/keyword.hpp> 304</pre> 305<p>will ensure <tt class="docutils literal"><span class="pre">boost::parameter::keyword</span></tt> is known to the compiler. There 306is also a combined header, <tt class="docutils literal">boost/parameter.hpp</tt>, that includes most of 307the library's components. For the the rest of this tutorial, unless we 308say 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(''' 311using 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"> 316namespace 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 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 325from one to four arguments by reference. If all arguments were 326required, its signature might be as follows:</p> 327<pre class="literal-block"> 328template < 329 typename Graph 330 , typename DFSVisitor 331 , typename Index 332 , typename ColorMap 333> 334void 335 depth_first_search( 336 Graph const& graph 337 , DFSVisitor visitor 338 , typename graph_traits<g>::vertex_descriptor root_vertex 339 , IndexMap index_map 340 , ColorMap& color 341 ); 342</pre> 343<!-- @ignore() --> 344<p>However, most of the parameters have a useful default value, 345as 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 356Name</th> 357<th class="head">Data 358Flow</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<>()</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 380descriptor 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> 387with key type := 388<tt class="docutils literal">graph</tt>'s vertex 389descriptor and value 390type 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 / 395out</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> 398with key type := 399<tt class="docutils literal">graph</tt>'s vertex 400descriptor type.</td> 401<td>a <tt class="docutils literal"><span class="pre">boost::iterator_property_map</span></tt> 402created 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 410above. For the purposes of this exercise, you don't need to understand 411them in detail.</p> 412</div> 413<div class="section" id="defining-the-keywords"> 414<h3>2.1.3 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 417arguments for which the default is appropriate:</p> 418<pre class="literal-block"> 419graphs::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 426identified by a unique <strong>keyword tag type</strong>.</p> 427<!-- Revisit this 428 429We're going to define our interface in namespace ``graphs``. Since users 430need access to the keyword objects, but not the tag types, we'll define 431the keyword objects so they're accessible through ``graphs``, and we'll 432hide the tag types away in a nested namespace, ``graphs::tag``. The 433library 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 435library provides a convenient macro for defining keyword objects:</p> 436<pre class="literal-block"> 437#include <boost/parameter/name.hpp> 438 439namespace 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"> 451namespace 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<tag::graph> const& _graph 465 = boost::parameter::keyword<tag::graph>::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> 472reference named <tt class="docutils literal">_graph</tt>.</p> 473<p>This “fancy dance” involving an unnamed namespace and references is all done 474to avoid violating the One Definition Rule (ODR)<a class="footnote-reference" href="#odr" id="id5"><sup>2</sup></a> when the named 475parameter interface is used by function templates that are instantiated in 476multiple 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 Writing the Function</h3> 480<p>Now that we have our keywords defined, the function template definition 481follows a simple pattern using the <tt class="docutils literal">BOOST_PARAMETER_FUNCTION</tt> macro:</p> 482<pre class="literal-block"> 483#include <boost/parameter/preprocessor.hpp> 484 485namespace 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<>()) 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 511BOOST_PARAMETER_NAME(graph) 512BOOST_PARAMETER_NAME(visitor) 513BOOST_PARAMETER_NAME(in(root_vertex)) 514BOOST_PARAMETER_NAME(in(index_map)) 515BOOST_PARAMETER_NAME(in_out(color_map)) 516 517namespace 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 531the return type prevent any commas it might contain from confusing the 532preprocessor, 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 535function'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 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 543order in which they'd be expected if passed positionally. Any required 544parameters must come first, but the <tt class="docutils literal">(required … )</tt> clause can be omitted 545when all the parameters are optional.</p> 546<div class="section" id="required-parameters"> 547<h4>2.1.5.1 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> 550clause—as a series of two-element tuples describing each parameter name 551and any requirements on the argument type. In this case there is only a 552single 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 558allowed. Required parameters must always precede any optional parameters 559in 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 565BOOST_PARAMETER_NAME(graph) 566 567BOOST_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 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 576series of adjacent <em>three</em>-element tuples describing the parameter name, 577any requirements on the argument type, <em>and</em> and an expression 578representing the parameter's default value:</p> 579<pre class="compound-last literal-block"> 580(optional 581 <strong>(visitor, *, boost::dfs_visitor<>()) 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 593namespace boost { 594 595 int vertex_index = 0; 596 597 template <typename T = int> 598 struct dfs_visitor 599 { 600 }; 601} 602 603BOOST_PARAMETER_NAME(graph) 604BOOST_PARAMETER_NAME(visitor) 605BOOST_PARAMETER_NAME(in(root_vertex)) 606BOOST_PARAMETER_NAME(in(index_map)) 607BOOST_PARAMETER_NAME(in_out(color_map)) 608 609BOOST_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 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 620and 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 621parameters can be <tt class="docutils literal">const</tt> lvalues, mutable lvalues, <tt class="docutils literal">const</tt> rvalues, 622or mutable rvalues. Therefore, the default configuration grants the most 623flexibility 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>, 626which 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 627are now passed by <tt class="docutils literal">const</tt> lvalue reference and so must only be read 628from. 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 630in <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 634to. Such parameters can only be mutable lvalues. In the example, to 635indicate 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 637difference 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 638whichever 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 641rvalue 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 642access step. Such parameters can only be mutable 643rvalues. 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"> 647BOOST_PARAMETER_NAME(graph) 648BOOST_PARAMETER_NAME(visitor) 649BOOST_PARAMETER_NAME(<strong>in(root_vertex)</strong>) 650BOOST_PARAMETER_NAME(<strong>in(index_map)</strong>) 651BOOST_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 654violate their category constraints, attempt to compile the <a class="reference external" href="../../test/compose.cpp">compose.cpp</a> 655test program with either the <tt class="docutils literal">LIBS_PARAMETER_TEST_COMPILE_FAILURE_0</tt> 656macro 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 658constraint violation.</p> 659</div> 660<!-- @example.prepend(''' 661#include <boost/parameter.hpp> 662 663namespace boost { 664 665 int vertex_index = 0; 666 667 template <typename T = int> 668 struct dfs_visitor 669 { 670 }; 671} 672''') --> 673<!-- @example.append(''' 674BOOST_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 Positional Arguments</h4> 692<p>When arguments are passed positionally (without the use of keywords), they 693will be mapped onto parameters in the order the parameters are given in the 694signature, so for example in this call</p> 695<pre class="literal-block"> 696graphs::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 700interpreted as a visitor.</p> 701</div> 702<div class="section" id="default-expression-evaluation"> 703<h4>2.1.5.5 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 706default 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<>()) 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 721A default expression is evaluated in the context of all preceding 722parameters, 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 725argument is passed for that parameter. We can actually demonstrate that 726with our code so far by replacing the body of <tt class="docutils literal">depth_first_search</tt> with 727something that prints the arguments:</p> 728<pre class="compound-middle literal-block"> 729#include <boost/graph/depth_first_search.hpp> // for dfs_visitor 730 731BOOST_PARAMETER_FUNCTION( 732 (bool), depth_first_search, tag 733 <em>…signature goes here…</em> 734) 735{ 736 std::cout << "graph=" << graph; 737 std::cout << std::endl; 738 std::cout << "visitor=" << visitor; 739 std::cout << std::endl; 740 std::cout << "root_vertex=" << root_vertex; 741 std::cout << std::endl; 742 std::cout << "index_map=" << index_map; 743 std::cout << std::endl; 744 std::cout << "color_map=" << color_map; 745 std::cout << std::endl; 746 return true; 747} 748 749#include <boost/core/lightweight_test.hpp> 750 751int main() 752{ 753 char const* g = "1"; 754 depth_first_search(1, 2, 3, 4, 5); 755 depth_first_search( 756 g, '2', _color_map = '5', 757 _index_map = "4", _root_vertex = "3" 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> 764arguments, both calls will compile, and each one will print exactly the 765same thing.</p> 766</div> 767<!-- @example.prepend(''' 768#include <boost/parameter.hpp> 769#include <iostream> 770 771BOOST_PARAMETER_NAME(graph) 772BOOST_PARAMETER_NAME(visitor) 773BOOST_PARAMETER_NAME(root_vertex) 774BOOST_PARAMETER_NAME(index_map) 775BOOST_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 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, 792provided we pass <em>something</em> for the required <tt class="docutils literal">graph</tt> parameter. That might 793not seem to be a problem at first; after all, if the arguments don't match the 794requirements imposed by the implementation of <tt class="docutils literal">depth_first_search</tt>, a 795compilation 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 799selected as the best matching overload. Some other <tt class="docutils literal">depth_first_search</tt> 800overload might've worked had it been chosen instead. By the time we see a 801compilation error, there's no chance to change that decision.</li> 802<li>Even if there are no overloads, error messages generated at instantiation 803time usually expose users to confusing implementation details. For 804example, 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 807of the kinds of errors you get from your STL implementation when you make 808a 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 810have 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 812argument-dependent lookup (ADL), we can isolate <tt class="docutils literal">depth_first_search</tt> in 813a namespace containing no types<a class="footnote-reference" href="#using" id="id8"><sup>6</sup></a>, but suppose we <em>want</em> it to 814found via ADL?</li> 815</ol> 816<p>It's usually a good idea to prevent functions from being considered for 817overload resolution when the passed argument types aren't appropriate. The 818library already does this when the required <tt class="docutils literal">graph</tt> parameter is not 819supplied, but we're not likely to see a depth first search that doesn't take a 820graph to operate on. Suppose, instead, that we found a different depth first 821search 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 823ambiguous:</p> 824<pre class="literal-block"> 825// new overload 826BOOST_PARAMETER_FUNCTION((void), depth_first_search, (tag), 827 (required (graph,*))( … ) 828) 829{ 830 // new algorithm implementation 831} 832 833… 834 835// ambiguous! 836depth_first_search(boost::adjacency_list<>(), 2, "hello"); 837</pre> 838<!-- @ignore() --> 839<div class="section" id="predicate-requirements"> 840<h5>2.1.5.6.1 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">"hello"</tt>, 843doesn'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 844descriptor type. Instead, this call should just invoke our new overload. To 845take the original <tt class="docutils literal">depth_first_search</tt> overload out of contention, we first 846encode this requirement as follows:</p> 847<pre class="literal-block"> 848struct vertex_descriptor_predicate 849{ 850 template <typename T, typename Args> 851 struct apply 852 : boost::mpl::if_< 853 boost::is_convertible< 854 T 855 , typename boost::graph_traits< 856 typename boost::parameter::value_type< 857 Args 858 , graphs::graph 859 >::type 860 >::vertex_descriptor 861 > 862 , boost::mpl::true_ 863 , boost::mpl::false_ 864 > 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 871template argument, Boost.Parameter will pass in the type on which we will 872impose the requirement. For the second template argument, Boost.Parameter 873will pass in the entire argument pack, making it possible to extract the 874type 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 876result <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 879equivalent 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 881parentheses, 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 891type, and our example that <em>was</em> ambiguous will smoothly call the new 892overload.</p> 893<p>We can encode the requirements on other arguments using the same concept; only 894the implementation of the nested <tt class="docutils literal">apply</tt> metafunction needs to be tweaked 895for each argument. There's no space to give a complete description of graph 896library details here, but suffice it to show that the next few metafunction 897classes provide the necessary checks.</p> 898<pre class="literal-block"> 899struct graph_predicate 900{ 901 template <typename T, typename Args> 902 struct apply 903 : boost::mpl::eval_if< 904 boost::is_convertible< 905 typename boost::graph_traits<T>::traversal_category 906 , boost::incidence_graph_tag 907 > 908 , boost::mpl::if_< 909 boost::is_convertible< 910 typename boost::graph_traits<T>::traversal_category 911 , boost::vertex_list_graph_tag 912 > 913 , boost::mpl::true_ 914 , boost::mpl::false_ 915 > 916 > 917 { 918 }; 919}; 920 921struct index_map_predicate 922{ 923 template <typename T, typename Args> 924 struct apply 925 : boost::mpl::eval_if< 926 boost::is_integral< 927 typename boost::property_traits<T>::value_type 928 > 929 , boost::mpl::if_< 930 boost::is_same< 931 typename boost::property_traits<T>::key_type 932 , typename boost::graph_traits< 933 typename boost::parameter::value_type< 934 Args 935 , graphs::graph 936 >::type 937 >::vertex_descriptor 938 > 939 , boost::mpl::true_ 940 , boost::mpl::false_ 941 > 942 > 943 { 944 }; 945}; 946 947struct color_map_predicate 948{ 949 template <typename T, typename Args> 950 struct apply 951 : boost::mpl::if_< 952 boost::is_same< 953 typename boost::property_traits<T>::key_type 954 , typename boost::graph_traits< 955 typename boost::parameter::value_type< 956 Args 957 , graphs::graph 958 >::type 959 >::vertex_descriptor 960 > 961 , boost::mpl::true_ 962 , boost::mpl::false_ 963 > 964 { 965 }; 966}; 967</pre> 968<p>Likewise, computing the default value for the <tt class="docutils literal">color_map</tt> parameter is no 969trivial matter, so it's best to factor the computation out to a separate 970function template.</p> 971<pre class="literal-block"> 972template <typename Size, typename IndexMap> 973boost::iterator_property_map< 974 std::vector<boost::default_color_type>::iterator 975 , IndexMap 976 , boost::default_color_type 977 , boost::default_color_type& 978>& 979 default_color_map(Size num_vertices, IndexMap const& index_map) 980{ 981 static std::vector<boost::default_color_type> colors(num_vertices); 982 static boost::iterator_property_map< 983 std::vector<boost::default_color_type>::iterator 984 , IndexMap 985 , boost::default_color_type 986 , boost::default_color_type& 987 > m(colors.begin(), index_map); 988 return m; 989} 990</pre> 991<p>The signature encloses each predicate metafunction in parentheses <em>preceded 992by an asterix</em>, as follows:</p> 993<pre class="literal-block"> 994BOOST_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<>() 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 1031BOOST_PARAMETER_NAME((_graph, graphs) graph) 1032BOOST_PARAMETER_NAME((_visitor, graphs) visitor) 1033BOOST_PARAMETER_NAME((_root_vertex, graphs) in(root_vertex)) 1034BOOST_PARAMETER_NAME((_index_map, graphs) in(index_map)) 1035BOOST_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 1045int 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 1065arguments to generic functions. However, doing so is worth the effort: your 1066code will be more self-documenting and will often provide a better user 1067experience. 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 More on Type Requirements</h5> 1072<p>Encoding type requirements onto a function's parameters is essential for 1073enabling 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"> 1076window* w = new_window( 1077 movable_=false 1078 , "alert box" 1079); 1080window* w = new_window( 1081 "alert box" 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 1087specifying the keywords. For each parameter that has a required type, we can 1088enclose that type in parentheses, then <em>replace</em> the <tt class="docutils literal">*</tt> element of the 1089parameter signature:</p> 1090<pre class="literal-block"> 1091BOOST_PARAMETER_NAME((name_, keywords) name) 1092BOOST_PARAMETER_NAME((movable_, keywords) movable) 1093 1094BOOST_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 1108well as the previous statements:</p> 1109<pre class="literal-block"> 1110window* w = new_window(false, "alert box"); 1111window* w = new_window("alert box", false); 1112</pre> 1113<!-- @ignore() --> 1114</div> 1115</div> 1116<div class="section" id="deduced-parameters"> 1117<h4>2.1.5.7 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"> 1121template < 1122 typename Function 1123 , typename KeywordExpression 1124 , typename CallPolicies 1125> 1126void def( 1127 // Required parameters 1128 char const* name, Function func 1129 1130 // Optional, deduced parameters 1131 , char const* docstring = "" 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 1138example: although it means something analogous in Boost.Python to what 1139it means in the Parameter library, for the purposes of this exercise 1140you 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 1142between any additional arguments and their parameters can be determined by the 1143types of the arguments actually passed, so the caller is neither required to 1144remember argument positions or explicitly specify parameter names for those 1145arguments. To generate this interface using <tt class="docutils literal">BOOST_PARAMETER_FUNCTION</tt>, we 1146need only enclose the deduced parameters in a <tt class="docutils literal">(deduced …)</tt> clause, as 1147follows:</p> 1148<pre class="literal-block"> 1149char const*& blank_char_ptr() 1150{ 1151 static char const* larr = ""; 1152 return larr; 1153} 1154 1155BOOST_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*), "") 1163 1164 (keywords 1165 // see<a class="footnote-reference" href="#is-keyword-expression" id="id13"><sup>5</sup></a> 1166 , *(is_keyword_expression<boost::mpl::_>) 1167 , no_keywords() 1168 ) 1169 1170 (policies 1171 , *( 1172 boost::mpl::eval_if< 1173 boost::is_convertible<boost::mpl::_,char const*> 1174 , boost::mpl::false_ 1175 , boost::mpl::if_< 1176 // see<a class="footnote-reference" href="#is-keyword-expression" id="id14"><sup>5</sup></a> 1177 is_keyword_expression<boost::mpl::_> 1178 , boost::mpl::false_ 1179 , boost::mpl::true_ 1180 > 1181 > 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 1196BOOST_PARAMETER_NAME(name) 1197BOOST_PARAMETER_NAME(func) 1198BOOST_PARAMETER_NAME(docstring) 1199BOOST_PARAMETER_NAME(keywords) 1200BOOST_PARAMETER_NAME(policies) 1201 1202struct default_call_policies 1203{ 1204}; 1205 1206struct no_keywords 1207{ 1208}; 1209 1210struct keywords 1211{ 1212}; 1213 1214template <typename T> 1215struct is_keyword_expression 1216 : boost::mpl::false_ 1217{ 1218}; 1219 1220template <> 1221struct is_keyword_expression<keywords> 1222 : boost::mpl::true_ 1223{ 1224}; 1225 1226default_call_policies some_policies; 1227 1228void 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 1243level.</p> 1244</div> 1245<p>With the declaration above, the following two calls are equivalent:</p> 1246<pre class="literal-block"> 1247char const* f_name = "f"; 1248def( 1249 f_name 1250 , &f 1251 , <strong>some_policies</strong> 1252 , <strong>"Documentation for f"</strong> 1253); 1254def( 1255 f_name 1256 , &f 1257 , <strong>"Documentation for f"</strong> 1258 , <strong>some_policies</strong> 1259); 1260</pre> 1261<!-- @example.prepend(''' 1262int main() 1263{ 1264''') --> 1265<p>If the user wants to pass a <tt class="docutils literal">policies</tt> argument that was also, for some 1266reason, convertible to <tt class="docutils literal">char const*</tt>, she can always specify the parameter 1267name explicitly, as follows:</p> 1268<pre class="literal-block"> 1269def( 1270 f_name 1271 , &f 1272 , <strong>_policies = some_policies</strong> 1273 , "Documentation for f" 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 1279demonstrate additional usage of deduced parameter support.</p> 1280</div> 1281<div class="section" id="parameter-dependent-return-types"> 1282<h4>2.1.5.8 Parameter-Dependent Return Types</h4> 1283<p>For some algorithms, the return type depends on at least one of the argument 1284types. However, there is one gotcha to avoid when encoding this return type 1285while using <tt class="docutils literal">BOOST_PARAMETER_FUNCTION</tt> or other code generation macros. As 1286an example, given the following definitions:</p> 1287<pre class="literal-block"> 1288BOOST_PARAMETER_NAME(x) 1289BOOST_PARAMETER_NAME(y) 1290BOOST_PARAMETER_NAME(z) 1291</pre> 1292<!-- @ignore() --> 1293<p>Let our algorithm simply return one of its arguments. If we naïvely implement 1294its return type in terms of <tt class="docutils literal"><span class="pre">parameter::value_type</span></tt>:</p> 1295<pre class="literal-block"> 1296BOOST_PARAMETER_FUNCTION( 1297 (typename parameter::value_type<Args,tag::y>::type), return_y, tag, 1298 (deduced 1299 (required 1300 (x, (std::map<char const*,std::string>)) 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 1314will result in a compiler error:</p> 1315<pre class="literal-block"> 1316std::map<char const*,std::string> k2s; 1317assert("foo" == return_y(2, k2s, "foo")); // 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 1322argument 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 1324overloads. Since <tt class="docutils literal"><span class="pre">parameter::value_type</span></tt> is a metafunction, our tool for 1325the job is <tt class="docutils literal">lazy_enable_if</tt>:</p> 1326<pre class="literal-block"> 1327BOOST_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< 1332 typename mpl::has_key<Args,tag::y>::type 1333 , parameter::value_type<Args,tag::y> 1334 > 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<char const*,std::string>)) 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 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 1361arguments as <tt class="docutils literal">BOOST_PARAMETER_FUNCTION</tt>, but are designed to be used within 1362the body of a class:</p> 1363<pre class="literal-block"> 1364BOOST_PARAMETER_NAME(arg1) 1365BOOST_PARAMETER_NAME(arg2) 1366 1367struct callable2 1368{ 1369 BOOST_PARAMETER_CONST_MEMBER_FUNCTION( 1370 (void), call, tag, (required (arg1,(int))(arg2,(int))) 1371 ) 1372 { 1373 std::cout << arg1 << ", " << arg2; 1374 std::cout << std::endl; 1375 } 1376}; 1377 1378#include <boost/core/lightweight_test.hpp> 1379 1380int main() 1381{ 1382 callable2 c2; 1383 callable2 const& 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> 1391using namespace boost::parameter; 1392''') --> 1393<!-- @test('run') --> 1394<p>These macros don't directly allow a function's interface to be separated from 1395its implementation, but you can always forward arguments on to a separate 1396implementation function:</p> 1397<pre class="literal-block"> 1398struct 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 1414BOOST_PARAMETER_NAME(arg1) 1415BOOST_PARAMETER_NAME(arg2) 1416using namespace boost::parameter; 1417''') --> 1418<!-- @test('compile') --> 1419<div class="section" id="static-member-functions"> 1420<h3>2.2.1 Static Member Functions</h3> 1421<p>To expose a static member function, simply insert the keyword “<tt class="docutils literal">static</tt>” 1422before the function name:</p> 1423<pre class="literal-block"> 1424BOOST_PARAMETER_NAME(arg1) 1425 1426struct somebody 1427{ 1428 BOOST_PARAMETER_MEMBER_FUNCTION( 1429 (void), <strong>static</strong> f, tag, (optional (arg1,(int),0)) 1430 ) 1431 { 1432 std::cout << arg1 << std::endl; 1433 } 1434}; 1435 1436#include <boost/core/lightweight_test.hpp> 1437 1438int 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> 1448using 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 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 1457arguments 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, 1459because these macros allow instances of the enclosing classes to be treated as 1460function objects:</p> 1461<pre class="literal-block"> 1462BOOST_PARAMETER_NAME(first_arg) 1463BOOST_PARAMETER_NAME(second_arg) 1464 1465struct callable2 1466{ 1467 BOOST_PARAMETER_CONST_FUNCTION_CALL_OPERATOR( 1468 (void), tag, (required (first_arg,(int))(second_arg,(int))) 1469 ) 1470 { 1471 std::cout << first_arg << ", "; 1472 std::cout << second_arg << std::endl; 1473 } 1474}; 1475 1476#include <boost/core/lightweight_test.hpp> 1477 1478int main() 1479{ 1480 callable2 c2; 1481 callable2 const& 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> 1489using 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 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>) 1497limits somewhat the quality of interface this library can provide 1498for defining parameter-enabled constructors. The usual workaround 1499for a lack of constructor delegation applies: one must factor the 1500common logic into one or more base classes.</p> 1501<p>Let's build a parameter-enabled constructor that simply prints its 1502arguments. The first step is to write a base class whose 1503constructor accepts a single argument known as an <a class="reference external" href="reference.html#argumentpack"><span class="concept">ArgumentPack</span></a>: 1504a bundle of references to the actual arguments, tagged with their 1505keywords. The values of the actual arguments are extracted from 1506the <span class="concept">ArgumentPack</span> by <em>indexing</em> it with keyword objects:</p> 1507<pre class="literal-block"> 1508BOOST_PARAMETER_NAME(name) 1509BOOST_PARAMETER_NAME(index) 1510 1511struct myclass_impl 1512{ 1513 template <typename ArgumentPack> 1514 myclass_impl(ArgumentPack const& args) 1515 { 1516 std::cout << "name = " << args[_name]; 1517 std::cout << "; index = " << args[_index | 42]; 1518 std::cout << 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 1527applied to keyword objects that are passed to an <span class="concept">ArgumentPack</span>'s indexing 1528operator: 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"> 1532struct 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>, 1541only <tt class="docutils literal">name</tt> is required. We can exercise our new interface as follows:</p> 1542<pre class="literal-block"> 1543myclass x("bob", 3); // positional 1544myclass y(_index = 12, _name = "sally"); // named 1545myclass z("june"); // positional/defaulted 1546</pre> 1547<!-- @example.wrap(''' 1548#include <boost/core/lightweight_test.hpp> 1549 1550int 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 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"> 1559template < 1560 ValueType, BaseList = bases<> 1561 , HeldType = ValueType, Copyable = void 1562> 1563class 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 Named Template Parameters</h3> 1569<p>First, we'll build an interface that allows users to pass arguments 1570positionally or by name:</p> 1571<pre class="literal-block"> 1572struct B 1573{ 1574 virtual ~B() = 0; 1575}; 1576 1577struct D : B 1578{ 1579 ~D(); 1580}; 1581 1582class_< 1583 <strong>class_type<B></strong> 1584 , <strong>copyable<boost::noncopyable></strong> 1585> …; 1586 1587class_< 1588 <strong>D</strong> 1589 , <strong>held_type<std::auto_ptr<D> ></strong> 1590 , <strong>base_list<bases<B> ></strong> 1591> …; 1592</pre> 1593<!-- @ignore() --> 1594<div class="section" id="template-keywords"> 1595<h4>2.5.1.1 Template Keywords</h4> 1596<p>The first step is to define keywords for each template parameter:</p> 1597<pre class="literal-block"> 1598namespace 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"> 1610namespace boost { namespace python { 1611 namespace tag { 1612 1613 struct class_type; // keyword tag type 1614 } 1615 1616 template <typename T> 1617 struct class_type 1618 : parameter::template_keyword<tag::class_type,T> 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 Class Template Skeleton</h4> 1630<p>The next step is to define the skeleton of our class template, which has three 1631optional parameters. Because the user may pass arguments in any order, we 1632don't know the actual identities of these parameters, so it would be premature 1633to use descriptive names or write out the actual default values for any of 1634them. 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"> 1637namespace boost { namespace python { 1638 1639 template < 1640 typename A0 1641 , typename A1 = boost::parameter::void_ 1642 , typename A2 = boost::parameter::void_ 1643 , typename A3 = boost::parameter::void_ 1644 > 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 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 1659required and optional parameters in their positional order, along with any 1660type requirements (note that it does <em>not</em> specify defaults -- those will be 1661dealt with separately):</p> 1662<pre class="literal-block"> 1663namespace boost { namespace python { 1664 1665 using boost::mpl::_; 1666 1667 typedef parameter::parameters< 1668 required<tag::class_type, boost::is_class<_> > 1669 , parameter::optional<tag::base_list, mpl::is_sequence<_> > 1670 , parameter::optional<tag::held_type> 1671 , parameter::optional<tag::copyable> 1672 > 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 1682using namespace boost::parameter; 1683 1684namespace 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 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 1701nested <tt class="docutils literal">::bind< … ></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< … ></tt> 1703metafunction to extract “logical parameters”. <tt class="docutils literal">value_type< … ></tt> is 1704a lot like <tt class="docutils literal">binding< … ></tt>, but no reference is added to the actual 1705argument type. Note that defaults are specified by passing it an 1706optional third argument:</p> 1707<pre class="literal-block"> 1708namespace boost { namespace python { 1709 1710 template < 1711 typename A0 1712 , typename A1 = boost::parameter::void_ 1713 , typename A2 = boost::parameter::void_ 1714 , typename A3 = boost::parameter::void_ 1715 > 1716 struct class_ 1717 { 1718 // Create ArgumentPack 1719 typedef typename class_signature::template bind< 1720 A0, A1, A2, A3 1721 >::type args; 1722 1723 // Extract first logical parameter. 1724 typedef typename parameter::value_type< 1725 args, tag::class_type 1726 >::type class_type; 1727 1728 typedef typename parameter::value_type< 1729 args, tag::base_list, bases<> 1730 >::type base_list; 1731 1732 typedef typename parameter::value_type< 1733 args, tag::held_type, class_type 1734 >::type held_type; 1735 1736 typedef typename parameter::value_type< 1737 args, tag::copyable, void 1738 >::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 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"> 1749typedef boost::python::class_< 1750 class_type<B>, copyable<boost::noncopyable> 1751> c1; 1752 1753typedef boost::python::class_< 1754 D 1755 , held_type<std::auto_ptr<D> > 1756 , base_list<bases<B> > 1757> c2; 1758</pre> 1759<!-- @example.prepend(''' 1760using boost::python::class_type; 1761using boost::python::copyable; 1762using boost::python::held_type; 1763using boost::python::base_list; 1764using boost::python::bases; 1765 1766struct B 1767{ 1768}; 1769 1770struct D 1771{ 1772}; 1773''') --> 1774<p class="compound-middle">we can now examine the intended parameters:</p> 1775<pre class="compound-last literal-block"> 1776BOOST_MPL_ASSERT((boost::is_same<c1::class_type, B>)); 1777BOOST_MPL_ASSERT((boost::is_same<c1::base_list, bases<> >)); 1778BOOST_MPL_ASSERT((boost::is_same<c1::held_type, B>)); 1779BOOST_MPL_ASSERT(( 1780 boost::is_same<c1::copyable, boost::noncopyable> 1781)); 1782 1783BOOST_MPL_ASSERT((boost::is_same<c2::class_type, D>)); 1784BOOST_MPL_ASSERT((boost::is_same<c2::base_list, bases<B> >)); 1785BOOST_MPL_ASSERT(( 1786 boost::is_same<c2::held_type, std::auto_ptr<D> > 1787)); 1788BOOST_MPL_ASSERT((boost::is_same<c2::copyable, void>)); 1789</pre> 1790</div> 1791<!-- @test('compile', howmany='all') --> 1792</div> 1793<div class="section" id="deduced-template-parameters"> 1794<h3>2.5.3 Deduced Template Parameters</h3> 1795<p>To apply a deduced parameter interface here, we need only make the type 1796requirements a bit tighter so the <tt class="docutils literal">held_type</tt> and <tt class="docutils literal">copyable</tt> parameters 1797can be crisply distinguished from the others. <a class="reference external" href="../../../python/doc/index.html">Boost.Python</a> does this by 1798requiring that <tt class="docutils literal">base_list</tt> be a specialization of its <tt class="docutils literal">bases< … ></tt> 1799template (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 1801of identifying specializations of <tt class="docutils literal">bases< … ></tt> is to derive them all from 1802the same class, as an implementation detail:</p> 1803<pre class="literal-block"> 1804namespace boost { namespace python { 1805 namespace detail { 1806 1807 struct bases_base 1808 { 1809 }; 1810 } 1811 1812 template < 1813 typename A0 = void, typename A1 = void, typename A2 = void <em>…</em> 1814 > 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 1827using namespace boost::parameter; 1828using boost::mpl::_; 1829 1830namespace 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 1839deducible:</p> 1840<pre class="literal-block"> 1841typedef parameter::parameters< 1842 required<tag::class_type, is_class<_> > 1843 1844 , parameter::optional< 1845 deduced<tag::base_list> 1846 , is_base_and_derived<detail::bases_base,_> 1847 > 1848 1849 , parameter::optional< 1850 deduced<tag::held_type> 1851 , mpl::not_< 1852 mpl::or_< 1853 is_base_and_derived<detail::bases_base,_> 1854 , is_same<noncopyable,_> 1855 > 1856 > 1857 > 1858 1859 , parameter::optional< 1860 deduced<tag::copyable> 1861 , is_same<noncopyable,_> 1862 > 1863 1864> class_signature; 1865</pre> 1866<!-- @example.prepend(''' 1867#include <boost/type_traits/is_class.hpp> 1868namespace 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 1904our users are greater. Our original examples can now be written without 1905explicit parameter names:</p> 1906<pre class="literal-block"> 1907typedef boost::python::class_<<strong>B</strong>, <strong>boost::noncopyable</strong>> c1; 1908 1909typedef boost::python::class_< 1910 <strong>D</strong>, <strong>std::auto_ptr<D></strong>, <strong>bases<B></strong> 1911> c2; 1912</pre> 1913<!-- @example.prepend(''' 1914struct B 1915{ 1916}; 1917 1918struct D 1919{ 1920}; 1921 1922using boost::python::bases; 1923''') --> 1924<!-- @example.append(''' 1925BOOST_MPL_ASSERT((boost::is_same<c1::class_type, B>)); 1926BOOST_MPL_ASSERT((boost::is_same<c1::base_list, bases<> >)); 1927BOOST_MPL_ASSERT((boost::is_same<c1::held_type, B>)); 1928BOOST_MPL_ASSERT(( 1929 boost::is_same<c1::copyable, boost::noncopyable> 1930)); 1931 1932BOOST_MPL_ASSERT((boost::is_same<c2::class_type, D>)); 1933BOOST_MPL_ASSERT((boost::is_same<c2::base_list, bases<B> >)); 1934BOOST_MPL_ASSERT(( 1935 boost::is_same<c2::held_type, std::auto_ptr<D> > 1936)); 1937BOOST_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 Advanced Topics</a></h1> 1945<p>At this point, you should have a good grasp of the basics. In this section 1946we'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 Fine-Grained Name Control</a></h2> 1949<p>If you don't like the leading-underscore naming convention used to refer to 1950keyword objects, or you need the name <tt class="docutils literal">tag</tt> for something other than the 1951keyword type namespace, there's another way to use <tt class="docutils literal">BOOST_PARAMETER_NAME</tt>:</p> 1952<pre class="literal-block"> 1953BOOST_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"> 1963BOOST_PARAMETER_NAME( 1964 ( 1965 <strong>pass_foo</strong>, <strong>keywords</strong> 1966 ) <strong>foo</strong> 1967) 1968 1969BOOST_PARAMETER_FUNCTION( 1970 (int), f, 1971 <strong>keywords</strong>, (required (<strong>foo</strong>, *)) 1972) 1973{ 1974 return <strong>foo</strong> + 1; 1975} 1976 1977int x = f(<strong>pass_foo</strong> = 41); 1978</pre> 1979<!-- @example.prepend('#include <boost/parameter.hpp>') --> 1980<!-- @example.append(''' 1981int 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 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 1994might have guessed, <span class="concept">ArgumentPack</span>s actually lie at the heart of 1995everything this library does; in this section we'll examine ways to 1996build and manipulate them more effectively.</p> 1997<div class="section" id="building-argumentpacks"> 1998<h3>3.2.1 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"> 2001BOOST_PARAMETER_NAME(index) 2002 2003template <typename ArgumentPack> 2004int print_index(ArgumentPack const& args) 2005{ 2006 std::cout << "index = " << args[_index]; 2007 std::cout << std::endl; 2008 return 0; 2009} 2010 2011int x = print_index(_index = 3); // prints "index = 3" 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 2018parentheses below are used to prevent the compiler from seeing two separate 2019arguments to <tt class="docutils literal">print_name_and_index</tt>:</p> 2020<pre class="literal-block"> 2021BOOST_PARAMETER_NAME(name) 2022 2023template <typename ArgumentPack> 2024int print_name_and_index(ArgumentPack const& args) 2025{ 2026 std::cout << "name = " << args[_name]; 2027 std::cout << "; "; 2028 return print_index(args); 2029} 2030 2031int y = print_name_and_index((_index = 3, _name = "jones")); 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 2036Signatures</a>, a <span class="concept">ParameterSpec</span> describes the positional order of parameters 2037and 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< … ></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"> 2041parameter::parameters< 2042 required<tag::name, is_convertible<_,char const*> > 2043 , optional<tag::index, is_convertible<_,int> > 2044> spec; 2045 2046char const sam[] = "sam"; 2047int twelve = 12; 2048 2049int z0 = print_name_and_index( 2050 <strong>spec(</strong> sam, twelve <strong>)</strong> 2051); 2052 2053int z1 = print_name_and_index( 2054 <strong>spec(</strong> _index=12, _name="sam" <strong>)</strong> 2055); 2056</pre> 2057<!-- @example.prepend(''' 2058namespace parameter = boost::parameter; 2059using parameter::required; 2060using parameter::optional; 2061using boost::is_convertible; 2062using boost::mpl::_; 2063''') --> 2064<!-- @example.append(''' 2065int 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 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 2076simplest and least error-prone approach is to forward them to a 2077function template and allow <em>it</em> to do type deduction:</p> 2078<pre class="literal-block"> 2079BOOST_PARAMETER_NAME(name) 2080BOOST_PARAMETER_NAME(index) 2081 2082template <typename Name, typename Index> 2083int deduce_arg_types_impl(Name&& name, Index&& index) 2084{ 2085 // we know the types 2086 Name&& n2 = boost::forward<Name>(name); 2087 Index&& i2 = boost::forward<Index>(index); 2088 return index; 2089} 2090 2091template <typename ArgumentPack> 2092int deduce_arg_types(ArgumentPack const& 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 2103int 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 2114function call. For example, suppose we wanted to return twice the value of 2115the <tt class="docutils literal">index</tt> parameter? In that case we can use the <tt class="docutils literal">value_type< … ></tt> 2116metafunction introduced <a class="reference internal" href="#binding-intro">earlier</a>:</p> 2117<pre class="literal-block"> 2118BOOST_PARAMETER_NAME(index) 2119 2120template <typename ArgumentPack> 2121typename boost::parameter::value_type<ArgumentPack,tag::index,int>::type 2122 twice_index(ArgumentPack const& 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 2133int 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< … ></tt> rather than <tt class="docutils literal">value_type< … ></tt>, we 2142would end up returning a reference to the temporary created in the <tt class="docutils literal">2 * …</tt> 2143expression.</p> 2144</div> 2145<div class="section" id="lazy-default-computation"> 2146<h3>3.2.3 Lazy Default Computation</h3> 2147<p>When a default value is expensive to compute, it would be preferable to avoid 2148it until we're sure it's absolutely necessary. <tt class="docutils literal">BOOST_PARAMETER_FUNCTION</tt> 2149takes care of that problem for us, but when using <span class="concept">ArgumentPack</span>s 2150explicitly, we need a tool other than <tt class="docutils literal">operator|</tt>:</p> 2151<pre class="literal-block"> 2152BOOST_PARAMETER_NAME(s1) 2153BOOST_PARAMETER_NAME(s2) 2154BOOST_PARAMETER_NAME(s3) 2155 2156template <typename ArgumentPack> 2157std::string f(ArgumentPack const& args) 2158{ 2159 std::string const& s1 = args[_s1]; 2160 std::string const& s2 = args[_s2]; 2161 typename parameter::binding< 2162 ArgumentPack,tag::s3,std::string 2163 >::type s3 = args[_s3 | (s1 + s2)]; // always constructs s1 + s2 2164 return s3; 2165} 2166 2167std::string x = f(( 2168 _s1="hello,", _s2=" world", _s3="hi world" 2169)); 2170</pre> 2171<!-- @example.prepend(''' 2172#include <boost/parameter.hpp> 2173#include <string> 2174 2175namespace parameter = boost::parameter; 2176''') --> 2177<!-- @example.append(''' 2178int main() 2179{ 2180 return 0; 2181} 2182''') --> 2183<!-- @test('run') --> 2184<p>In the example above, the string <tt class="docutils literal">"hello, world"</tt> is constructed despite the 2185fact that the user passed us a value for <tt class="docutils literal">s3</tt>. To remedy that, we can 2186compute 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"> 2194typename parameter::binding< 2195 ArgumentPack,tag::s3,std::string 2196>::type s3 = args[ 2197 _s3 <strong>|| boost::bind( 2198 std::plus<std::string>(), 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 2209namespace parameter = boost::parameter; 2210 2211BOOST_PARAMETER_NAME(s1) 2212BOOST_PARAMETER_NAME(s2) 2213BOOST_PARAMETER_NAME(s3) 2214 2215template <typename ArgumentPack> 2216std::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 2225std::string x = f((_s1="hello,", _s2=" world", _s3="hi world")); 2226 2227int 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> 2237normally uses short-circuit evaluation: its second argument is only 2238evaluated 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> 2240argument was supplied.</p> 2241</div> 2242<p>The expression <tt class="docutils literal"><span class="pre">bind(std::plus<std::string>(),</span> ref(s1), ref(s2))</tt> yields a 2243<em>function object</em> that, when invoked, adds the two strings together. That 2244function 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 Best Practices</a></h1> 2254<p>By now you should have a fairly good idea of how to use the Parameter 2255library. This section points out a few more-marginal issues that will help 2256you use the library more effectively.</p> 2257<div class="section" id="keyword-naming"> 2258<h2><a class="toc-backref" href="#id36">4.1 Keyword Naming</a></h2> 2259<p><tt class="docutils literal">BOOST_PARAMETER_NAME</tt> prepends a leading underscore to the names of all our 2260keyword objects in order to avoid the following usually-silent bug:</p> 2261<pre class="literal-block"> 2262namespace 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<tag::name>& <strong>name</strong> 2280 = boost::parameter::keyword<tag::name>::instance; 2281 boost::parameter::keyword<tag::age>& <strong>age</strong> 2282 = boost::parameter::keyword<tag::age>::instance; 2283 } 2284 2285 BOOST_PARAMETER_FUNCTION( 2286 (void), g, tag, (optional (name, *, "bob")(age, *, 42)) 2287 ) 2288 { 2289 std::cout << name << ":" << 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> 2305argument got reassigned the value 3, and was then passed as a positional 2306argument 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 2307default value for <tt class="docutils literal">age</tt> is used, and g prints <tt class="docutils literal">3:42</tt>. Our leading 2308underscore 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> 2310parameter had been made <tt class="docutils literal">const</tt>, which is always a good idea whenever 2311possible. Finally, we recommend that you use an enclosing namespace for all 2312your code, but particularly for names with leading underscores. If we were to 2313leave out the <tt class="docutils literal">people</tt> namespace above, names in the global namespace 2314beginning with leading underscores—which are reserved to your C++ 2315compiler—might become irretrievably ambiguous with those in our 2316unnamed namespace.</p> 2317</div> 2318<div class="section" id="namespaces"> 2319<h2><a class="toc-backref" href="#id37">4.2 Namespaces</a></h2> 2320<p>In our examples we've always declared keyword objects in (an unnamed namespace 2321within) the same namespace as the Boost.Parameter-enabled functions using 2322those keywords:</p> 2323<pre class="literal-block"> 2324namespace 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,*,"bob")(index,(int),1)) 2332 ) 2333 { 2334 std::cout << name << ":" << index; 2335 std::cout << 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"> 2350int x = <strong>lib::</strong>f( 2351 <strong>lib::</strong>_name = "jill" 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; 2365using lib::_index;</strong> 2366 2367int x = lib::f(_name = "jill", _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> 2380int x = <strong>f</strong>(_name = "jill", _index = 3); 2381</pre> 2382<p>This option is convenient, but it indiscriminately makes the <em>entire</em> 2383contents 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 2390give users more control:</p> 2391<pre class="literal-block"> 2392namespace 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,*,"bob")(index,(int),1)) 2402 ) 2403 { 2404 std::cout << name << ":" << index; 2405 std::cout << 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 2415all keywords associated with <tt class="docutils literal">lib</tt>:</p> 2416<pre class="literal-block"> 2417<strong>using namespace lib::keywords;</strong> 2418int y = lib::f(_name = "bob", _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 Documentation</a></h2> 2425<p>The interface idioms enabled by Boost.Parameter are completely new (to C++), 2426and 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 2430yet. We'd be very pleased to link to your documentation if you've got a 2431style 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 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 2438the Parameter library to see how it fares on your favorite 2439compiler. Additionally, you may need to be aware of the following 2440issues and workarounds for particular compilers.</p> 2441<div class="section" id="perfect-forwarding-support"> 2442<h2><a class="toc-backref" href="#id40">5.1 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 2444will <tt class="docutils literal">#define</tt> the macro <tt class="docutils literal">BOOST_PARAMETER_HAS_PERFECT_FORWARDING</tt> unless 2445you 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 2448cases 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 2449be 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 Boost.MP11 Support</a></h2> 2454<p>If your compiler is sufficiently compliant with the C++11 standard, then the 2455Parameter library will <tt class="docutils literal">#define</tt> the macro <tt class="docutils literal">BOOST_PARAMETER_CAN_USE_MP11</tt> 2456unless 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 2458demonstrate 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 No SFINAE Support</a></h2> 2462<p>Some older compilers don't support SFINAE. If your compiler meets that 2463criterion, 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 2465from 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 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 2471compute the types of default arguments given the type of the function object 2472that 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 2474the function object to contain a nested type name, <tt class="docutils literal">result_type</tt>, that 2475indicates its return type when invoked without arguments. To use an ordinary 2476function as a default generator on those compilers, you'll need to wrap it in 2477a class that provides <tt class="docutils literal">result_type</tt> as a <tt class="docutils literal">typedef</tt> and invokes the 2478function via its <tt class="docutils literal">operator()</tt>.</p> 2479<!-- Can't Declare |ParameterSpec| via ``typedef`` 2480============================================= 2481 2482In principle you can declare a |ParameterSpec| as a ``typedef`` for a 2483specialization of ``parameters<…>``, but Microsoft Visual C++ 6.x has been 2484seen to choke on that usage. The workaround is to use inheritance and 2485declare 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 2497Default Arguments Unsupported on Nested Templates 2498============================================= 2499 2500As of this writing, Borland compilers don't support the use of default 2501template arguments on member class templates. As a result, you have to 2502supply ``BOOST_PARAMETER_MAX_ARITY`` arguments to every use of 2503``parameters<…>::match``. Since the actual defaults used are unspecified, 2504the workaround is to use |BOOST_PARAMETER_MATCH|_ to declare default 2505arguments 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 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 2512trouble finding your keyword objects. This problem has been observed, but 2513only on this one compiler, and it disappeared as the test code evolved, so 2514we suggest you use it only as a last resort rather than as a preventative 2515measure. The solution is to add <em>using-declarations</em> to force the names 2516to be available in the enclosing namespace without qualification:</p> 2517<pre class="literal-block"> 2518namespace 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 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 2532Boost.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 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 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 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 Parameter (or “formal parameter”)</a></h2> 2546<p>the name used to refer to an argument within a function or class 2547template. 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"> 2550int f(int x) { return x + 1; } 2551int y = f(3); 2552</pre> 2553</div> 2554</div> 2555<div class="section" id="acknowledgements"> 2556<h1><a class="toc-backref" href="#id50">9 Acknowledgements</a></h1> 2557<p>The authors would like to thank all the Boosters who participated in the 2558review of this library and its documentation, most especially our review 2559manager, 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 2566use Boost.Parameter (this library) in an upcoming release, while keeping 2567the 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++ 2574program must have the same definition in all translation units (object 2575files) 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, 2582don't worry about the meaning of any Graph-library-specific details you 2583encounter. In this case you could replace all mentions of vertex 2584descriptor types with <tt class="docutils literal">int</tt> in the text, and your understanding of the 2585Parameter 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 2602metafunction <tt class="docutils literal">is_keyword_expression</tt> that can be used to identify 2603models 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 2611lives in an outer namespace by applying a <em>using-declaration</em>:</p> 2612<pre class="literal-block"> 2613namespace foo_overloads { 2614 2615 // foo declarations here 2616 void foo() { ... } 2617 ... 2618} 2619using foo_overloads::foo; 2620</pre> 2621<p class="last">This technique for avoiding unintentional argument-dependent lookup is due 2622to 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 2630SFINAE. <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 2632function template results in an invalid type, no compilation error is 2633emitted; instead the overload is removed from the overload set. By 2634producing an invalid type in the function signature depending on the 2635result of some condition, we can decide whether or not an overload is 2636considered 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 2638that don't support it, the Boost config library will <tt class="docutils literal">#define</tt> the 2639symbol <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 2641on SFINAE.</td></tr> 2642</tbody> 2643</table> 2644</div> 2645</div> 2646<div class="footer"> 2647<hr class="footer" /> 2648Generated on: 2020-08-11 14:59 UTC. 2649Generated 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> 2654
