Squashed 'third_party/boostorg/functional/' content from commit 7516442
Change-Id: I0e437294bc2af9d32de5022be6ac788cc67244d1
git-subtree-dir: third_party/boostorg/functional
git-subtree-split: 7516442815900430cc9c4a6190354e11bcbe72dd
diff --git a/forward/doc/Jamfile b/forward/doc/Jamfile
new file mode 100644
index 0000000..5665497
--- /dev/null
+++ b/forward/doc/Jamfile
@@ -0,0 +1,19 @@
+
+# (C) Copyright Tobias Schwinger
+#
+# Use modification and distribution are subject to the boost Software License,
+# Version 1.0. (See http:/\/www.boost.org/LICENSE_1_0.txt).
+
+using quickbook ;
+
+xml forward : forward.qbk ;
+boostbook standalone : forward
+ :
+ <xsl:param>boost.root=../../../../..
+ <xsl:param>boost.libraries=../../../../libraries.htm
+ <xsl:param>chunk.section.depth=0
+ <xsl:param>chunk.first.sections=0
+ <xsl:param>generate.section.toc.level=2
+ <xsl:param>toc.max.depth=1
+ ;
+
diff --git a/forward/doc/forward.qbk b/forward/doc/forward.qbk
new file mode 100644
index 0000000..4eb227d
--- /dev/null
+++ b/forward/doc/forward.qbk
@@ -0,0 +1,316 @@
+[library Boost.Functional/Forward
+ [quickbook 1.3]
+ [version 1.0]
+ [authors [Schwinger, Tobias]]
+ [copyright 2007 2008 Tobias Schwinger]
+ [license
+ Distributed under the Boost Software License, Version 1.0.
+ (See accompanying file LICENSE_1_0.txt or copy at
+ [@http://www.boost.org/LICENSE_1_0.txt])
+ ]
+ [purpose Function object adapters for generic argument forwarding.]
+ [category higher-order]
+ [category generic]
+ [last-revision $Date: 2008/11/01 19:58:50 $]
+]
+
+[def __unspecified__ /unspecified/]
+[def __boost_ref__ [@http://www.boost.org/doc/html/ref.html Boost.Ref]]
+[def __boost_result_of__ [@http://www.boost.org/libs/utility/utility.htm#result_of Boost.ResultOf]]
+[def __boost__result_of__ [@http://www.boost.org/libs/utility/utility.htm#result_of `boost::result_of`]]
+[def __the_forwarding_problem__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2002/n1385.htm The Forwarding Problem]]
+[def __boost_fusion__ [@http://www.boost.org/libs/fusion/doc/html/index.html Boost.Fusion]]
+
+[section Brief Description]
+
+`boost::forward_adapter` provides a reusable adapter template for function
+objects. It forwards RValues as references to const, while leaving LValues
+as-is.
+
+ struct g // function object that only accept LValues
+ {
+ template< typename T0, typename T1, typename T2 >
+ void operator()(T0 & t0, T1 & t1, T2 & t2) const;
+
+ typedef void result_type;
+ };
+
+ // Adapted version also accepts RValues and forwards
+ // them as references to const, LValues as-is
+ typedef boost::forward_adapter<g> f;
+
+Another adapter, `boost::lighweight_forward_adapter` allows forwarding with
+some help from the user accepting and unwrapping reference wrappers (see
+__boost_ref__) for reference arguments, const qualifying all other arguments.
+
+The target functions must be compatible with __boost_result_of__, and so are
+the adapters.
+
+[endsect]
+
+[section Background]
+
+Let's suppose we have some function `f` that we can call like this:
+
+ f(123,a_variable);
+
+Now we want to write another, generic function `g` that can be called the
+same way and returns some object that calls `f` with the same arguments.
+
+ f(123,a_variable) == g(f,123,a_variable).call_f()
+
+[heading Why would we want to do it, anyway?]
+
+Maybe we want to run `f` several times. Or maybe we want to run it within
+another thread. Maybe we just want to encapsulate the call expression for now,
+and then use it with other code that allows to compose more complex expressions
+in order to decompose it with C++ templates and have the compiler generate some
+machinery that eventually calls `f` at runtime (in other words; apply a
+technique that is commonly referred to as Expression Templates).
+
+[heading Now, how do we do it?]
+
+The bad news is: It's impossible.
+
+That is so because there is a slight difference between a variable and an
+expression that evaluates to its value: Given
+
+ int y;
+ int const z = 0;
+
+and
+
+ template< typename T > void func1(T & x);
+
+we can call
+
+ func1(y); // x is a reference to a non-const object
+ func1(z); // x is a reference to a const object
+
+where
+
+ func1(1); // fails to compile.
+
+This way we can safely have `func1` store its reference argument and the
+compiler keeps us from storing a reference to an object with temporary lifetime.
+
+It is important to realize that non-constness and whether an object binds to a
+non-const reference parameter are two different properties. The latter is the
+distinction between LValues and RValues. The names stem from the left hand side
+and the right hand side of assignment expressions, thus LValues are typically
+the ones you can assign to, and RValues the temporary results from the right
+hand side expression.
+
+ y = 1+2; // a is LValue, 1+2 is the expression producing the RValue,
+ // 1+2 = a; // usually makes no sense.
+
+ func1(y); // works, because y is an LValue
+ // func1(1+2); // fails to compile, because we only got an RValue.
+
+If we add const qualification on the parameter, our function also accepts
+RValues:
+
+ template< typename T > void func2(T const & x);
+
+ // [...] function scope:
+ func2(1); // x is a reference to a const temporary, object,
+ func2(y); // x is a reference to a const object, while y is not const, and
+ func2(z); // x is a reference to a const object, just like z.
+
+In all cases, the argument `x` in `func2` is a const-qualified LValue.
+We can use function overloading to identify non-const LValues:
+
+ template< typename T > void func3(T const & x); // #1
+ template< typename T > void func3(T & x); // #2
+
+ // [...] function scope:
+ func3(1); // x is a reference to a const, temporary object in #1,
+ func3(y); // x is a reference to a non-const object in #2, and
+ func3(z); // x is a reference to a const object in #1.
+
+Note that all arguments `x` in the overloaded function `func3` are LValues.
+In fact, there is no way to transport RValues into a function as-is in C++98.
+Also note that we can't distinguish between what used to be a const qualified
+LValue and an RValue.
+
+That's as close as we can get to a generic forwarding function `g` as
+described above by the means of C++ 98. See __the_forwarding_problem__ for a
+very detailed discussion including solutions that require language changes.
+
+Now, for actually implementing it, we need 2^N overloads for N parameters
+(each with and without const qualifier) for each number of arguments
+(that is 2^(Nmax+1) - 2^Nmin). Right, that means the compile-time complexity
+is O(2^N), however the factor is low so it works quite well for a reasonable
+number (< 10) of arguments.
+
+[endsect]
+
+[section:reference Reference]
+
+[section forward_adapter]
+
+[heading Description]
+
+Function object adapter template whose instances are callable with LValue and
+RValue arguments. RValue arguments are forwarded as reference-to-const typed
+LValues.
+
+An arity can be given as second, numeric non-type template argument to restrict
+forwarding to a specific arity.
+If a third, numeric non-type template argument is present, the second and third
+template argument are treated as minimum and maximum arity, respectively.
+Specifying an arity can be helpful to improve the readability of diagnostic
+messages and compile time performance.
+
+__boost_result_of__ can be used to determine the result types of specific call
+expressions.
+
+[heading Header]
+ #include <boost/functional/forward_adapter.hpp>
+
+[heading Synopsis]
+
+ namespace boost
+ {
+ template< class Function,
+ int Arity_Or_MinArity = __unspecified__, int MaxArity = __unspecified__ >
+ class forward_adapter;
+ }
+
+[variablelist Notation
+ [[`F`] [a possibly const qualified function object type or reference type thereof]]
+ [[`f`] [an object convertible to `F`]]
+ [[`FA`] [the type `forward_adapter<F>`]]
+ [[`fa`] [an instance object of `FA`, initialized with `f`]]
+ [[`a0`...`aN`] [arguments to `fa`]]
+]
+
+The result type of a target function invocation must be
+
+ __boost__result_of__<F*(TA0 [const]&...TAN [const]&])>::type
+
+where `TA0`...`TAN` denote the argument types of `a0`...`aN`.
+
+[heading Expression Semantics]
+
+[table
+ [[Expression] [Semantics]]
+ [[`FA(f)`] [creates an adapter, initializes the target function with `f`.]]
+ [[`FA()`] [creates an adapter, attempts to use `F`'s default constructor.]]
+ [[`fa(a0`...`aN)`] [calls `f` with with arguments `a0`...`aN`.]]
+]
+
+[heading Limits]
+
+The macro BOOST_FUNCTIONAL_FORWARD_ADAPTER_MAX_ARITY can be defined to set the
+maximum call arity. It defaults to 6.
+
+[heading Complexity]
+
+Preprocessing time: O(2^N), where N is the arity limit.
+Compile time: O(2^N), where N depends on the arity range.
+Run time: O(0) if the compiler inlines, O(1) otherwise.
+
+[endsect]
+
+
+[section lightweight_forward_adapter]
+
+[heading Description]
+
+Function object adapter template whose instances are callable with LValue and
+RValue arguments. All arguments are forwarded as reference-to-const typed
+LValues, except for reference wrappers which are unwrapped and may yield
+non-const LValues.
+
+An arity can be given as second, numeric non-type template argument to restrict
+forwarding to a specific arity.
+If a third, numeric non-type template argument is present, the second and third
+template argument are treated as minimum and maximum arity, respectively.
+Specifying an arity can be helpful to improve the readability of diagnostic
+messages and compile time performance.
+
+__boost_result_of__ can be used to determine the result types of specific call
+expressions.
+
+[heading Header]
+ #include <boost/functional/lightweight_forward_adapter.hpp>
+
+[heading Synopsis]
+
+ namespace boost
+ {
+ template< class Function,
+ int Arity_Or_MinArity = __unspecified__, int MaxArity = __unspecified__ >
+ struct lightweight_forward_adapter;
+ }
+
+[variablelist Notation
+ [[`F`] [a possibly const qualified function object type or reference type thereof]]
+ [[`f`] [an object convertible to `F`]]
+ [[`FA`] [the type `lightweight_forward_adapter<F>`]]
+ [[`fa`] [an instance of `FA`, initialized with `f`]]
+ [[`a0`...`aN`] [arguments to `fa`]]
+]
+
+The result type of a target function invocation must be
+
+ __boost__result_of__<F*(TA0 [const]&...TAN [const]&])>::type
+
+where `TA0`...`TAN` denote the argument types of `a0`...`aN`.
+
+[heading Expression Semantics]
+
+[table
+ [[Expression] [Semantics]]
+ [[`FA(f)`] [creates an adapter, initializes the target function with `f`.]]
+ [[`FA()`] [creates an adapter, attempts to use `F`'s default constructor.]]
+ [[`fa(a0`...`aN)`] [calls `f` with with const arguments `a0`...`aN`. If `aI` is a
+ reference wrapper it is unwrapped.]]
+]
+
+[heading Limits]
+
+The macro BOOST_FUNCTIONAL_LIGHTWEIGHT_FORWARD_ADAPTER_MAX_ARITY can be defined
+to set the maximum call arity. It defaults to 10.
+
+[heading Complexity]
+
+Preprocessing time: O(N), where N is the arity limit.
+Compile time: O(N), where N is the effective arity of a call.
+Run time: O(0) if the compiler inlines, O(1) otherwise.
+
+[endsect]
+
+[endsect]
+
+
+[section Acknowledgements]
+
+As these utilities are factored out of the __boost_fusion__ functional module,
+I want to thank Dan Marsden and Joel de Guzman for letting me participate in the
+development of that great library in the first place.
+
+Further, I want to credit the authors of the references below, for their
+in-depth investigation of the problem and the solution implemented here.
+
+Last but not least I want to thank Vesa Karnoven and Paul Mensonides for the
+Boost Preprocessor library. Without it, I would have ended up with an external
+code generator for this one.
+
+[endsect]
+
+
+[section References]
+
+# [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2002/n1385.htm The Forwarding Problem],
+ Peter Dimov, Howard E. Hinnant, David Abrahams, 2002
+
+# [@http://www.boost.org/libs/utility/utility.htm#result_of Boost.ResultOf],
+ Douglas Gregor, 2004
+
+# [@http://www.boost.org/doc/html/ref.html Boost.Ref],
+ Jaakko Jarvi, Peter Dimov, Douglas Gregor, David Abrahams, 1999-2002
+
+[endsect]
+
diff --git a/forward/doc/html/index.html b/forward/doc/html/index.html
new file mode 100644
index 0000000..2e38715
--- /dev/null
+++ b/forward/doc/html/index.html
@@ -0,0 +1,16 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+ <head>
+ <!-- Copyright (C) 2002 Douglas Gregor <doug.gregor -at- gmail.com>
+
+ Distributed under the Boost Software License, Version 1.0.
+ (See accompanying file LICENSE_1_0.txt or copy at
+ http://www.boost.org/LICENSE_1_0.txt) -->
+ <title>Redirect to generated documentation</title>
+ <meta http-equiv="refresh" content="0; URL=http://www.boost.org/doc/libs/master/libs/functional/forward/doc/html/">
+ </head>
+ <body>
+ Automatic redirection failed, please go to
+ <a href="http://www.boost.org/doc/libs/master/libs/functional/forward/doc/html/">http://www.boost.org/doc/libs/master/libs/functional/forward/doc/html/</a>
+ </body>
+</html>
diff --git a/forward/index.html b/forward/index.html
new file mode 100644
index 0000000..1803029
--- /dev/null
+++ b/forward/index.html
@@ -0,0 +1,15 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+ <head>
+ <meta http-equiv="refresh" content="0; URL=doc/html/index.html">
+ </head>
+ <body>
+ Automatic redirection failed, click this
+ <a href="doc/html/index.html">link</a> <hr>
+ <p>© Copyright Tobias Schwinger, 2009</p>
+ <p>Distributed under the Boost Software License, Version 1.0. (See
+ accompanying file <a href="../../../LICENSE_1_0.txt">
+ LICENSE_1_0.txt</a> or copy at
+ <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</p>
+ </body>
+</html>
diff --git a/forward/test/Jamfile b/forward/test/Jamfile
new file mode 100644
index 0000000..9169456
--- /dev/null
+++ b/forward/test/Jamfile
@@ -0,0 +1,17 @@
+
+# (C) Copyright Tobias Schwinger
+#
+# Use modification and distribution are subject to the boost Software License,
+# Version 1.0. (See http:/\/www.boost.org/LICENSE_1_0.txt).
+
+import testing ;
+
+project forward-tests
+ ;
+
+test-suite functional/forward
+ :
+ [ run forward_adapter.cpp ]
+ [ run lightweight_forward_adapter.cpp ]
+ ;
+
diff --git a/forward/test/forward_adapter.cpp b/forward/test/forward_adapter.cpp
new file mode 100644
index 0000000..0c5e0c3
--- /dev/null
+++ b/forward/test/forward_adapter.cpp
@@ -0,0 +1,135 @@
+/*=============================================================================
+ Copyright (c) 2007 Tobias Schwinger
+
+ Use modification and distribution are subject to the Boost Software
+ License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
+ http://www.boost.org/LICENSE_1_0.txt).
+==============================================================================*/
+
+#include <boost/config.hpp>
+
+#ifdef BOOST_MSVC
+# pragma warning(disable: 4244) // no conversion warnings, please
+#endif
+
+#include <boost/core/lightweight_test.hpp>
+#include <boost/functional/forward_adapter.hpp>
+
+#include <boost/type_traits/is_same.hpp>
+
+#include <boost/blank.hpp>
+#include <boost/noncopyable.hpp>
+
+#include <memory>
+
+template <class Base = boost::blank>
+class test_func : public Base
+{
+ int val;
+public:
+ test_func(int v) : val(v) { }
+
+ template<class B>
+ test_func(test_func<B> const & that)
+ : val(that.val)
+ { }
+
+ template<class B> friend class test_func;
+
+ int operator()(int & l, int const & r) const
+ {
+ return l=r+val;
+ }
+ long operator()(int & l, int const & r)
+ {
+ return -(l=r+val);
+ }
+ char operator()(int& l, int& r)
+ {
+ return l=r+val;
+ }
+
+ template <typename Sig>
+ struct result
+ {
+ typedef void type;
+ };
+
+ // ensure result_of argument types are what's expected
+ // note: this is *not* how client code should look like
+ template <class Self>
+ struct result< Self const(int&,int const&) > { typedef int type; };
+
+ template <class Self>
+ struct result< Self(int&,int const&) > { typedef long type; };
+
+ template <class Self>
+ struct result< Self(int&,int&) > { typedef char type; };
+};
+
+enum { int_, long_, char_ };
+
+int type_of(int) { return int_; }
+int type_of(long) { return long_; }
+int type_of(char) { return char_; }
+
+int main()
+{
+ {
+ using boost::is_same;
+ using boost::result_of;
+ typedef boost::forward_adapter< test_func<> > f;
+
+ // lvalue,rvalue
+ BOOST_TEST(( is_same<
+ result_of< f(int&, int) >::type, long >::value ));
+ BOOST_TEST(( is_same<
+ result_of< f const (int&, int) >::type, int >::value ));
+ // lvalue,const lvalue
+ BOOST_TEST(( is_same<
+ result_of< f(int&, int const &) >::type, long >::value ));
+ BOOST_TEST(( is_same<
+ result_of< f const (int&, int const &) >::type, int >::value ));
+ // lvalue,lvalue
+ BOOST_TEST(( is_same<
+ result_of< f(int&, int&) >::type, char >::value ));
+ // result_of works differently for C++11 here, so compare
+ // with using it against test_func.
+ BOOST_TEST(( is_same<
+ result_of< f const (int&, int&) >::type,
+ result_of< test_func<> const (int&, int&)>::type >::value ));
+ }
+
+ {
+ using boost::noncopyable;
+ using boost::forward_adapter;
+
+ int x = 0;
+ test_func<noncopyable> f(7);
+ forward_adapter< test_func<> > func(f);
+ forward_adapter< test_func<noncopyable> & > func_ref(f);
+ forward_adapter< test_func<noncopyable> & > const func_ref_c(f);
+ forward_adapter< test_func<> const > func_c(f);
+ forward_adapter< test_func<> > const func_c2(f);
+ forward_adapter< test_func<noncopyable> const & > func_c_ref(f);
+
+ BOOST_TEST( type_of( func(x,1) ) == long_ );
+ BOOST_TEST( type_of( func_ref(x,1) ) == long_ );
+ BOOST_TEST( type_of( func_ref_c(x,1) ) == long_ );
+ BOOST_TEST( type_of( func_c(x,1) ) == int_ );
+ BOOST_TEST( type_of( func_c2(x,1) ) == int_ );
+ BOOST_TEST( type_of( func_c_ref(x,1) ) == int_ );
+ BOOST_TEST( type_of( func(x,x) ) == char_ );
+
+ BOOST_TEST( func(x,1) == -8 );
+ BOOST_TEST( func_ref(x,1) == -8 );
+ BOOST_TEST( func_ref_c(x,1) == -8 );
+ BOOST_TEST( func_c(x,1) == 8 );
+ BOOST_TEST( func_c2(x,1) == 8 );
+ BOOST_TEST( func_c_ref(x,1) == 8 );
+ }
+
+ return boost::report_errors();
+}
+
+
diff --git a/forward/test/lightweight_forward_adapter.cpp b/forward/test/lightweight_forward_adapter.cpp
new file mode 100644
index 0000000..b89c92a
--- /dev/null
+++ b/forward/test/lightweight_forward_adapter.cpp
@@ -0,0 +1,135 @@
+/*=============================================================================
+ Copyright (c) 2007 Tobias Schwinger
+
+ Use modification and distribution are subject to the Boost Software
+ License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
+ http://www.boost.org/LICENSE_1_0.txt).
+==============================================================================*/
+
+#include <boost/config.hpp>
+
+#ifdef BOOST_MSVC
+# pragma warning(disable: 4244) // no conversion warnings, please
+#endif
+
+#include <boost/core/lightweight_test.hpp>
+#include <boost/functional/lightweight_forward_adapter.hpp>
+
+#include <boost/type_traits/is_same.hpp>
+
+#include <boost/blank.hpp>
+#include <boost/noncopyable.hpp>
+
+#include <memory>
+
+template <class Base = boost::blank>
+class test_func : public Base
+{
+ int val;
+public:
+ test_func(int v) : val(v) { }
+
+ template<class B>
+ test_func(test_func<B> const & that)
+ : val(that.val)
+ { }
+
+ template<class B> friend class test_func;
+
+ int operator()(int & l, int const & r) const
+ {
+ return l=r+val;
+ }
+ long operator()(int & l, int const & r)
+ {
+ return -(l=r+val);
+ }
+ char operator()(int & l, int & r)
+ {
+ return l=r+val;
+ }
+
+ template <typename Sig>
+ struct result
+ {
+ typedef void type;
+ };
+
+ // ensure result_of argument types are what's expected
+ // note: this is *not* how client code should look like
+ template <class Self>
+ struct result< Self const(int&,int const&) > { typedef int type; };
+
+ template <class Self>
+ struct result< Self(int&,int const&) > { typedef long type; };
+
+ template <class Self>
+ struct result< Self(int&,int&) > { typedef char type; };
+};
+
+enum { int_, long_, char_ };
+
+int type_of(int) { return int_; }
+int type_of(long) { return long_; }
+int type_of(char) { return char_; }
+
+int main()
+{
+ {
+ using boost::is_same;
+ using boost::result_of;
+ typedef boost::lightweight_forward_adapter< test_func<> > f;
+ typedef boost::reference_wrapper<int> ref;
+ typedef boost::reference_wrapper<int const> cref;
+
+ // lvalue,rvalue
+ BOOST_TEST(( is_same<
+ result_of< f(ref, int) >::type, long >::value ));
+ BOOST_TEST(( is_same<
+ result_of< f const (ref, int) >::type, int >::value ));
+ // lvalue,const lvalue
+ BOOST_TEST(( is_same<
+ result_of< f(ref, cref) >::type, long >::value ));
+ BOOST_TEST(( is_same<
+ result_of< f const (ref, cref) >::type, int >::value ));
+ // lvalue,lvalue
+ BOOST_TEST(( is_same<
+ result_of< f(ref, ref) >::type, char >::value ));
+ // result_of works differently for C++11 here, so compare
+ // with using it against test_func.
+ BOOST_TEST(( is_same<
+ result_of< f const (ref, ref) >::type,
+ result_of< test_func<> const (int&, int&) >::type >::value ));
+ }
+ {
+ using boost::noncopyable;
+ using boost::lightweight_forward_adapter;
+
+ int v = 0; boost::reference_wrapper<int> x(v);
+ test_func<noncopyable> f(7);
+ lightweight_forward_adapter< test_func<> > func(f);
+ lightweight_forward_adapter< test_func<noncopyable> & > func_ref(f);
+ lightweight_forward_adapter< test_func<noncopyable> & > const func_ref_c(f);
+ lightweight_forward_adapter< test_func<> const > func_c(f);
+ lightweight_forward_adapter< test_func<> > const func_c2(f);
+ lightweight_forward_adapter< test_func<noncopyable> const & > func_c_ref(f);
+
+ BOOST_TEST( type_of( func(x,1) ) == long_ );
+ BOOST_TEST( type_of( func_ref(x,1) ) == long_ );
+ BOOST_TEST( type_of( func_ref_c(x,1) ) == long_ );
+ BOOST_TEST( type_of( func_c(x,1) ) == int_ );
+ BOOST_TEST( type_of( func_c2(x,1) ) == int_ );
+ BOOST_TEST( type_of( func_c_ref(x,1) ) == int_ );
+ BOOST_TEST( type_of( func(x,x) ) == char_ );
+
+ BOOST_TEST( func(x,1) == -8 );
+ BOOST_TEST( func_ref(x,1) == -8 );
+ BOOST_TEST( func_ref_c(x,1) == -8 );
+ BOOST_TEST( func_c(x,1) == 8 );
+ BOOST_TEST( func_c2(x,1) == 8 );
+ BOOST_TEST( func_c_ref(x,1) == 8 );
+ }
+
+ return boost::report_errors();
+}
+