From f8a1b652bcd2cb38f4b53be27fbd00a3f3597951 Mon Sep 17 00:00:00 2001 From: Daniel Wallin Date: Tue, 1 May 2007 14:43:47 +0000 Subject: [PATCH] Fixed examples and removed use of boost::lambda. [SVN r37550] --- doc/index.rst | 99 ++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 74 insertions(+), 25 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 5d0e2a3..51e7131 100755 --- a/doc/index.rst +++ b/doc/index.rst @@ -1067,8 +1067,8 @@ With the declaration above, the following two calls are equivalent: .. 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 @@ specify the parameter name explicitly, as follows: .. parsed-literal:: def( - "f", f + "f", &f , **_policies = some_policies**, "Documentation for f"); .. @example.append('}') @@ -1114,7 +1114,8 @@ be used within the body of a class:: }; .. @example.prepend(''' - #include ''') + #include + #include ''') .. @test('compile') @@ -1701,7 +1702,10 @@ its function call operator: , optional > > 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 @@ its function call operator: .. @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 @@ case we can use the ``binding< … >`` metafunction introduced BOOST_PARAMETER_NAME(index) template - typename parameter::binding::type + typename remove_reference< + typename parameter::binding::type + >::type twice_index(ArgumentPack const& args) { return 2 * args[_index|42]; @@ -1778,21 +1789,44 @@ case we can use the ``binding< … >`` metafunction introduced int six = twice_index(_index = 3); -.. TODO: binding<> returns a reference. We should use value_type<> here. - .. @example.prepend(''' #include + #include #include - 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 + typename **parameter::value_type**::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 @@ when using |ArgumentPack|\ s explicitly, we need a tool other than 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(), ref(s1), ref(s2))** ]; .. @example.prepend(''' - #include + #include + #include #include #include + #include namespace parameter = boost::parameter; @@ -1876,7 +1920,7 @@ with a function object built by the Boost Lambda_ library: [#bind]_ .. @test('run') -.. _Lambda: ../../../lambda/index.html +.. .. _Lambda: ../../../lambda/index.html .. sidebar:: Mnemonics @@ -1886,10 +1930,15 @@ with a function object built by the Boost Lambda_ library: [#bind]_ 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(), 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 @@ __ ../../../graph/doc/bgl_named_params.html .. _`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(),s1,s2) +.. boost::bind(std::plus(),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