]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
2 | The Boost Parameter Library Reference Documentation | |
3 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | |
4 | ||
5 | :Authors: David Abrahams, Daniel Wallin | |
6 | :Contact: dave@boost-consulting.com, daniel@boostpro.com | |
7 | :organization: `BoostPro Computing`_ | |
8 | :date: $Date: 2005/07/17 19:53:01 $ | |
9 | ||
10 | :copyright: Copyright David Abrahams, Daniel Wallin | |
11 | 2005-2009. Distributed under the Boost Software License, | |
12 | Version 1.0. (See accompanying file LICENSE_1_0.txt | |
13 | or copy at http://www.boost.org/LICENSE_1_0.txt) | |
14 | ||
15 | |(logo)|__ | |
16 | ||
17 | .. |(logo)| image:: ../../../../boost.png | |
18 | :alt: Boost | |
19 | ||
20 | __ ../../../../index.htm | |
21 | ||
22 | .. _`BoostPro Computing`: http://www.boostpro.com | |
23 | ||
24 | ||
25 | ////////////////////////////////////////////////////////////////////////////// | |
26 | ||
27 | .. contents:: | |
28 | :depth: 2 | |
29 | ||
30 | ////////////////////////////////////////////////////////////////////////////// | |
31 | ||
32 | .. role:: class | |
33 | :class: class | |
34 | ||
35 | .. role:: concept | |
36 | :class: concept | |
37 | ||
38 | .. role:: function | |
39 | :class: function | |
40 | ||
41 | .. |ArgumentPack| replace:: :concept:`ArgumentPack` | |
42 | .. |ForwardSequence| replace:: :concept:`Forward Sequence` | |
43 | .. |ParameterSpec| replace:: :concept:`ParameterSpec` | |
44 | ||
45 | .. role:: vellipsis | |
46 | :class: vellipsis | |
47 | ||
48 | .. section-numbering:: | |
49 | :depth: 2 | |
50 | ||
51 | Preliminaries | |
52 | ============= | |
53 | ||
54 | This section covers some basic information you'll need to know in | |
55 | order to understand this reference | |
56 | ||
57 | Namespaces | |
58 | ---------- | |
59 | ||
60 | In this document, all unqualified identifiers should be assumed to | |
61 | be defined in namespace ``boost::parameter`` unless otherwise | |
62 | specified. | |
63 | ||
64 | Exceptions | |
65 | ---------- | |
66 | ||
67 | No operation described in this document | |
68 | throws an exception unless otherwise specified. | |
69 | ||
70 | Thread Safety | |
71 | ------------- | |
72 | ||
73 | All components of this library can be used safely from multiple | |
74 | threads without synchronization. [#thread]_ | |
75 | ||
76 | Typography | |
77 | ---------- | |
78 | ||
79 | Names written in :concept:`sans serif type` represent concepts_. | |
80 | ||
81 | In code blocks, *italic type* represents unspecified text that | |
82 | satisfies the requirements given in the detailed description that | |
83 | follows the code block. | |
84 | ||
85 | In a specification of the tokens generated by a macro, **bold | |
86 | type** is used to highlight the position of the expanded macro | |
87 | argument in the result. | |
88 | ||
89 | The special character β represents the value of |BOOST_PARAMETER_MAX_ARITY|_. | |
90 | ||
91 | ////////////////////////////////////////////////////////////////////////////// | |
92 | ||
93 | Terminology | |
94 | =========== | |
95 | ||
96 | .. |kw| replace:: keyword | |
97 | .. _kw: | |
98 | ||
99 | keyword | |
100 | The name of a function parameter. | |
101 | ||
102 | .. _keyword tag type: | |
103 | .. |keyword tag type| replace:: `keyword tag type`_ | |
104 | ||
105 | keyword tag type | |
106 | A type used to uniquely identify a function parameter. Typically | |
107 | its name will be the same as that of the parameter. | |
108 | ||
109 | .. _positional: | |
110 | .. |positional| replace:: `positional`_ | |
111 | ||
112 | positional argument | |
113 | An argument passed with no explicit |kw|. Its parameter is | |
114 | determined in the usual C++ way: by position with respect to a | |
115 | parameter list. | |
116 | ||
117 | .. _tag type: | |
118 | .. |tag type| replace:: `tag type`_ | |
119 | ||
120 | tag type | |
121 | Shorthand for “\ |keyword tag type|.” | |
122 | ||
123 | .. _keyword object: | |
124 | .. |keyword object| replace:: `keyword object`_ | |
125 | ||
126 | keyword object | |
127 | An instance of |keyword|_ ``<T>`` for some |tag | |
128 | type| ``T``. | |
129 | ||
130 | .. _tagged reference: | |
131 | .. |tagged reference| replace:: `tagged reference`_ | |
132 | ||
133 | tagged reference | |
134 | An object whose type is associated with a |keyword tag type| (the | |
135 | object's *keyword*), and that holds a reference (to the object's | |
136 | *value*). | |
137 | ||
138 | As a shorthand, a “tagged reference to ``x``\ ” means a tagged | |
139 | reference whose *value* is ``x``. | |
140 | ||
141 | .. _tagged default: | |
142 | .. |tagged default| replace:: `tagged default`_ | |
143 | ||
144 | tagged default | |
145 | A |tagged reference| whose *value* represents the value of a | |
146 | default argument. | |
147 | ||
148 | .. _tagged lazy default: | |
149 | .. |tagged lazy default| replace:: `tagged lazy default`_ | |
150 | ||
151 | tagged lazy default | |
152 | A |tagged reference| whose *value*, when invoked with no | |
153 | arguments, computes a default argument value. | |
154 | ||
155 | .. _intended argument type: | |
156 | .. |intended argument type| replace:: `intended argument type`_ | |
157 | ||
158 | intended argument type | |
159 | The *intended argument type* of a single-element |ArgumentPack|_ is the | |
160 | type of its element's *value*. The intended argument type of any other | |
161 | type ``X`` is ``X`` itself. | |
162 | ||
163 | .. Note:: | |
164 | ||
165 | In this reference, we will use concept names (and other names) | |
166 | to describe both types and objects, depending on context. So | |
167 | for example, “an |ArgumentPack|_\ ” can refer to a type that | |
168 | models |ArgumentPack|_ *or* an object of such a type. | |
169 | ||
170 | ////////////////////////////////////////////////////////////////////////////// | |
171 | ||
172 | Concepts | |
173 | ======== | |
174 | ||
175 | This section describes the generic type concepts_ used by the Parameter library. | |
176 | ||
177 | .. _concepts: http://www.boost.org/more/generic_programming.html#concept | |
178 | ||
179 | |ArgumentPack| | |
180 | -------------- | |
181 | ||
182 | An |ArgumentPack| is a collection of |tagged reference|\ s to the | |
183 | actual arguments passed to a function. Every |ArgumentPack| is | |
184 | also a valid MPL |ForwardSequence|__ consisting of the |keyword tag | |
185 | type|\ s in its |tagged reference|\ s. | |
186 | ||
187 | __ ../../../mpl/doc/refmanual/forward-sequence.html | |
188 | ||
189 | Requirements | |
190 | ............ | |
191 | ||
192 | In the table below, | |
193 | ||
194 | * ``A`` is a model of |ArgumentPack| | |
195 | * ``x`` is an instance of ``A`` | |
196 | * ``u`` is a |keyword object| of type ``K`` | |
197 | * ``v`` is a |tagged default| with |tag type| ``L`` and *value* of type ``D`` | |
198 | * ``w`` is a |tagged lazy default| with |tag type| ``M`` and *value* of type ``E const`` | |
199 | * ``z`` is an |ArgumentPack| containing a single element (as created by |keyword|_\ ``<…>::operator=``) | |
200 | ||
201 | Any exceptions are thrown from the invocation of ``w``\ 's *value* | |
202 | will be propagated to the caller. | |
203 | ||
204 | .. table:: |ArgumentPack| requirements | |
205 | ||
206 | +----------+-----------------------------+------------------+--------------------------------------+ | |
207 | |Expression| Type |Requirements |Semantics/Notes | | |
208 | +==========+=============================+==================+======================================+ | |
209 | |``x[u]`` |``binding<A,K>::type`` |``x`` contains an |Returns *b*\ 's *value* (by | | |
210 | | | |element *b* whose |reference). | | |
211 | | | ||kw|_ is ``K`` | | | |
212 | +----------+-----------------------------+------------------+--------------------------------------+ | |
213 | |``x[u]`` |``binding<A,L,D>::type`` |*none* |If ``x`` contains an element *b* whose| | |
214 | | | | ||kw|_ is the same as ``u``\ 's, | | |
215 | | | | |returns *b*\ 's *value* (by | | |
216 | | | | |reference). Otherwise, returns ``u``\| | |
217 | | | | |'s *value*. | | |
218 | +----------+-----------------------------+------------------+--------------------------------------+ | |
219 | |``x[w]`` |``lazy_binding<A,M,E>::type``|*none* |If ``x`` contains an element *b* whose| | |
220 | | | | ||kw|_ is the same as ``w``\ 's, | | |
221 | | | | |returns *b*\ 's *value* (by | | |
222 | | | | |reference). Otherwise, invokes ``w``\| | |
223 | | | | |'s *value* and returns the result. | | |
224 | +----------+-----------------------------+------------------+--------------------------------------+ | |
225 | |``x, z`` |Model of |ArgumentPack| |*none* |Returns an |ArgumentPack|_ containing | | |
226 | | | | |all the elements of both ``x`` and | | |
227 | | | | |``z``. | | |
228 | +----------+-----------------------------+------------------+--------------------------------------+ | |
229 | ||
230 | ||
231 | ||
232 | .. _parameterspec: | |
233 | ||
234 | |ParameterSpec| | |
235 | --------------- | |
236 | ||
237 | A |ParameterSpec| describes the type requirements for arguments | |
238 | corresponding to a given |kw|_ and indicates whether the argument | |
239 | is optional or required. The table below details the allowed forms | |
240 | and describes their condition for satisfaction by an actual | |
241 | argument type. In each row, | |
242 | ||
243 | .. _conditions: | |
244 | ||
245 | * ``K`` is the |ParameterSpec|\ 's |keyword tag type| | |
246 | * ``A`` is an |intended argument type| associated with ``K``, if any | |
247 | * ``F`` is a unary `MPL lambda expression`_ | |
248 | ||
249 | .. _`MPL lambda expression`: ../../../mpl/doc/refmanual/lambda-expression.html | |
250 | ||
251 | .. table:: |ParameterSpec| allowed forms and conditions of satisfaction | |
252 | ||
253 | +----------------------+--------------+--------------------------------+ | |
254 | |Type |``A`` required|Condition ``A`` must satisfy | | |
255 | +======================+==============+================================+ | |
256 | |``K`` |no |*n/a* | | |
257 | +----------------------+--------------+--------------------------------+ | |
258 | ||optional|_\ ``<K,F>``|no |``mpl::apply<F,A>::type::value``| | |
259 | | | |is ``true``. | | |
260 | +----------------------+--------------+--------------------------------+ | |
261 | ||required|_\ ``<K,F>``|yes |``mpl::apply<F,A>::type::value``| | |
262 | | | |is ``true``. | | |
263 | +----------------------+--------------+--------------------------------+ | |
264 | ||
265 | The information in a |ParameterSpec| is used to `limit`__ the | |
266 | arguments that will be matched by `forwarding functions`_. | |
267 | ||
268 | __ overloadcontrol_ | |
269 | .. _overloadcontrol: index.html#controlling-overload-resolution | |
270 | .. _forwarding functions: index.html#forwarding-functions | |
271 | ||
272 | ||
273 | ////////////////////////////////////////////////////////////////////////////// | |
274 | ||
275 | Class Templates | |
276 | =============== | |
277 | ||
278 | .. |keyword| replace:: ``keyword`` | |
279 | .. _keyword: | |
280 | ||
281 | ``keyword`` | |
282 | ----------- | |
283 | ||
284 | The type of every |keyword object| is a specialization of |keyword|. | |
285 | ||
286 | :Defined in: `boost/parameter/keyword.hpp`__ | |
287 | ||
288 | __ ../../../../boost/parameter/keyword.hpp | |
289 | ||
290 | .. parsed-literal:: | |
291 | ||
292 | template <class Tag> | |
293 | struct keyword | |
294 | { | |
295 | template <class T> |ArgumentPack|_ `operator=`_\(T& value) const; | |
296 | template <class T> |ArgumentPack|_ `operator=`_\(T const& value) const; | |
297 | ||
298 | template <class T> *tagged default* `operator|`_\(T& x) const; | |
299 | template <class T> *tagged default* `operator|`_\(T const& x) const; | |
300 | ||
301 | template <class F> *tagged lazy default* `operator||`_\(F const&) const; | |
302 | ||
303 | static keyword<Tag>& get_\(); | |
304 | }; | |
305 | ||
306 | ||
307 | .. |operator=| replace:: ``operator=`` | |
308 | .. _operator=: | |
309 | ||
310 | ``operator=`` | |
311 | .. parsed-literal:: | |
312 | ||
313 | template <class T> |ArgumentPack|_ operator=(T& value) const; | |
314 | template <class T> |ArgumentPack|_ operator=(T const& value) const; | |
315 | ||
316 | :Requires: nothing | |
317 | ||
318 | :Returns: | |
319 | an |ArgumentPack|_ containing a single |tagged reference| to | |
320 | ``value`` with |kw|_ ``Tag`` | |
321 | ||
322 | .. _operator|: | |
323 | ||
324 | ``operator|`` | |
325 | .. parsed-literal:: | |
326 | ||
327 | template <class T> *tagged default* operator|(T& x) const; | |
328 | template <class T> *tagged default* operator|(T const& x) const; | |
329 | ||
330 | :Returns: a |tagged default| with *value* ``x`` and |kw|_ ``Tag``. | |
331 | ||
332 | .. _operator||: | |
333 | ||
334 | ``operator||`` | |
335 | .. parsed-literal:: | |
336 | ||
337 | template <class F> *tagged lazy default* operator||(F const& g) const; | |
338 | ||
339 | :Requires: ``g()`` is valid, with type ``boost::``\ |result_of|_\ | |
340 | ``<F()>::type``. [#no_result_of]_ | |
341 | ||
342 | ||
343 | :Returns: a |tagged lazy default| with *value* ``g`` and |kw|_ ``Tag``. | |
344 | ||
345 | .. _get: | |
346 | ||
347 | ``get`` | |
348 | .. parsed-literal:: | |
349 | ||
350 | static keyword<Tag>& get\(); | |
351 | ||
352 | :Returns: a “singleton instance”: the same object will be | |
353 | returned on each invocation of ``get()``. | |
354 | ||
355 | :Thread Safety: ``get()`` can be called from multiple threads | |
356 | simultaneously. | |
357 | ||
358 | ``parameters`` | |
359 | -------------- | |
360 | ||
361 | Provides an interface for assembling the actual arguments to a | |
362 | `forwarding function` into an |ArgumentPack|, in which any | |
363 | |positional| arguments will be tagged according to the | |
364 | corresponding template argument to ``parameters``. | |
365 | ||
366 | .. _forwarding function: `forwarding functions`_ | |
367 | ||
368 | :Defined in: `boost/parameter/parameters.hpp`__ | |
369 | ||
370 | __ ../../../../boost/parameter/parameters.hpp | |
371 | ||
372 | .. parsed-literal:: | |
373 | ||
374 | template <class P0 = *unspecified*, class P1 = *unspecified*, …class P\ β = *unspecified*> | |
375 | struct parameters | |
376 | { | |
377 | template <class A0, class A1 = *unspecified*, …class A\ β = *unspecified*> | |
378 | struct `match`_ | |
379 | { | |
380 | typedef … type; | |
381 | }; | |
382 | ||
383 | template <class A0> | |
384 | |ArgumentPack|_ `operator()`_\(A0& a0) const; | |
385 | ||
386 | template <class A0, class A1> | |
387 | |ArgumentPack|_ `operator()`_\(A0& a0, A1& a1) const; | |
388 | ||
389 | :vellipsis:`⋮` | |
390 | ||
391 | template <class A0, class A1, …class A\ β> | |
392 | |ArgumentPack|_ `operator()`_\(A0& a0, A1& a1, …A\ β& a\ β) const; | |
393 | }; | |
394 | ||
395 | ||
396 | :Requires: ``P0``, ``P1``, … ``P``\ β are models of |ParameterSpec|_. | |
397 | ||
398 | ||
399 | .. Note:: | |
400 | ||
401 | In this section, ``R``\ *i* and ``K``\ *i* are defined as | |
402 | follows, for any argument type ``A``\ *i*: | |
403 | ||
404 | ||
405 | | let ``D0`` the set [d0, …, d\ *j*] of all **deduced** *parameter specs* in [``P0``, …, ``P``\ β] | |
406 | | ``R``\ *i* is ``A``\ *i*\ 's |intended argument type| | |
407 | | | |
408 | | if ``A``\ *i* is a result type of ``keyword<T>::``\ |operator=|_ | |
409 | | then | |
410 | | ``K``\ *i* is ``T`` | |
411 | | else | |
412 | | if some ``A``\ *j* where *j*\ ≤\ *i* is a result type of ``keyword<T>::``\ |operator=|_ | |
413 | | *or* some ``P``\ *j* in *j*\ ≤\ *i* is **deduced** | |
414 | | then | |
415 | | if some *parameter spec* ``d``\ *j* in ``D``\ *i* matches ``A``\ *i* | |
416 | | then | |
417 | | ``K``\ *i* is ``d``\ *j*\ 's |keyword tag type|. | |
418 | | ``D``\ :sub:`i+1` is ``D``\ *i* - [``d``\ *j*] | |
419 | | else | |
420 | | ``K``\ *i* is ``P``\ *i*\ 's |keyword tag type|. | |
421 | ||
422 | ||
423 | .. _match: | |
424 | ||
425 | ``match`` | |
426 | A |Metafunction|_ used to remove a `forwarding function`_ from overload resolution. | |
427 | ||
428 | :Returns: if ``P0``, ``P1``, …\ ``P``\ β are *satisfied* (see | |
429 | below), then ``parameters<P0,P1,…Pβ>``. Otherwise, | |
430 | ``match<A0,A1,…Aβ>::type`` is not defined. | |
431 | ||
432 | ``P0``, ``P1``, …\ ``P``\ β are **satisfied** if, for | |
433 | every *j* in 0…β, either: | |
434 | ||
435 | * ``P``\ *j* is the *unspecified* default | |
436 | * **or**, ``P``\ *j* is a *keyword tag type* | |
437 | ||
438 | * **or**, ``P``\ *j* is |optional|_ ``<X,F>`` and either | |
439 | ||
440 | - ``X`` is not ``K``\ *i* for any *i*, | |
441 | - **or** ``X`` is some ``K``\ *i* and ``mpl::apply<F,R``\ *i*\ | |
442 | ``>::type::value`` is ``true`` | |
443 | ||
444 | * **or**, ``P``\ *j* is |required|_ ``<X,F>``, and | |
445 | ||
446 | - ``X`` is some ``K``\ *i*, **and** | |
447 | - ``mpl::apply<F,R``\ *i*\ ``>::type::value`` is ``true`` | |
448 | ||
449 | .. _operator(): | |
450 | ||
451 | ``operator()`` | |
452 | .. parsed-literal:: | |
453 | ||
454 | template <class A0> |ArgumentPack|_ operator()(A0 const& a0) const; | |
455 | ||
456 | :vellipsis:`⋮` | |
457 | ||
458 | template <class A0, …class A\ β> |ArgumentPack|_ `operator()`_\(A0 const& a0, …A\ β const& a\ β) const; | |
459 | ||
460 | :Returns: | |
461 | An |ArgumentPack|_ containing, for each ``a``\ *i*, | |
462 | ||
463 | - if ``a``\ *i*, is a single-element |ArgumentPack|, its element | |
464 | - Otherwise, a |tagged reference| with |kw|_ ``K``\ *i* and *value* ``a``\ *i* | |
465 | ||
466 | ||
467 | .. |optional| replace:: ``optional`` | |
468 | .. |required| replace:: ``required`` | |
469 | ||
470 | .. _optional: | |
471 | .. _required: | |
472 | ||
473 | ``optional``, ``required`` | |
474 | -------------------------- | |
475 | ||
476 | These templates describe the requirements on a function parameter. | |
477 | ||
478 | :Defined in: `boost/parameter/parameters.hpp`__ | |
479 | ||
480 | __ ../../../../boost/parameter/parameters.hpp | |
481 | ||
482 | :Specializations model: |ParameterSpec|_ | |
483 | ||
484 | .. parsed-literal:: | |
485 | ||
486 | template <class Tag, class Predicate = *unspecified*> | |
487 | struct optional; | |
488 | ||
489 | template <class Tag, class Predicate = *unspecified*> | |
490 | struct required; | |
491 | ||
492 | The default value of ``Predicate`` is an unspecified |Metafunction|_ that returns | |
493 | ``mpl::true_`` for any argument. | |
494 | ||
495 | .. |Metafunction| replace:: :concept:`Metafunction` | |
496 | .. _Metafunction: ../../../mpl/doc/refmanual/metafunction.html | |
497 | ||
498 | ||
499 | ``deduced`` | |
500 | ----------- | |
501 | ||
502 | This template is used to wrap the *keyword tag* argument to | |
503 | ``optional`` or ``required``. | |
504 | ||
505 | :Defined in: `boost/parameter/parameters.hpp`__ | |
506 | ||
507 | __ ../../../../boost/parameter/parameters.hpp | |
508 | ||
509 | .. parsed-literal:: | |
510 | ||
511 | template <class Tag> | |
512 | struct deduced; | |
513 | ||
514 | ||
515 | ////////////////////////////////////////////////////////////////////////////// | |
516 | ||
517 | Metafunctions | |
518 | ============= | |
519 | ||
520 | A |Metafunction|_ is conceptually a function that operates on, and | |
521 | returns, C++ types. | |
522 | ||
523 | ``binding`` | |
524 | ----------- | |
525 | ||
526 | Returns the result type of indexing an argument pack with a | |
527 | |keyword tag type| or with a |tagged default|. | |
528 | ||
529 | :Defined n: `boost/parameter/binding.hpp`__ | |
530 | ||
531 | __ ../../../../boost/parameter/binding.hpp | |
532 | ||
533 | .. parsed-literal:: | |
534 | ||
535 | template <class A, class K, class D = void> | |
536 | struct binding | |
537 | { | |
538 | typedef … type; | |
539 | }; | |
540 | ||
541 | :Requires: ``A`` is a model of |ArgumentPack|_. | |
542 | ||
543 | :Returns: the reference type of the |tagged reference| in ``A`` | |
544 | having |keyword tag type| ``K``, if any. If no such |tagged | |
545 | reference| exists, returns ``D``. | |
546 | ||
547 | ``lazy_binding`` | |
548 | ---------------- | |
549 | ||
550 | Returns the result type of indexing an argument pack with a |tagged | |
551 | lazy default|. | |
552 | ||
553 | :Defined in: | |
554 | `boost/parameter/binding.hpp`__ | |
555 | ||
556 | __ ../../../../boost/parameter/binding.hpp | |
557 | ||
558 | .. parsed-literal:: | |
559 | ||
560 | template <class A, class K, class F> | |
561 | struct lazy_binding | |
562 | { | |
563 | typedef … type; | |
564 | }; | |
565 | ||
566 | :Requires: ``A`` is a model of |ArgumentPack|_. | |
567 | ||
568 | :Returns: the reference type of the |tagged reference| in ``A`` | |
569 | having |keyword tag type| ``K``, if any. If no such |tagged | |
570 | reference| exists, returns ``boost::``\ |result_of|_\ ``<F()>::type``. [#no_result_of]_ | |
571 | ||
572 | ||
573 | ``value_type`` | |
574 | -------------- | |
575 | ||
576 | Returns the result type of indexing an argument pack with a | |
577 | |keyword tag type| or with a |tagged default|. | |
578 | ||
579 | :Defined n: `boost/parameter/value_type.hpp`__ | |
580 | ||
581 | __ ../../../../boost/parameter/value_type.hpp | |
582 | ||
583 | .. parsed-literal:: | |
584 | ||
585 | template <class A, class K, class D = void> | |
586 | struct value_type | |
587 | { | |
588 | typedef … type; | |
589 | }; | |
590 | ||
591 | :Requires: ``A`` is a model of |ArgumentPack|_. | |
592 | ||
593 | :Returns: the type of the |tagged reference| in ``A`` | |
594 | having |keyword tag type| ``K``, if any. If no such |tagged | |
595 | reference| exists, returns ``D``. Equivalent to:: | |
596 | ||
597 | typename remove_reference< | |
598 | typename binding<A, K, D>::type | |
599 | >::type | |
600 | ||
601 | … when ``D`` is not a reference type. | |
602 | ||
603 | ||
604 | ////////////////////////////////////////////////////////////////////////////// | |
605 | ||
606 | Code Generation Macros | |
607 | ====================== | |
608 | ||
609 | Macros in this section can be used to ease the writing of code | |
610 | using the Parameter libray by eliminating repetitive boilerplate. | |
611 | ||
612 | ||
613 | ``BOOST_PARAMETER_FUNCTION(result,name,tag_namespace,arguments)`` | |
614 | ----------------------------------------------------------------- | |
615 | ||
616 | :Defined in: `boost/parameter/preprocessor.hpp`__ | |
617 | ||
618 | __ ../../../../boost/parameter/preprocessor.hpp | |
619 | ||
620 | :Requires: ``result`` is the parenthesized return type of the function. | |
621 | ``name`` is the base name of the function, this is the name of the | |
622 | generated forwarding functions. ``tag_namespace`` is the namespace in | |
623 | which the keywords used by the function resides. ``arguments`` is | |
624 | a list of *argument specifiers*, as defined below. | |
625 | ||
626 | ||
627 | :Argument specifiers syntax: | |
628 | .. parsed-literal:: | |
629 | ||
630 | argument-specifiers ::= *specifier-group* {*specifier-group*} | |
631 | ||
632 | specifier-group0 ::= *specifier-group1* | | |
633 | ( '**(**' '**deduced**' *specifier-group1* {*specifier-group1*} '**)**' ) | |
634 | ||
635 | specifier-group1 ::= ( '**(**' '**optional**' *optional-specifier* {*optional-specifier*} '**)**' ) | | |
636 | ( '**(**' '**required**' *required-specifier* {*required-specifier*} '**)**' ) | |
637 | ||
638 | optional-specifier ::= '**(**' *name* '**,**' *restriction* '**,**' *default-value* ')' | |
639 | required-specifier ::= '**(**' *name* '**,**' *restriction* ')' | |
640 | ||
641 | restriction ::= ('*****' '**(**' *lambda-expression* '**)**' ) | | |
642 | ( '**(**' *typename* '**)**' ) | | |
643 | '*****' | |
644 | ||
645 | ``name`` is any valid C++ identifier. ``default-value`` is any valid | |
646 | C++ expression. ``typename`` is the name of a type. | |
647 | ``lambda-expression`` is an `MPL lambda expression`_. | |
648 | ||
649 | .. _`MPL lambda expression`: ../../../mpl/doc/refmanual/lambda-expression.html | |
650 | ||
651 | :Generated names in enclosing scope: | |
652 | * ``boost_param_result_ ## __LINE__ ## name`` | |
653 | * ``boost_param_params_ ## __LINE__ ## name`` | |
654 | * ``boost_param_parameters_ ## __LINE__ ## name`` | |
655 | * ``boost_param_impl ## name`` | |
656 | * ``boost_param_default_ ## __LINE__ ## name`` | |
657 | ||
658 | ||
659 | Approximate expansion: | |
660 | **Where**: | |
661 | ||
662 | * ``n`` denotes the *minimum* arity, as determined from ``arguments``. | |
663 | * ``m`` denotes the *maximum* arity, as determined from ``arguments``. | |
664 | ||
665 | .. parsed-literal:: | |
666 | ||
667 | template <class T> | |
668 | struct boost_param_result\_ ## __LINE__ ## **name** | |
669 | { | |
670 | typedef **result** type; | |
671 | }; | |
672 | ||
673 | struct boost_param_params\_ ## __LINE__ ## **name** | |
674 | : boost::parameter::parameters< | |
675 | *list of parameter specifications, based on arguments* | |
676 | > | |
677 | {}; | |
678 | ||
679 | typedef boost_param_params\_ ## __LINE__ ## **name** | |
680 | boost_param_parameters\_ ## __LINE__ ## **name**; | |
681 | ||
682 | template <class A0, …, class A\ **n**> | |
683 | *result type* **name**\ ( | |
684 | A0 *cv*\ & a0, …, A\ **n** *cv*\ & a\ **n** | |
685 | , typename boost_param_parameters\_ ## __LINE__ ## **name**::match< | |
686 | A0 *cv*, …, A\ **n** *cv* | |
687 | >::type = boost_param_parameters\_ ## __LINE__ ## **name**\ () | |
688 | ) | |
689 | { | |
690 | *… forward to implementation …* | |
691 | } | |
692 | ||
693 | :vellipsis:`⋮` | |
694 | ||
695 | template <class A0, …, class A\ **m**> | |
696 | *result type* **name**\ ( | |
697 | A0 *cv*\ & a0, …, A\ **m** *cv*\ & a\ **m** | |
698 | , typename boost_param_parameters\_ ## __LINE__ ## **name**::match< | |
699 | A0 *cv*, …, A\ **m** *cv* | |
700 | >::type = boost_param_parameters\_ ## __LINE__ ## **name**\ () | |
701 | ) | |
702 | { | |
703 | *… forward to implementation …* | |
704 | } | |
705 | ||
706 | template < | |
707 | class ResultType | |
708 | , class *argument name*\ **0** ## _type | |
709 | … | |
710 | , class *argument name*\ **m** ## _type | |
711 | > | |
712 | ResultType boost_param_default\_ ## __LINE__ ## **name**\ ( | |
713 | (ResultType(*)()) | |
714 | , *argument name*\ **0** ## _type& *argument name*\ **0** | |
715 | … | |
716 | , *argument name*\ **m** ## _type& *argument name*\ **m** | |
717 | ) | |
718 | ||
719 | ||
720 | ||
721 | ``BOOST_PARAMETER_MEMBER_FUNCTION(result,name,tag_namespace,arguments)`` | |
722 | ------------------------------------------------------------------------ | |
723 | ||
724 | :Defined in: `boost/parameter/preprocessor.hpp`__ | |
725 | ||
726 | __ ../../../../boost/parameter/preprocessor.hpp | |
727 | ||
728 | See ``BOOST_PARAMETER_FUNCTION(result,name,tag_namespace,arguments)`` | |
729 | ||
730 | ||
731 | ||
732 | ``BOOST_PARAMETER_CONSTRUCTOR(cls, impl, tag_namespace, arguments)`` | |
733 | -------------------------------------------------------------------- | |
734 | ||
735 | :Defined in: `boost/parameter/preprocessor.hpp`__ | |
736 | ||
737 | __ ../../../../boost/parameter/preprocessor.hpp | |
738 | ||
739 | :Requires: ``cls`` is the name of this class. ``impl`` is the | |
740 | parenthesized implementation base class for ``cls``. | |
741 | ``tag_namespace`` is the namespace in which the keywords | |
742 | used by the function resides. ``arguments`` is | |
743 | a list of *argument specifiers*, as defined in | |
744 | ``BOOST_PARAMETER_FUNCTION(result,name,tag_namespace,arguments)``. | |
745 | ||
746 | :Generated names in enclosing scope: | |
747 | * ``boost_param_params_ ## __LINE__ ## ctor`` | |
748 | * ``constructor_parameters ## __LINE__`` | |
749 | ||
750 | Approximate expansion: | |
751 | **Where**: | |
752 | ||
753 | * ``n`` denotes the *minimum* arity, as determined from ``arguments``. | |
754 | * ``m`` denotes the *maximum* arity, as determined from ``arguments``. | |
755 | ||
756 | .. parsed-literal:: | |
757 | ||
758 | struct boost_param_params\_ ## __LINE__ ## ctor | |
759 | : boost::parameter::parameters< | |
760 | *list of parameter specifications, based on arguments* | |
761 | > | |
762 | {}; | |
763 | ||
764 | typedef boost_param_params\_ ## __LINE__ ## **name** | |
765 | constructor_parameters ## __LINE__; | |
766 | ||
767 | template <class A0, …, class A\ **n**> | |
768 | *cls*\ (A0 const& a0, …, A\ **n** const& a\ **n**) | |
769 | : *impl*\ (constructor_parameters ## __LINE__(a0, …, a\ **n**)) | |
770 | {} | |
771 | ||
772 | :vellipsis:`⋮` | |
773 | ||
774 | template <class A0, …, class A\ **m**> | |
775 | *cls*\ (A0 const& a0, …, A\ **n** const& a\ **m**) | |
776 | : *impl*\ (constructor_parameters ## __LINE__(a0, …, a\ **m**)) | |
777 | {} | |
778 | ||
779 | ||
780 | ``BOOST_PARAMETER_NAME(name)`` | |
781 | ------------------------------ | |
782 | ||
783 | Declares a tag-type and keyword object. | |
784 | ||
785 | Expands to: | |
786 | ||
787 | **If** *name* is of the form: | |
788 | ||
789 | .. parsed-literal:: | |
790 | ||
791 | (*tag-name*, *namespace-name*) *object-name* | |
792 | ||
793 | **then** | |
794 | ||
795 | .. parsed-literal:: | |
796 | ||
797 | namespace *namespace-name* | |
798 | { | |
799 | struct *tag-name* | |
800 | { | |
801 | static char const* keyword_name() | |
802 | { | |
803 | return ##\ *tag-name*; | |
804 | } | |
805 | ||
806 | typedef *unspecified* _; | |
807 | typedef *unspecified* _1; | |
808 | }; | |
809 | } | |
810 | ||
811 | ::boost::parameter::keyword<*tag-namespace*\ ::\ *tag-name*\ > const& *object-name* | |
812 | = ::boost::parameter::keyword<*tag-namespace*\ ::\ *tag-name*\ >::instance; | |
813 | ||
814 | **Else** | |
815 | ||
816 | .. parsed-literal:: | |
817 | ||
818 | namespace tag | |
819 | { | |
820 | struct *name* | |
821 | { | |
822 | static char const* keyword_name() | |
823 | { | |
824 | return ##\ *name*; | |
825 | } | |
826 | ||
827 | typedef *unspecified* _; | |
828 | typedef *unspecified* _1; | |
829 | }; | |
830 | } | |
831 | ||
832 | ::boost::parameter::keyword<tag::\ *name*\ > const& _\ *name* | |
833 | = ::boost::parameter::keyword<tag::\ *name*\ >::instance; | |
834 | ||
835 | ||
836 | ``BOOST_PARAMETER_TEMPLATE_KEYWORD(name)`` | |
837 | ------------------------------------------ | |
838 | ||
839 | Expands to: | |
840 | ||
841 | .. parsed-literal:: | |
842 | ||
843 | namespace tag | |
844 | { | |
845 | struct *name*; | |
846 | } | |
847 | ||
848 | template <class T> | |
849 | struct *name* | |
850 | : ::boost::parameter::template_keyword<tag::\ *name*, T> | |
851 | {}; | |
852 | ||
853 | ||
854 | ``BOOST_PARAMETER_FUN(r,n,l,h,p)`` | |
855 | ---------------------------------- | |
856 | ||
857 | .. admonition:: Deprecated | |
858 | ||
859 | This macro has been deprecated in favor of | |
860 | ``BOOST_PARAMETER_FUNCTION``. | |
861 | ||
862 | Generates a sequence of `forwarding function`_ templates named | |
863 | ``n``, with arities ranging from ``l`` to ``h`` , returning ``r``, | |
864 | and using ``p`` to control overload resolution and assign tags to | |
865 | positional arguments. | |
866 | ||
867 | :Defined in: `boost/parameter/macros.hpp`__ | |
868 | ||
869 | __ ../../../../boost/parameter/macros.hpp | |
870 | ||
871 | :Requires: ``l`` and ``h`` are nonnegative integer tokens such | |
872 | that ``l`` < ``h`` | |
873 | ||
874 | Generates | |
875 | .. parsed-literal:: | |
876 | ||
877 | template <class A1, class A2, …class A##\ **l**> | |
878 | r name( | |
879 | A1 const& a1, A2 const& a2, …A\ **l** const& x\ **l** | |
880 | , typename **p**::match<A1,A2,…A\ **l**>::type p = **p**\ ()) | |
881 | { | |
882 | return **name**\ _with_named_params(**p**\ (x1,x2,…x\ **l**)); | |
883 | } | |
884 | ||
885 | template <class A1, class A2, …class A\ **l**, class A\ ##\ BOOST_PP_INC_\ (**l**)> | |
886 | r name( | |
887 | A1 const& a1, A2 const& a2, …A\ **l** const& x\ **l** | |
888 | , A\ ##\ BOOST_PP_INC_\ (**l**) const& x\ ##\ BOOST_PP_INC_\ (**l**) | |
889 | , typename **p**::match<A1,A2,…A\ **l**,A\ ##\ BOOST_PP_INC_\ (**l**)>::type p = **p**\ ()) | |
890 | { | |
891 | return **name**\ _with_named_params(**p**\ (x1,x2,…x\ **l**,x\ ##\ BOOST_PP_INC_\ (**l**))); | |
892 | } | |
893 | ||
894 | :vellipsis:`⋮` | |
895 | ||
896 | template <class A1, class A2, …class A\ **h**> | |
897 | r name( | |
898 | A1 const& a1, A2 const& a2, …A\ **h** const& x\ **h** | |
899 | , typename **p**::match<A1,A2,…A\ **h**>::type p = **p**\ ()) | |
900 | { | |
901 | return **name**\ _with_named_params(**p**\ (a1,a2,…a\ **h**)); | |
902 | } | |
903 | ||
904 | ||
905 | .. _BOOST_PP_INC: ../../../preprocessor/doc/ref/inc.html | |
906 | ||
907 | ``BOOST_PARAMETER_KEYWORD(n,k)`` | |
908 | -------------------------------- | |
909 | ||
910 | .. admonition:: Deprecated | |
911 | ||
912 | This macro has been deprecated in favor of | |
913 | ``BOOST_PARAMETER_NAME``. | |
914 | ||
915 | Generates the declaration of a |keyword tag type| named ``k`` in | |
916 | namespace ``n``, and a corresponding |keyword object| definition in | |
917 | the enclosing namespace. | |
918 | ||
919 | :Defined in: `boost/parameter/keyword.hpp`__ | |
920 | ||
921 | __ ../../../../boost/parameter/keyword.hpp | |
922 | ||
923 | Generates | |
924 | .. parsed-literal:: | |
925 | ||
926 | namespace **n** { struct **k**; } | |
927 | namespace { | |
928 | boost::parameter::keyword<*tag-namespace*::**k**>& **k** | |
929 | = boost::parameter::keyword<*tag-namespace*::**k**>::get(); | |
930 | } | |
931 | ||
932 | ``BOOST_PARAMETER_MATCH(p,a,x)`` | |
933 | -------------------------------- | |
934 | ||
935 | Generates a defaulted parameter declaration for a `forwarding | |
936 | function`_. | |
937 | ||
938 | :Defined in: `boost/parameter/match.hpp`__ | |
939 | ||
940 | __ ../../../../boost/parameter/match.hpp | |
941 | ||
942 | :Requires: ``a`` is a `Boost.Preprocessor sequence`__ | |
943 | of the form | |
944 | ||
945 | .. parsed-literal:: | |
946 | ||
947 | (A0)(A1)…(A\ *n*) | |
948 | ||
949 | __ http://www.boost.org/libs/preprocessor/doc/data.html | |
950 | ||
951 | Generates | |
952 | .. parsed-literal:: | |
953 | ||
954 | typename **p**::match<**A0**\ ,\ **A1**\ …,\ **A**\ *n*>::type **x** = **p**\ () | |
955 | ||
956 | ||
957 | Configuration Macros | |
958 | ==================== | |
959 | ||
960 | ``BOOST_PARAMETER_MAX_ARITY`` | |
961 | ----------------------------- | |
962 | ||
963 | Determines the maximum number of arguments supported by the | |
964 | library. Will only be ``#defined`` by the library if it is not | |
965 | already ``#defined``. | |
966 | ||
967 | .. |BOOST_PARAMETER_MAX_ARITY| replace:: ``BOOST_PARAMETER_MAX_ARITY`` | |
968 | ||
969 | :Defined in: `boost/parameter/config.hpp`__ | |
970 | ||
971 | __ ../../../../boost/parameter/config.hpp | |
972 | ||
973 | :Default Value: ``8`` | |
974 | ||
975 | Tutorial | |
976 | ======== | |
977 | ||
978 | Follow `this link`__ to the Boost.Parameter tutorial | |
979 | documentation. | |
980 | ||
981 | __ index.html#tutorial | |
982 | ||
983 | ////////////////////////////////////////////////////////////// | |
984 | ||
985 | .. [#thread] References to tag objects may be initialized multiple | |
986 | times. This scenario can only occur in the presence of | |
987 | threading. Because the C++ standard doesn't consider threading, | |
988 | it doesn't explicitly allow or forbid multiple initialization of | |
989 | references. That said, it's hard to imagine an implementation | |
990 | where it could make a difference. | |
991 | ||
992 | .. [#no_result_of] Where |BOOST_NO_RESULT_OF|_ is ``#defined``, | |
993 | ``boost::``\ |result_of|_\ ``<F()>::type`` is replaced by | |
994 | ``F::result_type``. | |
995 | ||
996 | .. |result_of| replace:: ``result_of`` | |
997 | .. _result_of: ../../../utility/utility.htm#result_of | |
998 | ||
999 | .. |BOOST_NO_RESULT_OF| replace:: ``BOOST_NO_RESULT_OF`` | |
1000 | .. _BOOST_NO_RESULT_OF: ../../../utility/utility.htm#BOOST_NO_RESULT_OF | |
1001 |