Squashed 'third_party/boostorg/bind/' content from commit d67200b
Change-Id: I21573b0bd786f4e8482a7bb79a73b7574be6bdae
git-subtree-dir: third_party/boostorg/bind
git-subtree-split: d67200bd2a1f67135a4c677636546ec9615e21ea
diff --git a/doc/bind/limitations.qbk b/doc/bind/limitations.qbk
new file mode 100644
index 0000000..a3b2305
--- /dev/null
+++ b/doc/bind/limitations.qbk
@@ -0,0 +1,37 @@
+[/
+ / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd.
+ / Copyright (c) 2003-2008 Peter Dimov
+ /
+ / 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)
+ /]
+
+[section:limitations Limitations]
+
+As a general rule, the function objects generated by `bind` take their
+arguments by reference and cannot, therefore, accept non-const temporaries or
+literal constants. This is an inherent limitation of the C++ language in its
+current (2003) incarnation, known as the [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2002/n1385.htm forwarding problem].
+(It will be fixed in the next standard, usually called C++0x.)
+
+The library uses signatures of the form
+
+ template<class T> void f(T & t);
+
+to accept arguments of arbitrary types and pass them on unmodified. As noted,
+this does not work with non-const r-values.
+
+On compilers that support partial ordering of function templates, a possible
+solution is to add an overload:
+
+ template<class T> void f(T & t);
+ template<class T> void f(T const & t);
+
+Unfortunately, this requires providing 512 overloads for nine arguments, which
+is impractical. The library chooses a small subset: for up to two arguments,
+it provides the const overloads in full, for arities of three and more it
+provides a single additional overload with all of the arguments taken by const
+reference. This covers a reasonable portion of the use cases.
+
+[endsect]