Update of /cvsroot/boost/boost/libs/parameter/doc
In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv15367
Modified Files:
Tag: RC_1_34_0
index.rst reference.rst
Log Message:
Merged HEAD to RC_1_34_0
Index: index.rst
===================================================================
RCS file: /cvsroot/boost/boost/libs/parameter/doc/index.rst,v
retrieving revision 1.29.2.4
retrieving revision 1.29.2.5
diff -u -d -r1.29.2.4 -r1.29.2.5
--- index.rst 3 Jan 2007 16:45:09 -0000 1.29.2.4
+++ index.rst 3 May 2007 14:39:41 -0000 1.29.2.5
@@ -1067,8 +1067,8 @@
.. parsed-literal::
- def("f", f, **some_policies**, **"Documentation for f"**);
- def("f", f, **"Documentation for f"**, **some_policies**);
+ def("f", &f, **some_policies**, **"Documentation for f"**);
+ def("f", &f, **"Documentation for f"**, **some_policies**);
.. @example.prepend('''
int main()
@@ -1081,7 +1081,7 @@
.. parsed-literal::
def(
- "f", f
+ "f", &f
, **_policies = some_policies**, "Documentation for f");
.. @example.append('}')
@@ -1114,7 +1114,8 @@
};
.. @example.prepend('''
- #include <boost/parameter.hpp>''')
+ #include <boost/parameter.hpp>
+ #include <iostream>''')
.. @test('compile')
@@ -1701,7 +1702,10 @@
, optional<tag::\ index, is_convertible<_,int> >
> spec;
- int z0 = print_name_and_index( **spec(**\ "sam", 12\ **)** );
+ char const sam[] = "sam";
+ int twelve = 12;
+
+ int z0 = print_name_and_index( **spec(**\ sam, twelve\ **)** );
int z1 = print_name_and_index(
**spec(**\ _index=12, _name="sam"\ **)**
@@ -1720,6 +1724,11 @@
.. @test('run', howmany='all')
+Note that because of the `forwarding problem`_,
``parameter::parameters::operator()``
+can't accept non-const rvalues.
+
+.. _`forwarding problem`:
http://std.dkuug.dk/jtc1/sc22/wg21/docs/papers/2002/n1385.htm
+
Extracting Parameter Types
==========================
@@ -1770,7 +1779,9 @@
BOOST_PARAMETER_NAME(index)
template <class ArgumentPack>
- typename parameter::binding<ArgumentPack, tag::index, int>::type
+ typename remove_reference<
+ typename parameter::binding<ArgumentPack, tag::index, int>::type
+ >::type
twice_index(ArgumentPack const& args)
{
return 2 * args[_index|42];
@@ -1778,21 +1789,44 @@
int six = twice_index(_index = 3);
-.. TODO: binding<> returns a reference. We should use value_type<> here.
-
.. @example.prepend('''
#include <boost/parameter.hpp>
+ #include <boost/type_traits/remove_reference.hpp>
#include <cassert>
- namespace parameter = boost::parameter;''')
+ namespace parameter = boost::parameter;
+ using boost::remove_reference;''')
+
+Note that the ``remove_reference< ⦠>`` dance is necessary because
+``binding< ⦠>`` will return a reference type when the argument
+is bound in the argument pack. If we don't strip the reference we
+end up returning a reference to the temporary created in the ``2 * â¦``
+expression. A convenient shortcut would be to use the ``value_type< ⦠>``
+metafunction:
+
+.. parsed-literal::
+
+ template <class ArgumentPack>
+ typename **parameter::value_type<ArgumentPack, tag::index, int>**::type
+ twice_index(ArgumentPack const& args)
+ {
+ return 2 * args[_index|42];
+ }
+
+.. @example.wrap('namespace with_value_type {', '''
+ int six = twice_index(_index = 3);
+ }''')
+
+.. TODO: binding<> returns a reference. We should use value_type<> here.
.. @example.append('''
int main()
{
assert(six == 6);
+ assert(with_value_type::six == 6);
}''')
-.. @test('run')
+.. @test('run', howmany='all')
__ binding_intro_
@@ -1837,21 +1871,31 @@
In the example above, the string ``"hello, world"`` is constructed
despite the fact that the user passed us a value for ``s3``. To
remedy that, we can compute the default value *lazily* (that is,
-only on demand), by combining the logical-or (â``||``â) operator
-with a function object built by the Boost Lambda_ library: [#bind]_
+only on demand), by using ``boost::bind()`` to create a function
+object.
+
+.. danielw: I'm leaving the text below in the source, because we might
+.. want to change back to it after 1.34, and if I remove it now we
+.. might forget about it.
+
+.. by combining the logical-or (â``||``â) operator
+.. with a function object built by the Boost Lambda_ library: [#bind]_
.. parsed-literal::
- namespace lambda = boost::lambda;
+ using boost::bind;
+ using boost::ref;
typename parameter::binding<
ArgumentPack, tag::s3, std::string
- >::type s3 = args[_s3 **|| (lambda::var(s1)+lambda::var(s2))** ];
+ >::type s3 = args[_s3 **|| bind(std::plus<std::string>(), ref(s1),
ref(s2))** ];
.. @example.prepend('''
- #include <boost/lambda/lambda.hpp>
+ #include <boost/bind.hpp>
+ #include <boost/ref.hpp>
#include <boost/parameter.hpp>
#include <string>
+ #include <functional>
namespace parameter = boost::parameter;
@@ -1876,7 +1920,7 @@
.. @test('run')
-.. _Lambda: ../../../lambda/index.html
+.. .. _Lambda: ../../../lambda/index.html
.. sidebar:: Mnemonics
@@ -1886,10 +1930,15 @@
Similarly, in ``color_map[param||f]``, ``f`` is only invoked if
no ``color_map`` argument was supplied.
-The expression ``lambda::var(s1)+lambda::var(s2)`` yields a
-*function object* that, when invoked, adds the two strings
-together. That function will only be invoked if no ``s3`` argument
-is supplied by the caller.
+The expression ``bind(std::plus<std::string>(), ref(s1), ref(s2))`` yields
+a *function object* that, when invoked, adds the two strings together.
+That function will only be invoked if no ``s3`` argument is supplied by
+the caller.
+
+.. The expression ``lambda::var(s1)+lambda::var(s2)`` yields a
+.. *function object* that, when invoked, adds the two strings
+.. together. That function will only be invoked if no ``s3`` argument
+.. is supplied by the caller.
================
Best Practices
@@ -2251,17 +2300,17 @@
.. _`ConceptC++`: http://www.generic-programming.org/software/ConceptGCC/
-.. [#bind] The Lambda library is known not to work on `some
- less-conformant compilers`__. When using one of those you could
- use `Boost.Bind`_ to generate the function object::
+.. .. [#bind] The Lambda library is known not to work on `some
+.. less-conformant compilers`__. When using one of those you could
+.. use `Boost.Bind`_ to generate the function object::
- boost::bind(std::plus<std::string>(),s1,s2)
+.. boost::bind(std::plus<std::string>(),s1,s2)
.. [#is_keyword_expression] Here we're assuming there's a predicate
metafunction ``is_keyword_expression`` that can be used to
identify models of Boost.Python's KeywordExpression concept.
-__ http://www.boost.org/regression/release/user/lambda.html
+.. .. __ http://www.boost.org/regression/release/user/lambda.html
.. _Boost.Bind: ../../../bind/index.html
Index: reference.rst
===================================================================
RCS file: /cvsroot/boost/boost/libs/parameter/doc/reference.rst,v
retrieving revision 1.25.2.1
retrieving revision 1.25.2.2
diff -u -d -r1.25.2.1 -r1.25.2.2
--- reference.rst 18 Sep 2006 20:42:44 -0000 1.25.2.1
+++ reference.rst 3 May 2007 14:39:41 -0000 1.25.2.2
@@ -253,7 +253,7 @@
+----------------------+--------------+--------------------------------+
|Type |``A`` required|Condition ``A`` must satisfy |
+======================+==============+================================+
- ||keyword|_\ ``<K>`` |no |*n/a* |
+ |``K`` |no |*n/a* |
+----------------------+--------------+--------------------------------+
||optional|_\ ``<K,F>``|no |``mpl::apply<F,A>::type::value``|
| | |is ``true``. |
@@ -381,16 +381,15 @@
};
template <class A0>
- |ArgumentPack|_ `operator()`_\(A0 const& a0) const;
+ |ArgumentPack|_ `operator()`_\(A0& a0) const;
template <class A0, class A1>
- |ArgumentPack|_ `operator()`_\(A0 const& a0, A1 const& a1) const;
:vellipsis:`\
- .
- .
- .
- â`
+ |ArgumentPack|_ `operator()`_\(A0& a0, A1& a1) const;
+
+ :vellipsis:`â®`
+
template <class A0, class A1, â¦class A\ β>
- |ArgumentPack|_ `operator()`_\(A0 const& a0, A1 const& a1, â¦A\ β
const& a\ β) const;
+ |ArgumentPack|_ `operator()`_\(A0& a0, A1& a1, â¦A\ β& a\ β) const;
};
@@ -403,13 +402,22 @@
follows, for any argument type ``A``\ *i*:
+ | let ``D0`` the set [d0, â¦, d\ *j*] of all **deduced** *parameter
specs* in [``P0``, â¦, ``P``\ β]
| ``R``\ *i* is ``A``\ *i*\ 's |intended argument type|
|
- | if ``A``\ *i* is a result type of ``keyword<T>::``\ |operator=|_
- | then
- | ``K``\ *i* is ``T``
- | else
- | ``K``\ *i* is ``P``\ *i*\ 's |keyword tag type|.
+ | if ``A``\ *i* is a result type of ``keyword<T>::``\ |operator=|_
+ | then
+ | ``K``\ *i* is ``T``
+ | else
+ | if some ``A``\ *j* where *j*\ â¤\ *i* is a result type of
``keyword<T>::``\ |operator=|_
+ | *or* some ``P``\ *j* in *j*\ â¤\ *i* is **deduced**
+ | then
+ | if some *parameter spec* ``d``\ *j* in ``D``\ *i* matches
``A``\ *i*
+ | then
+ | ``K``\ *i* is ``d``\ *j*\ 's |keyword tag type|.
+ | ``D``\ :sub:`i+1` is ``D``\ *i* - [``d``\ *j*]
+ | else
+ | ``K``\ *i* is ``P``\ *i*\ 's |keyword tag type|.
.. _match:
@@ -425,7 +433,7 @@
every *j* in 0â¦Î², either:
* ``P``\ *j* is the *unspecified* default
- * **or**, ``P``\ *j* is a specialization of |keyword|_,
+ * **or**, ``P``\ *j* is a *keyword tag type*
* **or**, ``P``\ *j* is |optional|_ ``<X,F>`` and either
@@ -443,11 +451,10 @@
``operator()``
.. parsed-literal::
- template <class A0> |ArgumentPack|_ operator()(A0 const& a0) const;
:vellipsis:`\
- .
- .
- .
- â`
+ template <class A0> |ArgumentPack|_ operator()(A0 const& a0) const;
+
+ :vellipsis:`â®`
+
template <class A0, â¦class A\ β> |ArgumentPack|_ `operator()`_\(A0
const& a0, â¦A\ β const& a\ β) const;
:Returns:
@@ -488,6 +495,23 @@
.. |Metafunction| replace:: :concept:`Metafunction`
.. _Metafunction: ../../../mpl/doc/refmanual/metafunction.html
+
+``deduced``
+-----------
+
+This template is used to wrap the *keyword tag* argument to
+``optional`` or ``required``.
+
+:Defined in: `boost/parameter/parameters.hpp`__
+
+__ ../../../../boost/parameter/parameters.hpp
+
+.. parsed-literal::
+
+ template <class Tag>
+ struct deduced;
+
+
//////////////////////////////////////////////////////////////////////////////
Metafunctions
@@ -546,6 +570,37 @@
reference| exists, returns ``boost::``\ |result_of|_\ ``<F()>::type``.
[#no_result_of]_
+``value_type``
+--------------
+
+Returns the result type of indexing an argument pack with a
+|keyword tag type| or with a |tagged default|.
+
+:Defined n: `boost/parameter/value_type.hpp`__
+
+__ ../../../../boost/parameter/value_type.hpp
+
+.. parsed-literal::
+
+ template <class A, class K, class D = void>
+ struct value_type
+ {
+ typedef ⦠type;
+ };
+
+:Requires: ``A`` is a model of |ArgumentPack|_.
+
+:Returns: the type of the |tagged reference| in ``A``
+ having |keyword tag type| ``K``, if any. If no such |tagged
+ reference| exists, returns ``D``. Equivalent to::
+
+ typename remove_reference<
+ typename binding<A, K, D>::type
+ >::type
+
+ ⦠when ``D`` is not a reference type.
+
+
//////////////////////////////////////////////////////////////////////////////
Code Generation Macros
@@ -554,6 +609,7 @@
Macros in this section can be used to ease the writing of code
using the Parameter libray by eliminating repetitive boilerplate.
+
``BOOST_PARAMETER_FUNCTION(result,name,tag_namespace,arguments)``
-----------------------------------------------------------------
@@ -571,17 +627,20 @@
:Argument specifiers syntax:
.. parsed-literal::
- argument-specifiers ::= specifier-group {specifier-group}
+ argument-specifiers ::= *specifier-group* {*specifier-group*}
- specifier-group ::= ( '(' 'optional' optional-specifier
{optional-specifier} ')' ) |
- ( '(' 'required' required-specifier
{required-specifier} ')' )
+ specifier-group0 ::= *specifier-group1* |
+ ( '**(**' '**deduced**' *specifier-group1*
{*specifier-group1*} '**)**' )
- optional-specifier ::= '(' name ',' restriction ',' default-value ')'
- required-specifier ::= '(' name ',' restriction ')'
+ specifier-group1 ::= ( '**(**' '**optional**' *optional-specifier*
{*optional-specifier*} '**)**' ) |
+ ( '**(**' '**required**' *required-specifier*
{*required-specifier*} '**)**' )
- restriction ::= ('*' '(' lambda-expression ')' ) |
- ( '(' typename ')' ) |
- '*'
+ optional-specifier ::= '**(**' *name* '**,**' *restriction* '**,**'
*default-value* ')'
+ required-specifier ::= '**(**' *name* '**,**' *restriction* ')'
+
+ restriction ::= ('*****' '**(**' *lambda-expression* '**)**' ) |
+ ( '**(**' *typename* '**)**' ) |
+ '*****'
``name`` is any valid C++ identifier. ``default-value`` is any valid
C++ expression. ``typename`` is the name of a type.
@@ -631,11 +690,7 @@
*⦠forward to implementation â¦*
}
- :vellipsis:`\
- .
- .
- .
- â`
+ :vellipsis:`â®`
template <class A0, â¦, class A\ **m**>
*result type* **name**\ (
@@ -661,9 +716,149 @@
, *argument name*\ **m** ## _type& *argument name*\ **m**
)
+
+
+``BOOST_PARAMETER_MEMBER_FUNCTION(result,name,tag_namespace,arguments)``
+------------------------------------------------------------------------
+
+:Defined in: `boost/parameter/preprocessor.hpp`__
+
+__ ../../../../boost/parameter/preprocessor.hpp
+
+See ``BOOST_PARAMETER_FUNCTION(result,name,tag_namespace,arguments)``
+
+
+
+``BOOST_PARAMETER_CONSTRUCTOR(cls, impl, tag_namespace, arguments)``
+--------------------------------------------------------------------
+
+:Defined in: `boost/parameter/preprocessor.hpp`__
+
+__ ../../../../boost/parameter/preprocessor.hpp
+
+:Requires: ``cls`` is the name of this class. ``impl`` is the
+ parenthesized implementation base class for ``cls``.
+ ``tag_namespace`` is the namespace in which the keywords
+ used by the function resides. ``arguments`` is
+ a list of *argument specifiers*, as defined in
+ ``BOOST_PARAMETER_FUNCTION(result,name,tag_namespace,arguments)``.
+
+:Generated names in enclosing scope:
+ * ``boost_param_params_ ## __LINE__ ## ctor``
+ * ``constructor_parameters ## __LINE__``
+
+Approximate expansion:
+ **Where**:
+
+ * ``n`` denotes the *minimum* arity, as determined from ``arguments``.
+ * ``m`` denotes the *maximum* arity, as determined from ``arguments``.
+
+ .. parsed-literal::
+
+ struct boost_param_params\_ ## __LINE__ ## ctor
+ : boost::parameter::parameters<
+ *list of parameter specifications, based on arguments*
+ >
+ {};
+
+ typedef boost_param_params\_ ## __LINE__ ## **name**
+ constructor_parameters ## __LINE__;
+
+ template <class A0, â¦, class A\ **n**>
+ *cls*\ (A0 const& a0, â¦, A\ **n** const& a\ **n**)
+ : *impl*\ (constructor_parameters ## __LINE__(a0, â¦, a\ **n**))
+ {}
+
+ :vellipsis:`â®`
+
+ template <class A0, â¦, class A\ **m**>
+ *cls*\ (A0 const& a0, â¦, A\ **n** const& a\ **m**)
+ : *impl*\ (constructor_parameters ## __LINE__(a0, â¦, a\ **m**))
+ {}
+
+
+``BOOST_PARAMETER_NAME(name)``
+------------------------------
+
+Declares a tag-type and keyword object.
+
+Expands to:
+
+**If** *name* is of the form:
+
+.. parsed-literal::
+
+ (*tag-name*, *namespace-name*) *object-name*
+
+**then**
+
+.. parsed-literal::
+
+ namespace *namespace-name*
+ {
+ struct *tag-name*
+ {
+ static char const* keyword_name()
+ {
+ return ##\ *tag-name*;
+ }
+
+ typedef *implementation defined* _;
+ typedef *implementation defined* _1;
+ };
+ }
+
+ ::boost::parameter::keyword<*tag-namespace*\ ::\ *tag-name*\ > const&
*object-name*
+ = ::boost::parameter::keyword<*tag-namespace*\ ::\ *tag-name*\
>::instance;
+
+**Else**
+
+.. parsed-literal::
+
+ namespace tag
+ {
+ struct *name*
+ {
+ static char const* keyword_name()
+ {
+ return ##\ *name*;
+ }
+
+ typedef *implementation defined* _;
+ typedef *implementation defined* _1;
+ };
+ }
+
+ ::boost::parameter::keyword<tag::\ *name*\ > const& _\ *name*
+ = ::boost::parameter::keyword<tag::\ *name*\ >::instance;
+
+
+``BOOST_PARAMETER_TEMPLATE_KEYWORD(name)``
+------------------------------------------
+
+Expands to:
+
+.. parsed-literal::
+
+ namespace tag
+ {
+ struct *name*;
+ }
+
+ template <class T>
+ struct *name*
+ : ::boost::parameter::template_keyword<tag::\ *name*, T>
+ {};
+
+
``BOOST_PARAMETER_FUN(r,n,l,h,p)``
----------------------------------
+.. admonition:: Deprecated
+
+ This macro has been deprecated in favor of
+ ``BOOST_PARAMETER_FUNCTION``.
+
Generates a sequence of `forwarding function`_ templates named
``n``, with arities ranging from ``l`` to ``h`` , returning ``r``,
and using ``p`` to control overload resolution and assign tags to
@@ -694,11 +889,10 @@
, typename **p**::match<A1,A2,â¦A\ **l**,A\ ##\ BOOST_PP_INC_\
(**l**)>::type p = **p**\ ())
{
return **name**\ _with_named_params(**p**\ (x1,x2,â¦x\ **l**,x\ ##\
BOOST_PP_INC_\ (**l**)));
- } :vellipsis:`\
- .
- .
- .
- â`
+ }
+
+ :vellipsis:`â®`
+
template <class A1, class A2, â¦class A\ **h**>
r name(
A1 const& a1, A2 const& a2, â¦A\ **h** const& x\ **h**
@@ -713,6 +907,11 @@
``BOOST_PARAMETER_KEYWORD(n,k)``
--------------------------------
+.. admonition:: Deprecated
+
+ This macro has been deprecated in favor of
+ ``BOOST_PARAMETER_NAME``.
+
Generates the declaration of a |keyword tag type| named ``k`` in
namespace ``n``, and a corresponding |keyword object| definition in
the enclosing namespace.
-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-cvs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/boost-cvs
