diff options
Diffstat (limited to 'libs/bind/doc')
| -rw-r--r-- | libs/bind/doc/Jamfile.v2 | 50 | ||||
| -rw-r--r-- | libs/bind/doc/bind.qbk | 35 | ||||
| -rw-r--r-- | libs/bind/doc/bind/acknowledgements.qbk | 48 | ||||
| -rw-r--r-- | libs/bind/doc/bind/examples.qbk | 70 | ||||
| -rw-r--r-- | libs/bind/doc/bind/faq.qbk | 99 | ||||
| -rw-r--r-- | libs/bind/doc/bind/implementation.qbk | 98 | ||||
| -rw-r--r-- | libs/bind/doc/bind/interface.qbk | 216 | ||||
| -rw-r--r-- | libs/bind/doc/bind/limitations.qbk | 37 | ||||
| -rw-r--r-- | libs/bind/doc/bind/purpose.qbk | 273 | ||||
| -rw-r--r-- | libs/bind/doc/bind/troubleshooting.qbk | 268 | ||||
| -rw-r--r-- | libs/bind/doc/html/bind.html | 1552 | ||||
| -rw-r--r-- | libs/bind/doc/html/mem_fn.html | 552 | ||||
| -rw-r--r-- | libs/bind/doc/html/standalone_bind_HTML.manifest | 1 | ||||
| -rw-r--r-- | libs/bind/doc/html/standalone_mem_fn_HTML.manifest | 1 | ||||
| -rw-r--r-- | libs/bind/doc/mem_fn.qbk | 32 | ||||
| -rw-r--r-- | libs/bind/doc/mem_fn/acknowledgements.qbk | 28 | ||||
| -rw-r--r-- | libs/bind/doc/mem_fn/faq.qbk | 53 | ||||
| -rw-r--r-- | libs/bind/doc/mem_fn/implementation.qbk | 70 | ||||
| -rw-r--r-- | libs/bind/doc/mem_fn/interface.qbk | 133 | ||||
| -rw-r--r-- | libs/bind/doc/mem_fn/purpose.qbk | 93 |
20 files changed, 3709 insertions, 0 deletions
diff --git a/libs/bind/doc/Jamfile.v2 b/libs/bind/doc/Jamfile.v2 new file mode 100644 index 000000000..c481aa611 --- /dev/null +++ b/libs/bind/doc/Jamfile.v2 @@ -0,0 +1,50 @@ +# 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) + +project doc/bind ; + +import boostbook ; +import quickbook ; + +xml bind_ : bind.qbk ; +boostbook standalone_bind + : + bind_ + : + <xsl:param>boost.root=../../../.. + # File name of HTML output: + <xsl:param>root.filename=bind + # How far down we chunk nested sections, basically all of them: + <xsl:param>chunk.section.depth=0 + # Don't put the first section on the same page as the TOC: + <xsl:param>chunk.first.sections=0 + # How far down sections get TOC's + <xsl:param>toc.section.depth=2 + # Max depth in each TOC: + <xsl:param>toc.max.depth=2 + # How far down we go with TOC's + <xsl:param>generate.section.toc.level=0 + ; + +xml mem_fn_ : mem_fn.qbk ; +boostbook standalone_mem_fn + : + mem_fn_ + : + <xsl:param>boost.root=../../../.. + # File name of HTML output: + <xsl:param>root.filename=mem_fn + # How far down we chunk nested sections, basically all of them: + <xsl:param>chunk.section.depth=0 + # Don't put the first section on the same page as the TOC: + <xsl:param>chunk.first.sections=0 + # How far down sections get TOC's + <xsl:param>toc.section.depth=2 + # Max depth in each TOC: + <xsl:param>toc.max.depth=2 + # How far down we go with TOC's + <xsl:param>generate.section.toc.level=0 + ; diff --git a/libs/bind/doc/bind.qbk b/libs/bind/doc/bind.qbk new file mode 100644 index 000000000..807ba681f --- /dev/null +++ b/libs/bind/doc/bind.qbk @@ -0,0 +1,35 @@ +[/ + / 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) + /] + +[library Boost.Bind + [quickbook 1.6] + [id bind] + [copyright 2001, 2002 Peter Dimov and Multi Media Ltd.] + [copyright 2003-2008 Peter Dimov] + [dirname bind] + [license Distributed under the + [@http://boost.org/LICENSE_1_0.txt Boost Software License, + Version 1.0]. + ] +] + +[template simplesect[title] +[block '''<simplesect><title>'''[title]'''</title>''']] + +[template endsimplesect[] +[block '''</simplesect>''']] + +[include bind/purpose.qbk] +[include bind/examples.qbk] +[include bind/limitations.qbk] +[include bind/faq.qbk] +[include bind/troubleshooting.qbk] +[include bind/interface.qbk] +[include bind/implementation.qbk] +[include bind/acknowledgements.qbk] diff --git a/libs/bind/doc/bind/acknowledgements.qbk b/libs/bind/doc/bind/acknowledgements.qbk new file mode 100644 index 000000000..3c87519de --- /dev/null +++ b/libs/bind/doc/bind/acknowledgements.qbk @@ -0,0 +1,48 @@ +[/ + / 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:acknowledgements Acknowledgements] + +Earlier efforts that have influenced the library design: + +* The [@http://staff.cs.utu.fi/BL/ Binder Library] by Jaakko J\u00E4rvi; + +* The [@boost:/libs/lambda/index.html Lambda Library] (now part of Boost) by + Jaakko J\u00E4rvi and Gary Powell (the successor to the Binder Library); + +* [@http://more.sourceforge.net/ Extensions to the STL] by Petter Urkedal. + +Doug Gregor suggested that a visitor mechanism would allow `bind` to +interoperate with a signal/slot library. + +John Maddock fixed a MSVC-specific conflict between `bind` and the +[@boost:/libs/type_traits/index.html type traits library]. + +Numerous improvements were suggested during the formal review period by Ross +Smith, Richard Crossley, Jens Maurer, Ed Brey, and others. Review manager was +Darin Adler. + +The precise semantics of `bind` were refined in discussions with Jaakko +J\u00E4rvi. + +Dave Abrahams fixed a MSVC-specific conflict between `bind` and the +[@boost:/libs/utility/iterator_adaptors.htm iterator adaptors library]. + +Dave Abrahams modified `bind` and `mem_fn` to support `void` returns on +deficient compilers. + +Mac Murrett contributed the "pascal" support enabled by +`BOOST_BIND_ENABLE_PASCAL`. + +The alternative `bind(type<R>(), f, ...)` syntax was inspired by a discussion +with Dave Abrahams and Joel de Guzman. + +This documentation was ported to Quickbook by Agustín Bergé. + +[endsect] diff --git a/libs/bind/doc/bind/examples.qbk b/libs/bind/doc/bind/examples.qbk new file mode 100644 index 000000000..7a36d0616 --- /dev/null +++ b/libs/bind/doc/bind/examples.qbk @@ -0,0 +1,70 @@ +[/ + / 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:examples Examples] + +[section Using bind with standard algorithms] + + class image; + + class animation + { + public: + void advance(int ms); + bool inactive() const; + void render(image & target) const; + }; + + std::vector<animation> anims; + + template<class C, class P> void erase_if(C & c, P pred) + { + c.erase(std::remove_if(c.begin(), c.end(), pred), c.end()); + } + + void update(int ms) + { + std::for_each(anims.begin(), anims.end(), boost::bind(&animation::advance, _1, ms)); + erase_if(anims, boost::mem_fn(&animation::inactive)); + } + + void render(image & target) + { + std::for_each(anims.begin(), anims.end(), boost::bind(&animation::render, _1, boost::ref(target))); + } + +[endsect] + +[section Using bind with Boost.Function] + + class button + { + public: + ``[@boost:/libs/function/index.html `boost::function`]``<void()> onClick; + }; + + class player + { + public: + void play(); + void stop(); + }; + + button playButton, stopButton; + player thePlayer; + + void connect() + { + playButton.onClick = boost::bind(&player::play, &thePlayer); + stopButton.onClick = boost::bind(&player::stop, &thePlayer); + } + +[endsect] + +[endsect] diff --git a/libs/bind/doc/bind/faq.qbk b/libs/bind/doc/bind/faq.qbk new file mode 100644 index 000000000..8406a19f1 --- /dev/null +++ b/libs/bind/doc/bind/faq.qbk @@ -0,0 +1,99 @@ +[/ + / 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:faq Frequently Asked Questions] + +[section Why doesn't this compile?] + +See the dedicated [link bind.troubleshooting Troubleshooting section]. + +[endsect] + +[section Why does this compile? It should not.] + +Probably because you used the general `bind<R>(f, ...)` syntax, thereby +instructing `bind` to not "inspect" f to detect arity and return type errors. + +[endsect] + +[section:Q_forms What is the difference between `bind(f, ...)` and `bind<R>(f, ...)`?] + +The first form instructs `bind` to inspect the type of `f` in order to +determine its arity (number of arguments) and return type. Arity errors will +be detected at "bind time". This syntax, of course, places some requirements +on `f`. It must be a function, function pointer, member function pointer, or a +function object that defines a nested type named `result_type`; in short, it +must be something that `bind` can recognize. + +The second form instructs `bind` to not attempt to recognize the type of `f`. +It is generally used with function objects that do not, or cannot, expose +`result_type`, but it can also be used with nonstandard functions. For example, +the current implementation does not automatically recognize variable-argument +functions like `printf`, so you will have to use `bind<int>(printf, ...)`. +Note that an alternative `bind(type<R>(), f, ...)` syntax is supported for +portability reasons. + +Another important factor to consider is that compilers without partial +template specialization or function template partial ordering support cannot +handle the first form when `f` is a function object, and in most cases will +not handle the second form when `f` is a function (pointer) or a member +function pointer. + +[endsect] + +[section Does bind work with Windows API functions?] + +Yes, if you [link bind.implementation.stdcall `#define +BOOST_BIND_ENABLE_STDCALL`]. An alternative is to treat the function as a +[link bind.purpose.with_function_objects generic function object] and use the +`bind<R>(f, ...)` syntax. + +[endsect] + +[section Does bind work with COM methods?] + +Yes, if you [link bind.implementation.stdcall `#define +BOOST_MEM_FN_ENABLE_STDCALL`]. + +[endsect] + +[section Does bind work with Mac toolbox functions?] + +Yes, if you [link bind.implementation.stdcall `#define +BOOST_BIND_ENABLE_PASCAL`]. An alternative is to treat the function as a [link +bind.purpose.with_function_objects generic function object] and use the +`bind<R>(f, ...)` syntax. + +[endsect] + +[section Does bind work with extern "C" functions?] + +Sometimes. On some platforms, pointers to extern "C" functions are equivalent +to "ordinary" function pointers, so they work fine. Other platforms treat them +as different types. A platform-specific implementation of `bind` is expected +to handle the problem transparently; this implementation does not. As usual, +the workaround is to treat the function as a [link +bind.purpose.with_function_objects generic function object] and use the +`bind<R>(f, ...)` syntax. + +[endsect] + +[section Why doesn't bind automatically recognize nonstandard functions?] + +Non-portable extensions, in general, should default to off to prevent vendor +lock-in. Had the [link bind.implementation.stdcall appropriate macros] been +defined automatically, you could have accidentally taken advantage of them +without realizing that your code is, perhaps, no longer portable. In addition, +some compilers have the option to make `__stdcall` (`__fastcall`) their +default calling convention, in which case no separate support would be +necessary. + +[endsect] + +[endsect] diff --git a/libs/bind/doc/bind/implementation.qbk b/libs/bind/doc/bind/implementation.qbk new file mode 100644 index 000000000..40d339ada --- /dev/null +++ b/libs/bind/doc/bind/implementation.qbk @@ -0,0 +1,98 @@ +[/ + / 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:implementation Implementation] + +[section Files] + +* [@../../include/boost/bind.hpp boost/bind.hpp] (main header) +* [@../../include/boost/bind/bind_cc.hpp boost/bind/bind_cc.hpp] (used by `bind.hpp`, do not include directly) +* [@../../include/boost/bind/bind_mf_cc.hpp boost/bind/bind_mf_cc.hpp] (used by `bind.hpp`, do not include directly) +* [@../../include/boost/bind/bind_template.hpp boost/bind/bind_template.hpp] (used by `bind.hpp`, do not include directly) +* [@../../include/boost/bind/arg.hpp boost/bind/arg.hpp] (defines the type of the placeholder arguments) +* [@../../include/boost/bind/placeholders.hpp boost/bind/placeholders.hpp] (defines the `_1`, `_2`, ... `_9` placeholders) +* [@../../include/boost/bind/apply.hpp boost/bind/apply.hpp] (`apply` helper function object) +* [@../../include/boost/bind/protect.hpp boost/bind/protect.hpp] (`protect` helper function) +* [@../../include/boost/bind/make_adaptable.hpp boost/bind/make_adaptable.hpp] (`make_adaptable` helper function) +* [@../../test/bind_test.cpp libs/bind/test/bind_test.cpp] (test) +* [@../../bind_as_compose.cpp libs/bind/bind_as_compose.cpp] (function composition example) +* [@../../bind_visitor.cpp libs/bind/bind_visitor.cpp] (visitor example) +* [@../../test/bind_stdcall_test.cpp libs/bind/test/bind_stdcall_test.cpp] (test with `__stdcall` functions) +* [@../../test/bind_stdcall_mf_test.cpp libs/bind/test/bind_stdcall_mf_test.cpp] (test with `__stdcall` member functions) +* [@../../test/bind_fastcall_test.cpp libs/bind/test/bind_fastcall_test.] (test with `__fastcall` functions) +* [@../../test/bind_fastcall_mf_test.cpp libs/bind/test/bind_fastcall_mf_test.cpp] (test with `__fastcall` member functions) + +[endsect] + +[section Dependencies] + +* [@boost:/libs/config/config.htm Boost.Config] +* [@boost:/libs/core/doc/html/core/ref.html boost/ref.hpp] +* [@boost:/libs/bind/mem_fn.html boost/mem_fn.hpp] +* [@boost:/boost/type.hpp boost/type.hpp] + +[endsect] + +[section Number of Arguments] + +This implementation supports function objects with up to nine arguments. This +is an implementation detail, not an inherent limitation of the design. + +[endsect] + +[section:stdcall `__stdcall`, `__cdecl`, `__fastcall`, and `pascal` Support] + +Some platforms allow several types of (member) functions that differ by their +calling convention (the rules by which the function is invoked: how are +arguments passed, how is the return value handled, and who cleans up the stack + - if any.) + +For example, Windows API functions and COM interface member functions use a +calling convention known as `__stdcall`. Borland VCL components use +`__fastcall`. Mac toolbox functions use a `pascal` calling convention. + +To use `bind` with `__stdcall` functions, `#define` the macro +`BOOST_BIND_ENABLE_STDCALL` before including `<boost/bind.hpp>`. + +To use `bind` with `__stdcall` member functions, `#define` the macro +`BOOST_MEM_FN_ENABLE_STDCALL` before including `<boost/bind.hpp>`. + +To use `bind` with `__fastcall` functions, `#define` the macro +`BOOST_BIND_ENABLE_FASTCALL` before including `<boost/bind.hpp>`. + +To use `bind` with `__fastcall` member functions, `#define` the macro +`BOOST_MEM_FN_ENABLE_FASTCALL` before including `<boost/bind.hpp>`. + +To use `bind` with `pascal` functions, `#define` the macro +`BOOST_BIND_ENABLE_PASCAL` before including `<boost/bind.hpp>`. + +To use `bind` with `__cdecl` member functions, `#define` the macro +`BOOST_MEM_FN_ENABLE_CDECL` before including `<boost/bind.hpp>`. + +[*It is best to define these macros in the project options, via `-D` on the +command line, or as the first line in the translation unit (.cpp file) where +`bind` is used.] Not following this rule can lead to obscure errors when a +header includes `bind.hpp` before the macro has been defined. + +/[Note:/ this is a non-portable extension. It is not part of the interface./]/ + +/[Note:/ Some compilers provide only minimal support for the `__stdcall` keyword./]/ + +[endsect] + +[section `visit_each` support] + +Function objects returned by `bind` support the experimental and undocumented, +as of yet, `visit_each` enumeration interface. + +See [@../../bind_visitor.cpp bind_visitor.cpp] for an example. + +[endsect] + +[endsect] diff --git a/libs/bind/doc/bind/interface.qbk b/libs/bind/doc/bind/interface.qbk new file mode 100644 index 000000000..cd83f9cb3 --- /dev/null +++ b/libs/bind/doc/bind/interface.qbk @@ -0,0 +1,216 @@ +[/ + / 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:interface Interface] + +[section:synopsys Synopsis] + + namespace boost + { + // no arguments + + template<class R, class F> ``/unspecified-1/`` ``[link bind_1 `bind`]``(F f); + + template<class F> ``/unspecified-1-1/`` ``[link bind_1_1 `bind`]``(F f); + + template<class R> ``/unspecified-2/`` ``[link bind_2 `bind`]``(R (*f) ()); + + // one argument + + template<class R, class F, class A1> ``/unspecified-3/`` ``[link bind_3 `bind`]``(F f, A1 a1); + + template<class F, class A1> ``/unspecified-3-1/`` ``[link bind_3_1 `bind`]``(F f, A1 a1); + + template<class R, class B1, class A1> ``/unspecified-4/`` ``[link bind_4 `bind`]``(R (*f) (B1), A1 a1); + + template<class R, class T, class A1> ``/unspecified-5/`` ``[link bind_5 `bind`]``(R (T::*f) (), A1 a1); + + template<class R, class T, class A1> ``/unspecified-6/`` ``[link bind_6 `bind`]``(R (T::*f) () const, A1 a1); + + template<class R, class T, class A1> ``/unspecified-6-1/`` ``[link bind_6_1 `bind`]``(R T::*f, A1 a1); + + // two arguments + + template<class R, class F, class A1, class A2> ``/unspecified-7/`` ``[link bind_7 `bind`]``(F f, A1 a1, A2 a2); + + template<class F, class A1, class A2> ``/unspecified-7-1/`` ``[link bind_7_1 `bind`]``(F f, A1 a1, A2 a2); + + template<class R, class B1, class B2, class A1, class A2> ``/unspecified-8/`` ``[link bind_8 `bind`]``(R (*f) (B1, B2), A1 a1, A2 a2); + + template<class R, class T, class B1, class A1, class A2> ``/unspecified-9/`` ``[link bind_9 `bind`]``(R (T::*f) (B1), A1 a1, A2 a2); + + template<class R, class T, class B1, class A1, class A2> ``/unspecified-10/`` ``[link bind_10 `bind`]``(R (T::*f) (B1) const, A1 a1, A2 a2); + + // implementation defined number of additional overloads for more arguments + } + + namespace + { + ``/unspecified-placeholder-type-1/`` _1; + + ``/unspecified-placeholder-type-2/`` _2; + + ``/unspecified-placeholder-type-3/`` _3; + + // implementation defined number of additional placeholder definitions + } + +[endsect] + +[section Common requirements] + +All /unspecified-N/ types returned by `bind` are /CopyConstructible/. /unspecified-N/`::result_type` is defined as the return type of /unspecified-N/`::operator()`. + +All /unspecified-placeholder-N/ types are /CopyConstructible/. Their copy constructors do not throw exceptions. + +[endsect] + +[section Common definitions] + +The function \u03BC`(x, v1, v2, ..., vm)`, where `m` is a nonnegative integer, is +defined as: + +* `x.get()`, when `x` is of type [@boost:/libs/core/doc/html/core/ref.html `boost::reference_wrapper`]`<T>` for some type + `T`; + +* `vk`, when `x` is (a copy of) the placeholder /_k/ for some positive integer + /k/; + +* `x(v1, v2, ..., vm)` when `x` is (a copy of) a function object returned by + `bind`; + +* `x` otherwise. + +[endsect] + +[section `bind`] + +[#bind_1] + + template<class R, class F> ``/unspecified-1/`` bind(F f) + +* /Returns:/ A function object \u03BB such that the expression \u03BB`(v1, v2, ..., vm)` +is equivalent to `f()`, implicitly converted to `R`. + +* /Throws:/ Nothing unless the copy constructor of `F` throws an exception. + +[#bind_1_1] + + template<class F> ``/unspecified-1-1/`` bind(F f) + +* /Effects:/ Equivalent to `bind<typename F::result_type, F>(f)`. + +* /Notes:/ Implementations are allowed to infer the return type of `f` via other +means as an extension, without relying on the `result_type` member. + +[#bind_2] + + template<class R> ``/unspecified-2/`` bind(R (*f) ()) + +* /Returns:/ A function object \u03BB such that the expression \u03BB`(v1, v2, ..., vm)` +is equivalent to `f()`. + +* /Throws:/ Nothing. + +[#bind_3] + + template<class R, class F, class A1> ``/unspecified-3/`` bind(F f, A1 a1) + +* /Returns:/ A function object \u03BB such that the expression \u03BB`(v1, v2, ..., vm)` +is equivalent to `f(`\u03BC`(a1, v1, v2, ..., vm))`, implicitly converted to `R`. + +* /Throws:/ Nothing unless the copy constructors of `F` or `A1` throw an exception. + +[#bind_3_1] + + template<class F, class A1> ``/unspecified-3-1/`` bind(F f, A1 a1) + +* /Effects:/ Equivalent to `bind<typename F::result_type, F, A1>(f, a1)`. + +* /Notes:/ Implementations are allowed to infer the return type of `f` via other +means as an extension, without relying on the `result_type` member. + +[#bind_4] + + template<class R, class B1, class A1> ``/unspecified-4/`` bind(R (*f) (B1), A1 a1) + +* /Returns:/ A function object \u03BB such that the expression \u03BB`(v1, v2, ..., vm)` +is equivalent to `f(`\u03BC`(a1, v1, v2, ..., vm))`. + +* /Throws:/ Nothing unless the copy constructor of `A1` throws an exception. + +[#bind_5] + + template<class R, class T, class A1> ``/unspecified-5/`` bind(R (T::*f) (), A1 a1) + +* /Effects:/ Equivalent to `bind<R>(`[@boost:/libs/bind/mem_fn.html `boost::mem_fn`]`(f), a1)`. + +[#bind_6] + + template<class R, class T, class A1> ``/unspecified-6/`` bind(R (T::*f) () const, A1 a1) + +* /Effects:/ Equivalent to `bind<R>(`[@boost:/libs/bind/mem_fn.html `boost::mem_fn`]`(f), a1)`. + +[#bind_6_1] + + template<class R, class T, class A1> ``/unspecified-6-1/`` bind(R T::*f, A1 a1) + +* /Effects:/ Equivalent to `bind<R>(`[@boost:/libs/bind/mem_fn.html `boost::mem_fn`]`(f), a1)`. + +[#bind_7] + + template<class R, class F, class A1, class A2> ``/unspecified-7/`` bind(F f, A1 a1, A2 a2) + +* /Returns:/ A function object \u03BB such that the expression \u03BB`(v1, v2, ..., vm)` +is equivalent to `f(`\u03BC`(a1, v1, v2, ..., vm), `\u03BC`(a2, v1, v2, ..., vm))`, +implicitly converted to `R`. + +* /Throws:/ Nothing unless the copy constructors of `F`, `A1` or `A2` throw an +exception. + +[#bind_7_1] + + template<class F, class A1, class A2> ``/unspecified-7-1/`` bind(F f, A1 a1, A2 a2) + +* /Effects:/ Equivalent to `bind<typename F::result_type, F, A1, A2>(f, a1, a2)`. + +* /Notes:/ Implementations are allowed to infer the return type of `f` via other +means as an extension, without relying on the `result_type` member. + +[#bind_8] + + template<class R, class B1, class B2, class A1, class A2> ``/unspecified-8/`` bind(R (*f) (B1, B2), A1 a1, A2 a2) + +* /Returns:/ A function object \u03BB such that the expression \u03BB`(v1, v2, ..., vm)` +is equivalent to `f(`\u03BC`(a1, v1, v2, ..., vm), `\u03BC`(a2, v1, v2, ..., vm))`. + +* /Throws:/ Nothing unless the copy constructors of `A1` or `A2` throw an exception. + +[#bind_9] + + template<class R, class T, class B1, class A1, class A2> ``/unspecified-9/`` bind(R (T::*f) (B1), A1 a1, A2 a2) + +* /Effects:/ Equivalent to `bind<R>(`[@boost:/libs/bind/mem_fn.html `boost::mem_fn`]`(f), a1, a2)`. + +[#bind_10] + + template<class R, class T, class B1, class A1, class A2> ``/unspecified-10/`` bind(R (T::*f) (B1) const, A1 a1, A2 a2) + +* /Effects:/ Equivalent to `bind<R>(`[@boost:/libs/bind/mem_fn.html `boost::mem_fn`]`(f), a1, a2)`. + +[endsect] + +[section Additional overloads] + +Implementations are allowed to provide additional `bind` overloads in order to +support more arguments or different function pointer variations. + +[endsect] + +[endsect] diff --git a/libs/bind/doc/bind/limitations.qbk b/libs/bind/doc/bind/limitations.qbk new file mode 100644 index 000000000..a3b2305c8 --- /dev/null +++ b/libs/bind/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] diff --git a/libs/bind/doc/bind/purpose.qbk b/libs/bind/doc/bind/purpose.qbk new file mode 100644 index 000000000..8ec1e79f7 --- /dev/null +++ b/libs/bind/doc/bind/purpose.qbk @@ -0,0 +1,273 @@ +[/ + / 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:purpose Purpose] + +`boost::bind` is a generalization of the standard functions `std::bind1st` and +`std::bind2nd`. It supports arbitrary function objects, functions, function +pointers, and member function pointers, and is able to bind any argument to a +specific value or route input arguments into arbitrary positions. `bind` does +not place any requirements on the function object; in particular, it does not +need the `result_type`, `first_argument_type` and `second_argument_type` +standard typedefs. + +[section Using bind with functions and function pointers] + +Given these definitions: + + int f(int a, int b) + { + return a + b; + } + + int g(int a, int b, int c) + { + return a + b + c; + } + +`bind(f, 1, 2)` will produce a "nullary" function object that takes no +arguments and returns `f(1, 2)`. Similarly, `bind(g, 1, 2, 3)()` is equivalent + `to g(1, 2, 3)`. + +It is possible to selectively bind only some of the arguments. +`bind(f, _1, 5)(x)` is equivalent to `f(x, 5)`; here `_1` is a /placeholder/ +argument that means "substitute with the first input argument." + +For comparison, here is the same operation expressed with the standard library +primitives: + + std::bind2nd(std::ptr_fun(f), 5)(x); + +`bind` covers the functionality of `std::bind1st` as well: + + std::bind1st(std::ptr_fun(f), 5)(x); // f(5, x) + bind(f, 5, _1)(x); // f(5, x) + +`bind` can handle functions with more than two arguments, and its argument +substitution mechanism is more general: + + bind(f, _2, _1)(x, y); // f(y, x) + bind(g, _1, 9, _1)(x); // g(x, 9, x) + bind(g, _3, _3, _3)(x, y, z); // g(z, z, z) + bind(g, _1, _1, _1)(x, y, z); // g(x, x, x) + +Note that, in the last example, the function object produced by +`bind(g, _1, _1, _1)` does not contain references to any arguments beyond the +first, but it can still be used with more than one argument. Any extra +arguments are silently ignored, just like the first and the second argument +are ignored in the third example. + +The arguments that `bind` takes are copied and held internally by the returned +function object. For example, in the following code: + + int i = 5; + bind(f, i, _1); + +a copy of the value of `i` is stored into the function object. +[@boost:/libs/core/doc/html/core/ref.html `boost::ref`] and +[@boost:/libs/core/doc/html/core/ref.html `boost::cref`] can be used to make the function +object store a reference to an object, rather than a copy: + + int i = 5; + bind(f, ref(i), _1); + bind(f, cref(i), _1); + +[endsect] + +[section:with_function_objects Using bind with function objects] + +`bind` is not limited to functions; it accepts arbitrary function objects. In +the general case, the return type of the generated function object's +`operator()` has to be specified explicitly (without a `typeof` operator the +return type cannot be inferred): + + struct F + { + int operator()(int a, int b) { return a - b; } + bool operator()(long a, long b) { return a == b; } + }; + + F f; + int x = 104; + bind<int>(f, _1, _1)(x); // f(x, x), i.e. zero + +Some compilers have trouble with the `bind<R>(f, ...)` syntax. For portability +reasons, an alternative way to express the above is supported: + + boost::bind(boost::type<int>(), f, _1, _1)(x); + +Note, however, that the alternative syntax is provided only as a workaround. +It is not part of the interface. + +When the function object exposes a nested type named `result_type`, the explicit +return type can be omitted: + + int x = 8; + bind(std::less<int>(), _1, 9)(x); // x < 9 + +/[Note:/ the ability to omit the return type is not available on all compilers./]/ + +By default, `bind` makes a copy of the provided function object. `boost::ref` +and `boost::cref` can be used to make it store a reference to the function +object, rather than a copy. This can be useful when the function object is +non-copyable, expensive to copy, or contains state; of course, in this case +the programmer is expected to ensure that the function object is not destroyed +while it's still being used. + + struct F2 + { + int s; + + typedef void result_type; + void operator()(int x) { s += x; } + }; + + F2 f2 = { 0 }; + int a[] = { 1, 2, 3 }; + + std::for_each(a, a+3, bind(ref(f2), _1)); + + assert(f2.s == 6); + +[endsect] + +[section Using bind with pointers to members] + +Pointers to member functions and pointers to data members are not function +objects, because they do not support `operator()`. For convenience, `bind` +accepts member pointers as its first argument, and the behavior is as if +[@boost:/libs/bind/mem_fn.html `boost::mem_fn`] has been used to convert the +member pointer into a function object. In other words, the expression + + bind(&X::f, args) + +is equivalent to + + bind<R>(``[@boost:/libs/bind/mem_fn.html `mem_fn`]``(&X::f), args) + +where `R` is the return type of `X::f` (for member functions) or the type of +the member (for data members.) + +/[Note:/ `mem_fn` creates function objects that are able to accept a pointer, +a reference, or a smart pointer to an object as its first argument; for +additional information, see the `mem_fn` +[@boost:/libs/bind/mem_fn.html documentation]./]/ + +Example: + + struct X + { + bool f(int a); + }; + + X x; + shared_ptr<X> p(new X); + int i = 5; + + bind(&X::f, ref(x), _1)(i); // x.f(i) + bind(&X::f, &x, _1)(i); // (&x)->f(i) + bind(&X::f, x, _1)(i); // (internal copy of x).f(i) + bind(&X::f, p, _1)(i); // (internal copy of p)->f(i) + +The last two examples are interesting in that they produce "self-contained" +function objects. `bind(&X::f, x, _1)` stores a copy of `x`. +`bind(&X::f, p, _1)` stores a copy of `p`, and since `p` is a +[@boost:/libs/smart_ptr/shared_ptr.htm `boost::shared_ptr`], the function +object retains a reference to its instance of `X` and will remain valid even +when `p` goes out of scope or is `reset()`. + +[endsect] + +[section Using nested binds for function composition] + +Some of the arguments passed to `bind` may be nested /bind expressions/ +themselves: + + bind(f, bind(g, _1))(x); // f(g(x)) + +The inner /bind expressions/ are evaluated, in unspecified order, before the +outer `bind` when the function object is called; the results of the evaluation +are then substituted in their place when the outer `bind` is evaluated. In the +example above, when the function object is called with the argument list `(x)`, +`bind(g, _1)(x)` is evaluated first, yielding `g(x)`, and then +`bind(f, g(x))(x)` is evaluated, yielding the final result `f(g(x))`. + +This feature of `bind` can be used to perform function composition. See +[@../../bind_as_compose.cpp bind_as_compose.cpp] for an example that +demonstrates how to use `bind` to achieve similar functionality to +[@http://www.boost.org/doc/libs/1_31_0/libs/compose/index.htm Boost.Compose]. + +Note that the first argument - the bound function object - is not evaluated, +even when it's a function object that is produced by `bind` or a /placeholder/ +argument, so the example below does not work as expected: + + typedef void (*pf)(int); + + std::vector<pf> v; + std::for_each(v.begin(), v.end(), bind(_1, 5)); + +The desired effect can be achieved via a helper function object `apply` that +applies its first argument, as a function object, to the rest of its argument +list. For convenience, an implementation of `apply` is provided in the +[@../../include/boost/bind/apply.hpp apply.hpp] header file. Here is how the +modified version of the previous example looks like: + + typedef void (*pf)(int); + + std::vector<pf> v; + std::for_each(v.begin(), v.end(), bind(apply<void>(), _1, 5)); + +Although the first argument is, by default, not evaluated, all other arguments +are. Sometimes it is necessary not to evaluate arguments subsequent to the +first, even when they are nested /bind subexpressions/. This can be achieved +with the help of another function object, `protect`, that masks the type so +that `bind` does not recognize and evaluate it. When called, protect simply +forwards the argument list to the other function object unmodified. + +The header [@../../include/boost/bind/protect.hpp protect.hpp] contains an +implementation of `protect`. To `protect` a bind function object from +evaluation, use `protect(bind(f, ...))`. + +[endsect] + +[section Overloaded operators (new in Boost 1.33)] + +For convenience, the function objects produced by `bind` overload the logical +not operator `!` and the relational and logical operators `==, !=, <, <=, >, +>=, &&, ||`. + +`!bind(f, ...)` is equivalent to `bind(logical_not(), bind(f, ...))`, where +`logical_not` is a function object that takes one argument `x` and returns +`!x`. + +`bind(f, ...) op x`, where _op_ is a relational or logical operator, is +equivalent to `bind(relation(), bind(f, ...), x)`, where `relation` is a +function object that takes two arguments `a` and `b` and returns `a op b`. + +What this means in practice is that you can conveniently negate the result of +`bind`: + + std::remove_if(first, last, !bind(&X::visible, _1)); // remove invisible objects + +and compare the result of `bind` against a value: + + std::find_if(first, last, bind(&X::name, _1) == "Peter"); + std::find_if(first, last, bind(&X::name, _1) == "Peter" || bind(&X::name, _1) == "Paul"); + +against a /placeholder/: + + bind(&X::name, _1) == _2 + +or against another /bind expression/: + + std::sort(first, last, bind(&X::name, _1) < bind(&X::name, _2)); // sort by name + +[endsect] + +[endsect] diff --git a/libs/bind/doc/bind/troubleshooting.qbk b/libs/bind/doc/bind/troubleshooting.qbk new file mode 100644 index 000000000..2897a3dde --- /dev/null +++ b/libs/bind/doc/bind/troubleshooting.qbk @@ -0,0 +1,268 @@ +[/ + / 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:troubleshooting Troubleshooting] + +[section Incorrect number of arguments] + +In a `bind(f, a1, a2, ..., aN)` expression, the function object `f` must be +able to take exactly N arguments. This error is normally detected at "bind +time"; in other words, the compilation error is reported on the line where +`bind()` is invoked: + + int f(int, int); + + int main() + { + boost::bind(f, 1); // error, f takes two arguments + boost::bind(f, 1, 2); // OK + } + +A common variation of this error is to forget that member functions have an +implicit "this" argument: + + struct X + { + int f(int); + } + + int main() + { + boost::bind(&X::f, 1); // error, X::f takes two arguments + boost::bind(&X::f, _1, 1); // OK + } + +[endsect] + +[section The function object cannot be called with the specified arguments] + +As in normal function calls, the function object that is bound must be +compatible with the argument list. The incompatibility will usually be +detected by the compiler at "call time" and the result is typically an error +in `bind.hpp` on a line that looks like: + + return f(a[a1_], a[a2_]); + +An example of this kind of error: + + int f(int); + + int main() + { + boost::bind(f, "incompatible"); // OK so far, no call + boost::bind(f, "incompatible")(); // error, "incompatible" is not an int + boost::bind(f, _1); // OK + boost::bind(f, _1)("incompatible"); // error, "incompatible" is not an int + } + +[endsect] + +[section Accessing an argument that does not exist] + +The placeholder `_N` selects the argument at position `N` from the argument +list passed at "call time." Naturally, it is an error to attempt to access +beyond the end of this list: + + int f(int); + + int main() + { + boost::bind(f, _1); // OK + boost::bind(f, _1)(); // error, there is no argument number 1 + } + +The error is usually reported in `bind.hpp`, at a line similar to: + + return f(a[a1_]); + +When emulating `std::bind1st(f, a)`, a common mistake of this category is to +type `bind(f, a, _2)` instead of the correct `bind(f, a, _1)`. + +[endsect] + +[section Inappropriate use of `bind(f, ...)`] + +The `bind(f, a1, a2, ..., aN)` [link bind.faq.Q_forms form] causes automatic +recognition of the type of `f`. It will not work with arbitrary function +objects; `f` must be a function or a member function pointer. + +It is possible to use this form with function objects that define +`result_type`, but only on compilers that support partial specialization and +partial ordering. In particular, MSVC up to version 7.0 does not support this +syntax for function objects. + +[endsect] + +[section Inappropriate use of `bind<R>(f, ...)`] + +The `bind<R>(f, a1, a2, ..., aN)` [link bind.faq.Q_forms form] supports +arbitrary function objects. + +It is possible (but not recommended) to use this form with functions or member +function pointers, but only on compilers that support partial ordering. In +particular, MSVC up to version 7.0 does not fully support this syntax for +functions and member function pointers. + +[endsect] + +[section Binding a nonstandard function] + +By default, the `bind(f, a1, a2, ..., aN)` [link bind.faq.Q_forms form] +recognizes "ordinary" C++ functions and function pointers. [link +bind.implementation.stdcall Functions that use a different calling convention], +or variable-argument functions such as `std::printf`, do not work. The general +`bind<R>(f, a1, a2, ..., aN)` [link bind.faq.Q_forms form] works with +nonstandard functions. + +On some platforms, extern "C" functions, like `std::strcmp`, are not +recognized by the short form of `bind`. + +See also [link bind.implementation.stdcall `__stdcall` and `pascal` Support]. + +[endsect] + +[section Binding an overloaded function] + +An attempt to bind an overloaded function usually results in an error, as +there is no way to tell which overload was meant to be bound. This is a common +problem with member functions with two overloads, const and non-const, as in +this simplified example: + + struct X + { + int& get(); + int const& get() const; + }; + + int main() + { + boost::bind(&X::get, _1); + } + +The ambiguity can be resolved manually by casting the (member) function +pointer to the desired type: + + int main() + { + boost::bind(static_cast< int const& (X::*) () const >(&X::get), _1); + } + +Another, arguably more readable, alternative is to introduce a temporary +variable: + + int main() + { + int const& (X::*get) () const = &X::get; + boost::bind(get, _1); + } + +[endsect] + +[section Modeling STL function object concepts] + +The function objects that are produced by `bind` do not model the STL +[@http://www.sgi.com/tech/stl/UnaryFunction.html /Unary Function/] or +[@http://www.sgi.com/tech/stl/BinaryFunction.html /Binary Function/] concepts, +even when the function objects are unary or binary operations, because the +function object types are missing public typedefs `result_type` and +`argument_type` or `first_argument_type` and `second_argument_type`. In cases +where these typedefs are desirable, however, the utility function +`make_adaptable` can be used to adapt unary and binary function objects to +these concepts. This allows unary and binary function objects resulting from +`bind` to be combined with STL templates such as +[@http://en.cppreference.com/w/cpp/utility/functional/unary_negate `std::unary_negate`] +and [@http://en.cppreference.com/w/cpp/utility/functional/binary_negate `std::binary_negate`]. + +The `make_adaptable` function is defined in [@../../include/boost/bind/make_adaptable.hpp +`<boost/bind/make_adaptable.hpp>`], which must be included explicitly in +addition to [@../../include/boost/bind.hpp `<boost/bind.hpp>`]: + + #include <boost/bind/make_adaptable.hpp> + + template <class R, class F> ``/unspecified-type/`` make_adaptable(F f); + + template<class R, class A1, class F> ``/unspecified-unary-functional-type/`` make_adaptable(F f); + + template<class R, class A1, class A2, class F> ``/unspecified-binary-functional-type/`` make_adaptable(F f); + + template<class R, class A1, class A2, class A3, class F> ``/unspecified-ternary-functional-type/`` make_adaptable(F f); + + template<class R, class A1, class A2, class A3, class A4, class F> ``/unspecified-4-ary-functional-type/`` make_adaptable(F f); + +This example shows how to use `make_adaptable` to make a predicate for "is not a space": + + typedef char char_t; + std::locale loc(""); + const std::ctype<char_t>& ct = std::use_facet<std::ctype<char_t> >(loc); + + auto isntspace = std::not1(boost::make_adaptable<bool, char_t>(boost::bind(&std::ctype<char_t>::is, &ct, std::ctype_base::space, _1))); + +In this example, `bind` creates the "is a space" (unary) predicate. It is then +passed to `make_adaptable` so that a function object modeling the /Unary +Function/ concept can be created, serving as the argument to +[@http://en.cppreference.com/w/cpp/utility/functional/not1 `std::not1`]. + +[endsect] + +[section `const` in signatures] + +Some compilers, including MSVC 6.0 and Borland C++ 5.5.1, have problems with +the top-level `const` in function signatures: + + int f(int const); + + int main() + { + boost::bind(f, 1); // error + } + +Workaround: remove the `const` qualifier from the argument. + +[endsect] + +[section MSVC specific: `using boost::bind;`] + +On MSVC (up to version 7.0), when `boostbind` is brought into scope with an +using declaration: + + using boost::bind; + +the syntax `bind<R>(f, ...)` does not work. Workaround: either use the +qualified name, `boost::bind`, or use an using directive instead: + + using namespace boost; + +[endsect] + +[section MSVC specific: class templates shadow function templates] + +On MSVC (up to version 7.0), a nested class template named `bind` will shadow +the function template `boost::bind`, breaking the `bind<R>(f, ...)`syntax. +Unfortunately, some libraries contain nested class templates named `bind` +(ironically, such code is often an MSVC specific workaround.) + +The workaround is to use the alternative `bind(type<R>(), f, ...)` syntax. + +[endsect] + +[section MSVC specific: `...` in signatures treated as type] + +MSVC (up to version 7.0) treats the ellipsis in a variable argument function +(such as `std::printf`) as a type. Therefore, it will accept the (incorrect in +the current implementation) form: + + bind(printf, "%s\n", _1); + +and will reject the correct version: + + bind<int>(printf, "%s\n", _1); + +[endsect] + +[endsect] diff --git a/libs/bind/doc/html/bind.html b/libs/bind/doc/html/bind.html new file mode 100644 index 000000000..491582b70 --- /dev/null +++ b/libs/bind/doc/html/bind.html @@ -0,0 +1,1552 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Chapter 1. Boost.Bind</title> +<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="bind.html" title="Chapter 1. Boost.Bind"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> +<td align="center"><a href="../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"></div> +<div class="chapter"> +<div class="titlepage"><div> +<div><h2 class="title"> +<a name="bind"></a>Chapter 1. Boost.Bind</h2></div> +<div><p class="copyright">Copyright © 2001, 2002 Peter Dimov and Multi Media Ltd.</p></div> +<div><p class="copyright">Copyright © 2003-2008 Peter Dimov</p></div> +<div><div class="legalnotice"> +<a name="bind.legal"></a><p> + Distributed under the <a href="http://boost.org/LICENSE_1_0.txt" target="_top">Boost + Software License, Version 1.0</a>. + </p> +</div></div> +</div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="bind.html#bind.purpose">Purpose</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="bind.html#bind.purpose.using_bind_with_functions_and_fu">Using + bind with functions and function pointers</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.purpose.with_function_objects">Using bind with function + objects</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.purpose.using_bind_with_pointers_to_memb">Using + bind with pointers to members</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.purpose.using_nested_binds_for_function_">Using + nested binds for function composition</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.purpose.overloaded_operators_new_in_boos">Overloaded + operators (new in Boost 1.33)</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="bind.html#bind.examples">Examples</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="bind.html#bind.examples.using_bind_with_standard_algorit">Using + bind with standard algorithms</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.examples.using_bind_with_boost_function">Using bind + with Boost.Function</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="bind.html#bind.limitations">Limitations</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.faq">Frequently Asked Questions</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="bind.html#bind.faq.why_doesn_t_this_compile">Why doesn't this compile?</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.faq.why_does_this_compile_it_should_">Why does this + compile? It should not.</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.faq.Q_forms">What is the difference between <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> and + <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code>?</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.faq.does_bind_work_with_windows_api_">Does bind + work with Windows API functions?</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.faq.does_bind_work_with_com_methods">Does bind work + with COM methods?</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.faq.does_bind_work_with_mac_toolbox_">Does bind + work with Mac toolbox functions?</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.faq.does_bind_work_with_extern_c_fun">Does bind + work with extern "C" functions?</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.faq.why_doesn_t_bind_automatically_r">Why doesn't + bind automatically recognize nonstandard functions?</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="bind.html#bind.troubleshooting">Troubleshooting</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.incorrect_number_of_arguments">Incorrect + number of arguments</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.the_function_object_cannot_be_ca">The + function object cannot be called with the specified arguments</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.accessing_an_argument_that_does_">Accessing + an argument that does not exist</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.inappropriate_use_of_bind_f">Inappropriate + use of <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code></a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.inappropriate_use_of_bind_r_f">Inappropriate + use of <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code></a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.binding_a_nonstandard_function">Binding + a nonstandard function</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.binding_an_overloaded_function">Binding + an overloaded function</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.modeling_stl_function_object_con">Modeling + STL function object concepts</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.const_in_signatures"><code class="computeroutput"><span class="keyword">const</span></code> in signatures</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.msvc_specific_using_boost_bind">MSVC + specific: <code class="computeroutput"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">;</span></code></a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.msvc_specific_class_templates_sh">MSVC + specific: class templates shadow function templates</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.msvc_specific_in_signatures_trea">MSVC + specific: <code class="computeroutput"><span class="special">...</span></code> in signatures treated + as type</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="bind.html#bind.interface">Interface</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="bind.html#bind.interface.synopsys">Synopsis</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.interface.common_requirements">Common requirements</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.interface.common_definitions">Common definitions</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.interface.bind"><code class="computeroutput"><span class="identifier">bind</span></code></a></span></dt> +<dt><span class="section"><a href="bind.html#bind.interface.additional_overloads">Additional overloads</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="bind.html#bind.implementation">Implementation</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="bind.html#bind.implementation.files">Files</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.implementation.dependencies">Dependencies</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.implementation.number_of_arguments">Number of Arguments</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.implementation.stdcall"><code class="computeroutput"><span class="identifier">__stdcall</span></code>, + <code class="computeroutput"><span class="identifier">__cdecl</span></code>, <code class="computeroutput"><span class="identifier">__fastcall</span></code>, + and <code class="computeroutput"><span class="identifier">pascal</span></code> Support</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.implementation.visit_each_support"><code class="computeroutput"><span class="identifier">visit_each</span></code> support</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="bind.html#bind.acknowledgements">Acknowledgements</a></span></dt> +</dl> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bind.purpose"></a><a class="link" href="bind.html#bind.purpose" title="Purpose">Purpose</a> +</h2></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span></code> is a generalization of the standard + functions <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind1st</span></code> and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind2nd</span></code>. + It supports arbitrary function objects, functions, function pointers, and member + function pointers, and is able to bind any argument to a specific value or + route input arguments into arbitrary positions. <code class="computeroutput"><span class="identifier">bind</span></code> + does not place any requirements on the function object; in particular, it does + not need the <code class="computeroutput"><span class="identifier">result_type</span></code>, + <code class="computeroutput"><span class="identifier">first_argument_type</span></code> and <code class="computeroutput"><span class="identifier">second_argument_type</span></code> standard typedefs. + </p> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.purpose.using_bind_with_functions_and_fu"></a><a class="link" href="bind.html#bind.purpose.using_bind_with_functions_and_fu" title="Using bind with functions and function pointers">Using + bind with functions and function pointers</a> +</h3></div></div></div> +<p> + Given these definitions: + </p> +<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">b</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">a</span> <span class="special">+</span> <span class="identifier">b</span><span class="special">;</span> +<span class="special">}</span> + +<span class="keyword">int</span> <span class="identifier">g</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">b</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">c</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">a</span> <span class="special">+</span> <span class="identifier">b</span> <span class="special">+</span> <span class="identifier">c</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">)</span></code> + will produce a "nullary" function object that takes no arguments + and returns <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">)</span></code>. Similarly, <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">g</span><span class="special">,</span> + <span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">)()</span></code> is equivalent <code class="computeroutput"><span class="identifier">to</span> + <span class="identifier">g</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">)</span></code>. + </p> +<p> + It is possible to selectively bind only some of the arguments. <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> + <span class="number">5</span><span class="special">)(</span><span class="identifier">x</span><span class="special">)</span></code> is equivalent + to <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="number">5</span><span class="special">)</span></code>; here <code class="computeroutput"><span class="identifier">_1</span></code> + is a <span class="emphasis"><em>placeholder</em></span> argument that means "substitute + with the first input argument." + </p> +<p> + For comparison, here is the same operation expressed with the standard library + primitives: + </p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind2nd</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ptr_fun</span><span class="special">(</span><span class="identifier">f</span><span class="special">),</span> <span class="number">5</span><span class="special">)(</span><span class="identifier">x</span><span class="special">);</span> +</pre> +<p> + <code class="computeroutput"><span class="identifier">bind</span></code> covers the functionality + of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind1st</span></code> as well: + </p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind1st</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ptr_fun</span><span class="special">(</span><span class="identifier">f</span><span class="special">),</span> <span class="number">5</span><span class="special">)(</span><span class="identifier">x</span><span class="special">);</span> <span class="comment">// f(5, x)</span> +<span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="number">5</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">x</span><span class="special">);</span> <span class="comment">// f(5, x)</span> +</pre> +<p> + <code class="computeroutput"><span class="identifier">bind</span></code> can handle functions + with more than two arguments, and its argument substitution mechanism is + more general: + </p> +<pre class="programlisting"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">_2</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">y</span><span class="special">);</span> <span class="comment">// f(y, x)</span> +<span class="identifier">bind</span><span class="special">(</span><span class="identifier">g</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> <span class="number">9</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">x</span><span class="special">);</span> <span class="comment">// g(x, 9, x)</span> +<span class="identifier">bind</span><span class="special">(</span><span class="identifier">g</span><span class="special">,</span> <span class="identifier">_3</span><span class="special">,</span> <span class="identifier">_3</span><span class="special">,</span> <span class="identifier">_3</span><span class="special">)(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">z</span><span class="special">);</span> <span class="comment">// g(z, z, z)</span> +<span class="identifier">bind</span><span class="special">(</span><span class="identifier">g</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">z</span><span class="special">);</span> <span class="comment">// g(x, x, x)</span> +</pre> +<p> + Note that, in the last example, the function object produced by <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">g</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> + <span class="identifier">_1</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)</span></code> does + not contain references to any arguments beyond the first, but it can still + be used with more than one argument. Any extra arguments are silently ignored, + just like the first and the second argument are ignored in the third example. + </p> +<p> + The arguments that <code class="computeroutput"><span class="identifier">bind</span></code> takes + are copied and held internally by the returned function object. For example, + in the following code: + </p> +<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">5</span><span class="special">;</span> +<span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">i</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">);</span> +</pre> +<p> + a copy of the value of <code class="computeroutput"><span class="identifier">i</span></code> + is stored into the function object. <a href="../../../../libs/core/doc/html/core/ref.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">ref</span></code></a> and <a href="../../../../libs/core/doc/html/core/ref.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">cref</span></code></a> can be used to make the function + object store a reference to an object, rather than a copy: + </p> +<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">5</span><span class="special">;</span> +<span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">ref</span><span class="special">(</span><span class="identifier">i</span><span class="special">),</span> <span class="identifier">_1</span><span class="special">);</span> +<span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">cref</span><span class="special">(</span><span class="identifier">i</span><span class="special">),</span> <span class="identifier">_1</span><span class="special">);</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.purpose.with_function_objects"></a><a class="link" href="bind.html#bind.purpose.with_function_objects" title="Using bind with function objects">Using bind with function + objects</a> +</h3></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">bind</span></code> is not limited to functions; + it accepts arbitrary function objects. In the general case, the return type + of the generated function object's <code class="computeroutput"><span class="keyword">operator</span><span class="special">()</span></code> has to be specified explicitly (without + a <code class="computeroutput"><span class="identifier">typeof</span></code> operator the return + type cannot be inferred): + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">F</span> +<span class="special">{</span> + <span class="keyword">int</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">int</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">b</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">a</span> <span class="special">-</span> <span class="identifier">b</span><span class="special">;</span> <span class="special">}</span> + <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">long</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">long</span> <span class="identifier">b</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">a</span> <span class="special">==</span> <span class="identifier">b</span><span class="special">;</span> <span class="special">}</span> +<span class="special">};</span> + +<span class="identifier">F</span> <span class="identifier">f</span><span class="special">;</span> +<span class="keyword">int</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">104</span><span class="special">;</span> +<span class="identifier">bind</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">x</span><span class="special">);</span> <span class="comment">// f(x, x), i.e. zero</span> +</pre> +<p> + Some compilers have trouble with the <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> + syntax. For portability reasons, an alternative way to express the above + is supported: + </p> +<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">type</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(),</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">x</span><span class="special">);</span> +</pre> +<p> + Note, however, that the alternative syntax is provided only as a workaround. + It is not part of the interface. + </p> +<p> + When the function object exposes a nested type named <code class="computeroutput"><span class="identifier">result_type</span></code>, + the explicit return type can be omitted: + </p> +<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">8</span><span class="special">;</span> +<span class="identifier">bind</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">less</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(),</span> <span class="identifier">_1</span><span class="special">,</span> <span class="number">9</span><span class="special">)(</span><span class="identifier">x</span><span class="special">);</span> <span class="comment">// x < 9</span> +</pre> +<p> + <span class="emphasis"><em>[Note:</em></span> the ability to omit the return type is not available + on all compilers.<span class="emphasis"><em>]</em></span> + </p> +<p> + By default, <code class="computeroutput"><span class="identifier">bind</span></code> makes a + copy of the provided function object. <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">ref</span></code> and + <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">cref</span></code> can be used to make it store a reference + to the function object, rather than a copy. This can be useful when the function + object is non-copyable, expensive to copy, or contains state; of course, + in this case the programmer is expected to ensure that the function object + is not destroyed while it's still being used. + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">F2</span> +<span class="special">{</span> + <span class="keyword">int</span> <span class="identifier">s</span><span class="special">;</span> + + <span class="keyword">typedef</span> <span class="keyword">void</span> <span class="identifier">result_type</span><span class="special">;</span> + <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="identifier">s</span> <span class="special">+=</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span> +<span class="special">};</span> + +<span class="identifier">F2</span> <span class="identifier">f2</span> <span class="special">=</span> <span class="special">{</span> <span class="number">0</span> <span class="special">};</span> +<span class="keyword">int</span> <span class="identifier">a</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span> <span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span> <span class="special">};</span> + +<span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">a</span><span class="special">+</span><span class="number">3</span><span class="special">,</span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">f2</span><span class="special">),</span> <span class="identifier">_1</span><span class="special">));</span> + +<span class="identifier">assert</span><span class="special">(</span><span class="identifier">f2</span><span class="special">.</span><span class="identifier">s</span> <span class="special">==</span> <span class="number">6</span><span class="special">);</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.purpose.using_bind_with_pointers_to_memb"></a><a class="link" href="bind.html#bind.purpose.using_bind_with_pointers_to_memb" title="Using bind with pointers to members">Using + bind with pointers to members</a> +</h3></div></div></div> +<p> + Pointers to member functions and pointers to data members are not function + objects, because they do not support <code class="computeroutput"><span class="keyword">operator</span><span class="special">()</span></code>. For convenience, <code class="computeroutput"><span class="identifier">bind</span></code> + accepts member pointers as its first argument, and the behavior is as if + <a href="../../../../libs/bind/mem_fn.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span></code></a> + has been used to convert the member pointer into a function object. In other + words, the expression + </p> +<pre class="programlisting"><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">args</span><span class="special">)</span> +</pre> +<p> + is equivalent to + </p> +<pre class="programlisting"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><a href="../../../../libs/bind/mem_fn.html" target="_top"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">),</span> <span class="identifier">args</span><span class="special">)</span> +</pre> +<p> + where <code class="computeroutput"><span class="identifier">R</span></code> is the return type + of <code class="computeroutput"><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span></code> (for member functions) or the type of + the member (for data members.) + </p> +<p> + <span class="emphasis"><em>[Note:</em></span> <code class="computeroutput"><span class="identifier">mem_fn</span></code> + creates function objects that are able to accept a pointer, a reference, + or a smart pointer to an object as its first argument; for additional information, + see the <code class="computeroutput"><span class="identifier">mem_fn</span></code> <a href="../../../../libs/bind/mem_fn.html" target="_top">documentation</a>.<span class="emphasis"><em>]</em></span> + </p> +<p> + Example: + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">X</span> +<span class="special">{</span> + <span class="keyword">bool</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">a</span><span class="special">);</span> +<span class="special">};</span> + +<span class="identifier">X</span> <span class="identifier">x</span><span class="special">;</span> +<span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">X</span><span class="special">></span> <span class="identifier">p</span><span class="special">(</span><span class="keyword">new</span> <span class="identifier">X</span><span class="special">);</span> +<span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">5</span><span class="special">;</span> + +<span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">ref</span><span class="special">(</span><span class="identifier">x</span><span class="special">),</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">i</span><span class="special">);</span> <span class="comment">// x.f(i)</span> +<span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="special">&</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">i</span><span class="special">);</span> <span class="comment">// (&x)->f(i)</span> +<span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">i</span><span class="special">);</span> <span class="comment">// (internal copy of x).f(i)</span> +<span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">i</span><span class="special">);</span> <span class="comment">// (internal copy of p)->f(i)</span> +</pre> +<p> + The last two examples are interesting in that they produce "self-contained" + function objects. <code class="computeroutput"><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">x</span><span class="special">,</span> + <span class="identifier">_1</span><span class="special">)</span></code> + stores a copy of <code class="computeroutput"><span class="identifier">x</span></code>. <code class="computeroutput"><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> + <span class="identifier">_1</span><span class="special">)</span></code> + stores a copy of <code class="computeroutput"><span class="identifier">p</span></code>, and since + <code class="computeroutput"><span class="identifier">p</span></code> is a <a href="../../../../libs/smart_ptr/shared_ptr.htm" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span></code></a>, the function object + retains a reference to its instance of <code class="computeroutput"><span class="identifier">X</span></code> + and will remain valid even when <code class="computeroutput"><span class="identifier">p</span></code> + goes out of scope or is <code class="computeroutput"><span class="identifier">reset</span><span class="special">()</span></code>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.purpose.using_nested_binds_for_function_"></a><a class="link" href="bind.html#bind.purpose.using_nested_binds_for_function_" title="Using nested binds for function composition">Using + nested binds for function composition</a> +</h3></div></div></div> +<p> + Some of the arguments passed to <code class="computeroutput"><span class="identifier">bind</span></code> + may be nested <span class="emphasis"><em>bind expressions</em></span> themselves: + </p> +<pre class="programlisting"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">g</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">))(</span><span class="identifier">x</span><span class="special">);</span> <span class="comment">// f(g(x))</span> +</pre> +<p> + The inner <span class="emphasis"><em>bind expressions</em></span> are evaluated, in unspecified + order, before the outer <code class="computeroutput"><span class="identifier">bind</span></code> + when the function object is called; the results of the evaluation are then + substituted in their place when the outer <code class="computeroutput"><span class="identifier">bind</span></code> + is evaluated. In the example above, when the function object is called with + the argument list <code class="computeroutput"><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code>, <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">g</span><span class="special">,</span> + <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">x</span><span class="special">)</span></code> is evaluated + first, yielding <code class="computeroutput"><span class="identifier">g</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code>, and + then <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">g</span><span class="special">(</span><span class="identifier">x</span><span class="special">))(</span><span class="identifier">x</span><span class="special">)</span></code> is evaluated, + yielding the final result <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span><span class="identifier">g</span><span class="special">(</span><span class="identifier">x</span><span class="special">))</span></code>. + </p> +<p> + This feature of <code class="computeroutput"><span class="identifier">bind</span></code> can + be used to perform function composition. See <a href="../../bind_as_compose.cpp" target="_top">bind_as_compose.cpp</a> + for an example that demonstrates how to use <code class="computeroutput"><span class="identifier">bind</span></code> + to achieve similar functionality to <a href="http://www.boost.org/doc/libs/1_31_0/libs/compose/index.htm" target="_top">Boost.Compose</a>. + </p> +<p> + Note that the first argument - the bound function object - is not evaluated, + even when it's a function object that is produced by <code class="computeroutput"><span class="identifier">bind</span></code> + or a <span class="emphasis"><em>placeholder</em></span> argument, so the example below does + not work as expected: + </p> +<pre class="programlisting"><span class="keyword">typedef</span> <span class="keyword">void</span> <span class="special">(*</span><span class="identifier">pf</span><span class="special">)(</span><span class="keyword">int</span><span class="special">);</span> + +<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="identifier">pf</span><span class="special">></span> <span class="identifier">v</span><span class="special">;</span> +<span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">v</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">_1</span><span class="special">,</span> <span class="number">5</span><span class="special">));</span> +</pre> +<p> + The desired effect can be achieved via a helper function object <code class="computeroutput"><span class="identifier">apply</span></code> that applies its first argument, + as a function object, to the rest of its argument list. For convenience, + an implementation of <code class="computeroutput"><span class="identifier">apply</span></code> + is provided in the <a href="../../include/boost/bind/apply.hpp" target="_top">apply.hpp</a> + header file. Here is how the modified version of the previous example looks + like: + </p> +<pre class="programlisting"><span class="keyword">typedef</span> <span class="keyword">void</span> <span class="special">(*</span><span class="identifier">pf</span><span class="special">)(</span><span class="keyword">int</span><span class="special">);</span> + +<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="identifier">pf</span><span class="special">></span> <span class="identifier">v</span><span class="special">;</span> +<span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">v</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">apply</span><span class="special"><</span><span class="keyword">void</span><span class="special">>(),</span> <span class="identifier">_1</span><span class="special">,</span> <span class="number">5</span><span class="special">));</span> +</pre> +<p> + Although the first argument is, by default, not evaluated, all other arguments + are. Sometimes it is necessary not to evaluate arguments subsequent to the + first, even when they are nested <span class="emphasis"><em>bind subexpressions</em></span>. + This can be achieved with the help of another function object, <code class="computeroutput"><span class="identifier">protect</span></code>, that masks the type so that <code class="computeroutput"><span class="identifier">bind</span></code> does not recognize and evaluate it. + When called, protect simply forwards the argument list to the other function + object unmodified. + </p> +<p> + The header <a href="../../include/boost/bind/protect.hpp" target="_top">protect.hpp</a> + contains an implementation of <code class="computeroutput"><span class="identifier">protect</span></code>. + To <code class="computeroutput"><span class="identifier">protect</span></code> a bind function + object from evaluation, use <code class="computeroutput"><span class="identifier">protect</span><span class="special">(</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...))</span></code>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.purpose.overloaded_operators_new_in_boos"></a><a class="link" href="bind.html#bind.purpose.overloaded_operators_new_in_boos" title="Overloaded operators (new in Boost 1.33)">Overloaded + operators (new in Boost 1.33)</a> +</h3></div></div></div> +<p> + For convenience, the function objects produced by <code class="computeroutput"><span class="identifier">bind</span></code> + overload the logical not operator <code class="computeroutput"><span class="special">!</span></code> + and the relational and logical operators <code class="computeroutput"><span class="special">==,</span> + <span class="special">!=,</span> <span class="special"><,</span> + <span class="special"><=,</span> <span class="special">>,</span> + <span class="special">>=,</span> <span class="special">&&,</span> + <span class="special">||</span></code>. + </p> +<p> + <code class="computeroutput"><span class="special">!</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> + <span class="special">...)</span></code> is equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">logical_not</span><span class="special">(),</span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> + <span class="special">...))</span></code>, where <code class="computeroutput"><span class="identifier">logical_not</span></code> + is a function object that takes one argument <code class="computeroutput"><span class="identifier">x</span></code> + and returns <code class="computeroutput"><span class="special">!</span><span class="identifier">x</span></code>. + </p> +<p> + <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span> + <span class="identifier">op</span> <span class="identifier">x</span></code>, + where <span class="underline">op</span> is a relational or logical + operator, is equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">relation</span><span class="special">(),</span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> + <span class="special">...),</span> <span class="identifier">x</span><span class="special">)</span></code>, where <code class="computeroutput"><span class="identifier">relation</span></code> + is a function object that takes two arguments <code class="computeroutput"><span class="identifier">a</span></code> + and <code class="computeroutput"><span class="identifier">b</span></code> and returns <code class="computeroutput"><span class="identifier">a</span> <span class="identifier">op</span> <span class="identifier">b</span></code>. + </p> +<p> + What this means in practice is that you can conveniently negate the result + of <code class="computeroutput"><span class="identifier">bind</span></code>: + </p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">remove_if</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="special">!</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">visible</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">));</span> <span class="comment">// remove invisible objects</span> +</pre> +<p> + and compare the result of <code class="computeroutput"><span class="identifier">bind</span></code> + against a value: + </p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">find_if</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)</span> <span class="special">==</span> <span class="string">"Peter"</span><span class="special">);</span> +<span class="identifier">std</span><span class="special">::</span><span class="identifier">find_if</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)</span> <span class="special">==</span> <span class="string">"Peter"</span> <span class="special">||</span> <span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)</span> <span class="special">==</span> <span class="string">"Paul"</span><span class="special">);</span> +</pre> +<p> + against a <span class="emphasis"><em>placeholder</em></span>: + </p> +<pre class="programlisting"><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)</span> <span class="special">==</span> <span class="identifier">_2</span> +</pre> +<p> + or against another <span class="emphasis"><em>bind expression</em></span>: + </p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">sort</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)</span> <span class="special"><</span> <span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">_2</span><span class="special">));</span> <span class="comment">// sort by name</span> +</pre> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bind.examples"></a><a class="link" href="bind.html#bind.examples" title="Examples">Examples</a> +</h2></div></div></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.examples.using_bind_with_standard_algorit"></a><a class="link" href="bind.html#bind.examples.using_bind_with_standard_algorit" title="Using bind with standard algorithms">Using + bind with standard algorithms</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">image</span><span class="special">;</span> + +<span class="keyword">class</span> <span class="identifier">animation</span> +<span class="special">{</span> +<span class="keyword">public</span><span class="special">:</span> + <span class="keyword">void</span> <span class="identifier">advance</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">ms</span><span class="special">);</span> + <span class="keyword">bool</span> <span class="identifier">inactive</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">void</span> <span class="identifier">render</span><span class="special">(</span><span class="identifier">image</span> <span class="special">&</span> <span class="identifier">target</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="special">};</span> + +<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="identifier">animation</span><span class="special">></span> <span class="identifier">anims</span><span class="special">;</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">C</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">P</span><span class="special">></span> <span class="keyword">void</span> <span class="identifier">erase_if</span><span class="special">(</span><span class="identifier">C</span> <span class="special">&</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">P</span> <span class="identifier">pred</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">c</span><span class="special">.</span><span class="identifier">erase</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">remove_if</span><span class="special">(</span><span class="identifier">c</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">c</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">pred</span><span class="special">),</span> <span class="identifier">c</span><span class="special">.</span><span class="identifier">end</span><span class="special">());</span> +<span class="special">}</span> + +<span class="keyword">void</span> <span class="identifier">update</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">ms</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">anims</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">anims</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">animation</span><span class="special">::</span><span class="identifier">advance</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> <span class="identifier">ms</span><span class="special">));</span> + <span class="identifier">erase_if</span><span class="special">(</span><span class="identifier">anims</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span><span class="special">(&</span><span class="identifier">animation</span><span class="special">::</span><span class="identifier">inactive</span><span class="special">));</span> +<span class="special">}</span> + +<span class="keyword">void</span> <span class="identifier">render</span><span class="special">(</span><span class="identifier">image</span> <span class="special">&</span> <span class="identifier">target</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">anims</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">anims</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">animation</span><span class="special">::</span><span class="identifier">render</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">target</span><span class="special">)));</span> +<span class="special">}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.examples.using_bind_with_boost_function"></a><a class="link" href="bind.html#bind.examples.using_bind_with_boost_function" title="Using bind with Boost.Function">Using bind + with Boost.Function</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">button</span> +<span class="special">{</span> +<span class="keyword">public</span><span class="special">:</span> + <a href="../../../../libs/function/index.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">function</span></code></a><span class="special"><</span><span class="keyword">void</span><span class="special">()></span> <span class="identifier">onClick</span><span class="special">;</span> +<span class="special">};</span> + +<span class="keyword">class</span> <span class="identifier">player</span> +<span class="special">{</span> +<span class="keyword">public</span><span class="special">:</span> + <span class="keyword">void</span> <span class="identifier">play</span><span class="special">();</span> + <span class="keyword">void</span> <span class="identifier">stop</span><span class="special">();</span> +<span class="special">};</span> + +<span class="identifier">button</span> <span class="identifier">playButton</span><span class="special">,</span> <span class="identifier">stopButton</span><span class="special">;</span> +<span class="identifier">player</span> <span class="identifier">thePlayer</span><span class="special">;</span> + +<span class="keyword">void</span> <span class="identifier">connect</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">playButton</span><span class="special">.</span><span class="identifier">onClick</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">player</span><span class="special">::</span><span class="identifier">play</span><span class="special">,</span> <span class="special">&</span><span class="identifier">thePlayer</span><span class="special">);</span> + <span class="identifier">stopButton</span><span class="special">.</span><span class="identifier">onClick</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">player</span><span class="special">::</span><span class="identifier">stop</span><span class="special">,</span> <span class="special">&</span><span class="identifier">thePlayer</span><span class="special">);</span> +<span class="special">}</span> +</pre> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bind.limitations"></a><a class="link" href="bind.html#bind.limitations" title="Limitations">Limitations</a> +</h2></div></div></div> +<p> + As a general rule, the function objects generated by <code class="computeroutput"><span class="identifier">bind</span></code> + 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 <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2002/n1385.htm" target="_top">forwarding + problem</a>. (It will be fixed in the next standard, usually called C++0x.) + </p> +<p> + The library uses signatures of the form + </p> +<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">T</span> <span class="special">&</span> <span class="identifier">t</span><span class="special">);</span> +</pre> +<p> + to accept arguments of arbitrary types and pass them on unmodified. As noted, + this does not work with non-const r-values. + </p> +<p> + On compilers that support partial ordering of function templates, a possible + solution is to add an overload: + </p> +<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">T</span> <span class="special">&</span> <span class="identifier">t</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span> <span class="special">&</span> <span class="identifier">t</span><span class="special">);</span> +</pre> +<p> + 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. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bind.faq"></a><a class="link" href="bind.html#bind.faq" title="Frequently Asked Questions">Frequently Asked Questions</a> +</h2></div></div></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.faq.why_doesn_t_this_compile"></a><a class="link" href="bind.html#bind.faq.why_doesn_t_this_compile" title="Why doesn't this compile?">Why doesn't this compile?</a> +</h3></div></div></div> +<p> + See the dedicated <a class="link" href="bind.html#bind.troubleshooting" title="Troubleshooting">Troubleshooting section</a>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.faq.why_does_this_compile_it_should_"></a><a class="link" href="bind.html#bind.faq.why_does_this_compile_it_should_" title="Why does this compile? It should not.">Why does this + compile? It should not.</a> +</h3></div></div></div> +<p> + Probably because you used the general <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> + syntax, thereby instructing <code class="computeroutput"><span class="identifier">bind</span></code> + to not "inspect" f to detect arity and return type errors. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.faq.Q_forms"></a><a class="link" href="bind.html#bind.faq.Q_forms" title="What is the difference between bind(f, ...) and bind<R>(f, ...)?">What is the difference between <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> and + <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code>?</a> +</h3></div></div></div> +<p> + The first form instructs <code class="computeroutput"><span class="identifier">bind</span></code> + to inspect the type of <code class="computeroutput"><span class="identifier">f</span></code> + in order to determine its arity (number of arguments) and return type. Arity + errors will be detected at "bind time". This syntax, of course, + places some requirements on <code class="computeroutput"><span class="identifier">f</span></code>. + It must be a function, function pointer, member function pointer, or a function + object that defines a nested type named <code class="computeroutput"><span class="identifier">result_type</span></code>; + in short, it must be something that <code class="computeroutput"><span class="identifier">bind</span></code> + can recognize. + </p> +<p> + The second form instructs <code class="computeroutput"><span class="identifier">bind</span></code> + to not attempt to recognize the type of <code class="computeroutput"><span class="identifier">f</span></code>. + It is generally used with function objects that do not, or cannot, expose + <code class="computeroutput"><span class="identifier">result_type</span></code>, but it can also + be used with nonstandard functions. For example, the current implementation + does not automatically recognize variable-argument functions like <code class="computeroutput"><span class="identifier">printf</span></code>, so you will have to use <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">printf</span><span class="special">,</span> <span class="special">...)</span></code>. Note + that an alternative <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">type</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(),</span> <span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> + syntax is supported for portability reasons. + </p> +<p> + Another important factor to consider is that compilers without partial template + specialization or function template partial ordering support cannot handle + the first form when <code class="computeroutput"><span class="identifier">f</span></code> is + a function object, and in most cases will not handle the second form when + <code class="computeroutput"><span class="identifier">f</span></code> is a function (pointer) + or a member function pointer. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.faq.does_bind_work_with_windows_api_"></a><a class="link" href="bind.html#bind.faq.does_bind_work_with_windows_api_" title="Does bind work with Windows API functions?">Does bind + work with Windows API functions?</a> +</h3></div></div></div> +<p> + Yes, if you <a class="link" href="bind.html#bind.implementation.stdcall" title="__stdcall, __cdecl, __fastcall, and pascal Support"><code class="computeroutput"><span class="preprocessor">#define</span> + <span class="identifier">BOOST_BIND_ENABLE_STDCALL</span></code></a>. + An alternative is to treat the function as a <a class="link" href="bind.html#bind.purpose.with_function_objects" title="Using bind with function objects">generic + function object</a> and use the <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> + syntax. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.faq.does_bind_work_with_com_methods"></a><a class="link" href="bind.html#bind.faq.does_bind_work_with_com_methods" title="Does bind work with COM methods?">Does bind work + with COM methods?</a> +</h3></div></div></div> +<p> + Yes, if you <a class="link" href="bind.html#bind.implementation.stdcall" title="__stdcall, __cdecl, __fastcall, and pascal Support"><code class="computeroutput"><span class="preprocessor">#define</span> + <span class="identifier">BOOST_MEM_FN_ENABLE_STDCALL</span></code></a>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.faq.does_bind_work_with_mac_toolbox_"></a><a class="link" href="bind.html#bind.faq.does_bind_work_with_mac_toolbox_" title="Does bind work with Mac toolbox functions?">Does bind + work with Mac toolbox functions?</a> +</h3></div></div></div> +<p> + Yes, if you <a class="link" href="bind.html#bind.implementation.stdcall" title="__stdcall, __cdecl, __fastcall, and pascal Support"><code class="computeroutput"><span class="preprocessor">#define</span> + <span class="identifier">BOOST_BIND_ENABLE_PASCAL</span></code></a>. + An alternative is to treat the function as a <a class="link" href="bind.html#bind.purpose.with_function_objects" title="Using bind with function objects">generic + function object</a> and use the <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> + syntax. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.faq.does_bind_work_with_extern_c_fun"></a><a class="link" href="bind.html#bind.faq.does_bind_work_with_extern_c_fun" title='Does bind work with extern "C" functions?'>Does bind + work with extern "C" functions?</a> +</h3></div></div></div> +<p> + Sometimes. On some platforms, pointers to extern "C" functions + are equivalent to "ordinary" function pointers, so they work fine. + Other platforms treat them as different types. A platform-specific implementation + of <code class="computeroutput"><span class="identifier">bind</span></code> is expected to handle + the problem transparently; this implementation does not. As usual, the workaround + is to treat the function as a <a class="link" href="bind.html#bind.purpose.with_function_objects" title="Using bind with function objects">generic + function object</a> and use the <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> + syntax. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.faq.why_doesn_t_bind_automatically_r"></a><a class="link" href="bind.html#bind.faq.why_doesn_t_bind_automatically_r" title="Why doesn't bind automatically recognize nonstandard functions?">Why doesn't + bind automatically recognize nonstandard functions?</a> +</h3></div></div></div> +<p> + Non-portable extensions, in general, should default to off to prevent vendor + lock-in. Had the <a class="link" href="bind.html#bind.implementation.stdcall" title="__stdcall, __cdecl, __fastcall, and pascal Support">appropriate + macros</a> been defined automatically, you could have accidentally taken + advantage of them without realizing that your code is, perhaps, no longer + portable. In addition, some compilers have the option to make <code class="computeroutput"><span class="identifier">__stdcall</span></code> (<code class="computeroutput"><span class="identifier">__fastcall</span></code>) + their default calling convention, in which case no separate support would + be necessary. + </p> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bind.troubleshooting"></a><a class="link" href="bind.html#bind.troubleshooting" title="Troubleshooting">Troubleshooting</a> +</h2></div></div></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.incorrect_number_of_arguments"></a><a class="link" href="bind.html#bind.troubleshooting.incorrect_number_of_arguments" title="Incorrect number of arguments">Incorrect + number of arguments</a> +</h3></div></div></div> +<p> + In a <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,</span> + <span class="special">...,</span> <span class="identifier">aN</span><span class="special">)</span></code> expression, the function object <code class="computeroutput"><span class="identifier">f</span></code> must be able to take exactly N arguments. + This error is normally detected at "bind time"; in other words, + the compilation error is reported on the line where <code class="computeroutput"><span class="identifier">bind</span><span class="special">()</span></code> is invoked: + </p> +<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">int</span><span class="special">);</span> + +<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span> <span class="comment">// error, f takes two arguments</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">);</span> <span class="comment">// OK</span> +<span class="special">}</span> +</pre> +<p> + A common variation of this error is to forget that member functions have + an implicit "this" argument: + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">X</span> +<span class="special">{</span> + <span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span><span class="special">);</span> +<span class="special">}</span> + +<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span> <span class="comment">// error, X::f takes two arguments</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span> <span class="comment">// OK</span> +<span class="special">}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.the_function_object_cannot_be_ca"></a><a class="link" href="bind.html#bind.troubleshooting.the_function_object_cannot_be_ca" title="The function object cannot be called with the specified arguments">The + function object cannot be called with the specified arguments</a> +</h3></div></div></div> +<p> + As in normal function calls, the function object that is bound must be compatible + with the argument list. The incompatibility will usually be detected by the + compiler at "call time" and the result is typically an error in + <code class="computeroutput"><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span></code> on a line that looks like: + </p> +<pre class="programlisting"><span class="keyword">return</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">a</span><span class="special">[</span><span class="identifier">a1_</span><span class="special">],</span> <span class="identifier">a</span><span class="special">[</span><span class="identifier">a2_</span><span class="special">]);</span> +</pre> +<p> + An example of this kind of error: + </p> +<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span><span class="special">);</span> + +<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="string">"incompatible"</span><span class="special">);</span> <span class="comment">// OK so far, no call</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="string">"incompatible"</span><span class="special">)();</span> <span class="comment">// error, "incompatible" is not an int</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">);</span> <span class="comment">// OK</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="string">"incompatible"</span><span class="special">);</span> <span class="comment">// error, "incompatible" is not an int</span> +<span class="special">}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.accessing_an_argument_that_does_"></a><a class="link" href="bind.html#bind.troubleshooting.accessing_an_argument_that_does_" title="Accessing an argument that does not exist">Accessing + an argument that does not exist</a> +</h3></div></div></div> +<p> + The placeholder <code class="computeroutput"><span class="identifier">_N</span></code> selects + the argument at position <code class="computeroutput"><span class="identifier">N</span></code> + from the argument list passed at "call time." Naturally, it is + an error to attempt to access beyond the end of this list: + </p> +<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span><span class="special">);</span> + +<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">);</span> <span class="comment">// OK</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)();</span> <span class="comment">// error, there is no argument number 1</span> +<span class="special">}</span> +</pre> +<p> + The error is usually reported in <code class="computeroutput"><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span></code>, at + a line similar to: + </p> +<pre class="programlisting"><span class="keyword">return</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">a</span><span class="special">[</span><span class="identifier">a1_</span><span class="special">]);</span> +</pre> +<p> + When emulating <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind1st</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">a</span><span class="special">)</span></code>, a common mistake of this category is to + type <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">_2</span><span class="special">)</span></code> + instead of the correct <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> + <span class="identifier">a</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)</span></code>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.inappropriate_use_of_bind_f"></a><a class="link" href="bind.html#bind.troubleshooting.inappropriate_use_of_bind_f" title="Inappropriate use of bind(f, ...)">Inappropriate + use of <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code></a> +</h3></div></div></div> +<p> + The <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,</span> + <span class="special">...,</span> <span class="identifier">aN</span><span class="special">)</span></code> <a class="link" href="bind.html#bind.faq.Q_forms" title="What is the difference between bind(f, ...) and bind<R>(f, ...)?">form</a> + causes automatic recognition of the type of <code class="computeroutput"><span class="identifier">f</span></code>. + It will not work with arbitrary function objects; <code class="computeroutput"><span class="identifier">f</span></code> + must be a function or a member function pointer. + </p> +<p> + It is possible to use this form with function objects that define <code class="computeroutput"><span class="identifier">result_type</span></code>, but only on compilers that + support partial specialization and partial ordering. In particular, MSVC + up to version 7.0 does not support this syntax for function objects. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.inappropriate_use_of_bind_r_f"></a><a class="link" href="bind.html#bind.troubleshooting.inappropriate_use_of_bind_r_f" title="Inappropriate use of bind<R>(f, ...)">Inappropriate + use of <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code></a> +</h3></div></div></div> +<p> + The <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,</span> + <span class="special">...,</span> <span class="identifier">aN</span><span class="special">)</span></code> <a class="link" href="bind.html#bind.faq.Q_forms" title="What is the difference between bind(f, ...) and bind<R>(f, ...)?">form</a> + supports arbitrary function objects. + </p> +<p> + It is possible (but not recommended) to use this form with functions or member + function pointers, but only on compilers that support partial ordering. In + particular, MSVC up to version 7.0 does not fully support this syntax for + functions and member function pointers. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.binding_a_nonstandard_function"></a><a class="link" href="bind.html#bind.troubleshooting.binding_a_nonstandard_function" title="Binding a nonstandard function">Binding + a nonstandard function</a> +</h3></div></div></div> +<p> + By default, the <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,</span> + <span class="special">...,</span> <span class="identifier">aN</span><span class="special">)</span></code> <a class="link" href="bind.html#bind.faq.Q_forms" title="What is the difference between bind(f, ...) and bind<R>(f, ...)?">form</a> + recognizes "ordinary" C++ functions and function pointers. <a class="link" href="bind.html#bind.implementation.stdcall" title="__stdcall, __cdecl, __fastcall, and pascal Support">Functions that use a different calling + convention</a>, or variable-argument functions such as <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">printf</span></code>, + do not work. The general <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,</span> + <span class="special">...,</span> <span class="identifier">aN</span><span class="special">)</span></code> <a class="link" href="bind.html#bind.faq.Q_forms" title="What is the difference between bind(f, ...) and bind<R>(f, ...)?">form</a> + works with nonstandard functions. + </p> +<p> + On some platforms, extern "C" functions, like <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">strcmp</span></code>, + are not recognized by the short form of <code class="computeroutput"><span class="identifier">bind</span></code>. + </p> +<p> + See also <a class="link" href="bind.html#bind.implementation.stdcall" title="__stdcall, __cdecl, __fastcall, and pascal Support"><code class="computeroutput"><span class="identifier">__stdcall</span></code> + and <code class="computeroutput"><span class="identifier">pascal</span></code> Support</a>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.binding_an_overloaded_function"></a><a class="link" href="bind.html#bind.troubleshooting.binding_an_overloaded_function" title="Binding an overloaded function">Binding + an overloaded function</a> +</h3></div></div></div> +<p> + An attempt to bind an overloaded function usually results in an error, as + there is no way to tell which overload was meant to be bound. This is a common + problem with member functions with two overloads, const and non-const, as + in this simplified example: + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">X</span> +<span class="special">{</span> + <span class="keyword">int</span><span class="special">&</span> <span class="identifier">get</span><span class="special">();</span> + <span class="keyword">int</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">get</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="special">};</span> + +<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">get</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">);</span> +<span class="special">}</span> +</pre> +<p> + The ambiguity can be resolved manually by casting the (member) function pointer + to the desired type: + </p> +<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="keyword">static_cast</span><span class="special"><</span> <span class="keyword">int</span> <span class="keyword">const</span><span class="special">&</span> <span class="special">(</span><span class="identifier">X</span><span class="special">::*)</span> <span class="special">()</span> <span class="keyword">const</span> <span class="special">>(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">get</span><span class="special">),</span> <span class="identifier">_1</span><span class="special">);</span> +<span class="special">}</span> +</pre> +<p> + Another, arguably more readable, alternative is to introduce a temporary + variable: + </p> +<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> +<span class="special">{</span> + <span class="keyword">int</span> <span class="keyword">const</span><span class="special">&</span> <span class="special">(</span><span class="identifier">X</span><span class="special">::*</span><span class="identifier">get</span><span class="special">)</span> <span class="special">()</span> <span class="keyword">const</span> <span class="special">=</span> <span class="special">&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">get</span><span class="special">;</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">get</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">);</span> +<span class="special">}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.modeling_stl_function_object_con"></a><a class="link" href="bind.html#bind.troubleshooting.modeling_stl_function_object_con" title="Modeling STL function object concepts">Modeling + STL function object concepts</a> +</h3></div></div></div> +<p> + The function objects that are produced by <code class="computeroutput"><span class="identifier">bind</span></code> + do not model the STL <a href="http://www.sgi.com/tech/stl/UnaryFunction.html" target="_top"><span class="emphasis"><em>Unary + Function</em></span></a> or <a href="http://www.sgi.com/tech/stl/BinaryFunction.html" target="_top"><span class="emphasis"><em>Binary + Function</em></span></a> concepts, even when the function objects are + unary or binary operations, because the function object types are missing + public typedefs <code class="computeroutput"><span class="identifier">result_type</span></code> + and <code class="computeroutput"><span class="identifier">argument_type</span></code> or <code class="computeroutput"><span class="identifier">first_argument_type</span></code> and <code class="computeroutput"><span class="identifier">second_argument_type</span></code>. + In cases where these typedefs are desirable, however, the utility function + <code class="computeroutput"><span class="identifier">make_adaptable</span></code> can be used + to adapt unary and binary function objects to these concepts. This allows + unary and binary function objects resulting from <code class="computeroutput"><span class="identifier">bind</span></code> + to be combined with STL templates such as <a href="http://en.cppreference.com/w/cpp/utility/functional/unary_negate" target="_top"><code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">unary_negate</span></code></a> + and <a href="http://en.cppreference.com/w/cpp/utility/functional/binary_negate" target="_top"><code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">binary_negate</span></code></a>. + </p> +<p> + The <code class="computeroutput"><span class="identifier">make_adaptable</span></code> function + is defined in <a href="../../include/boost/bind/make_adaptable.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">/</span><span class="identifier">make_adaptable</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a>, + which must be included explicitly in addition to <a href="../../include/boost/bind.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a>: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">/</span><span class="identifier">make_adaptable</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> <span class="emphasis"><em>unspecified-type</em></span> <span class="identifier">make_adaptable</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> <span class="emphasis"><em>unspecified-unary-functional-type</em></span> <span class="identifier">make_adaptable</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> <span class="emphasis"><em>unspecified-binary-functional-type</em></span> <span class="identifier">make_adaptable</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> <span class="emphasis"><em>unspecified-ternary-functional-type</em></span> <span class="identifier">make_adaptable</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A4</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> <span class="emphasis"><em>unspecified-4-ary-functional-type</em></span> <span class="identifier">make_adaptable</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">);</span> +</pre> +<p> + This example shows how to use <code class="computeroutput"><span class="identifier">make_adaptable</span></code> + to make a predicate for "is not a space": + </p> +<pre class="programlisting"><span class="keyword">typedef</span> <span class="keyword">char</span> <span class="identifier">char_t</span><span class="special">;</span> +<span class="identifier">std</span><span class="special">::</span><span class="identifier">locale</span> <span class="identifier">loc</span><span class="special">(</span><span class="string">""</span><span class="special">);</span> +<span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ctype</span><span class="special"><</span><span class="identifier">char_t</span><span class="special">>&</span> <span class="identifier">ct</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">use_facet</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ctype</span><span class="special"><</span><span class="identifier">char_t</span><span class="special">></span> <span class="special">>(</span><span class="identifier">loc</span><span class="special">);</span> + +<span class="keyword">auto</span> <span class="identifier">isntspace</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">not1</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_adaptable</span><span class="special"><</span><span class="keyword">bool</span><span class="special">,</span> <span class="identifier">char_t</span><span class="special">>(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ctype</span><span class="special"><</span><span class="identifier">char_t</span><span class="special">>::</span><span class="identifier">is</span><span class="special">,</span> <span class="special">&</span><span class="identifier">ct</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ctype_base</span><span class="special">::</span><span class="identifier">space</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)));</span> +</pre> +<p> + In this example, <code class="computeroutput"><span class="identifier">bind</span></code> creates + the "is a space" (unary) predicate. It is then passed to <code class="computeroutput"><span class="identifier">make_adaptable</span></code> so that a function object + modeling the <span class="emphasis"><em>Unary Function</em></span> concept can be created, + serving as the argument to <a href="http://en.cppreference.com/w/cpp/utility/functional/not1" target="_top"><code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">not1</span></code></a>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.const_in_signatures"></a><a class="link" href="bind.html#bind.troubleshooting.const_in_signatures" title="const in signatures"><code class="computeroutput"><span class="keyword">const</span></code> in signatures</a> +</h3></div></div></div> +<p> + Some compilers, including MSVC 6.0 and Borland C++ 5.5.1, have problems with + the top-level <code class="computeroutput"><span class="keyword">const</span></code> in function + signatures: + </p> +<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="keyword">const</span><span class="special">);</span> + +<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span> <span class="comment">// error</span> +<span class="special">}</span> +</pre> +<p> + Workaround: remove the <code class="computeroutput"><span class="keyword">const</span></code> + qualifier from the argument. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.msvc_specific_using_boost_bind"></a><a class="link" href="bind.html#bind.troubleshooting.msvc_specific_using_boost_bind" title="MSVC specific: using boost::bind;">MSVC + specific: <code class="computeroutput"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">;</span></code></a> +</h3></div></div></div> +<p> + On MSVC (up to version 7.0), when <code class="computeroutput"><span class="identifier">boostbind</span></code> + is brought into scope with an using declaration: + </p> +<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">;</span> +</pre> +<p> + the syntax <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> + does not work. Workaround: either use the qualified name, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span></code>, + or use an using directive instead: + </p> +<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">;</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.msvc_specific_class_templates_sh"></a><a class="link" href="bind.html#bind.troubleshooting.msvc_specific_class_templates_sh" title="MSVC specific: class templates shadow function templates">MSVC + specific: class templates shadow function templates</a> +</h3></div></div></div> +<p> + On MSVC (up to version 7.0), a nested class template named <code class="computeroutput"><span class="identifier">bind</span></code> will shadow the function template + <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span></code>, breaking the <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code>syntax. + Unfortunately, some libraries contain nested class templates named <code class="computeroutput"><span class="identifier">bind</span></code> (ironically, such code is often an + MSVC specific workaround.) + </p> +<p> + The workaround is to use the alternative <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">type</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(),</span> <span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> + syntax. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.msvc_specific_in_signatures_trea"></a><a class="link" href="bind.html#bind.troubleshooting.msvc_specific_in_signatures_trea" title="MSVC specific: ... in signatures treated as type">MSVC + specific: <code class="computeroutput"><span class="special">...</span></code> in signatures treated + as type</a> +</h3></div></div></div> +<p> + MSVC (up to version 7.0) treats the ellipsis in a variable argument function + (such as <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">printf</span></code>) as a type. Therefore, it will accept + the (incorrect in the current implementation) form: + </p> +<pre class="programlisting"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">printf</span><span class="special">,</span> <span class="string">"%s\n"</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">);</span> +</pre> +<p> + and will reject the correct version: + </p> +<pre class="programlisting"><span class="identifier">bind</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">printf</span><span class="special">,</span> <span class="string">"%s\n"</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">);</span> +</pre> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bind.interface"></a><a class="link" href="bind.html#bind.interface" title="Interface">Interface</a> +</h2></div></div></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.interface.synopsys"></a><a class="link" href="bind.html#bind.interface.synopsys" title="Synopsis">Synopsis</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> +<span class="special">{</span> +<span class="comment">// no arguments</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> <span class="emphasis"><em>unspecified-1</em></span> <a class="link" href="bind.html#bind_1"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> <span class="emphasis"><em>unspecified-1-1</em></span> <a class="link" href="bind.html#bind_1_1"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="emphasis"><em>unspecified-2</em></span> <a class="link" href="bind.html#bind_2"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">());</span> + +<span class="comment">// one argument</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-3</em></span> <a class="link" href="bind.html#bind_3"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-3-1</em></span> <a class="link" href="bind.html#bind_3_1"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-4</em></span> <a class="link" href="bind.html#bind_4"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(</span><span class="identifier">B1</span><span class="special">),</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-5</em></span> <a class="link" href="bind.html#bind_5"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(),</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-6</em></span> <a class="link" href="bind.html#bind_6"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">()</span> <span class="keyword">const</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-6-1</em></span> <a class="link" href="bind.html#bind_6_1"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">);</span> + +<span class="comment">// two arguments</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-7</em></span> <a class="link" href="bind.html#bind_7"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-7-1</em></span> <a class="link" href="bind.html#bind_7_1"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-8</em></span> <a class="link" href="bind.html#bind_8"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(</span><span class="identifier">B1</span><span class="special">,</span> <span class="identifier">B2</span><span class="special">),</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-9</em></span> <a class="link" href="bind.html#bind_9"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(</span><span class="identifier">B1</span><span class="special">),</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-10</em></span> <a class="link" href="bind.html#bind_10"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(</span><span class="identifier">B1</span><span class="special">)</span> <span class="keyword">const</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">);</span> + +<span class="comment">// implementation defined number of additional overloads for more arguments</span> +<span class="special">}</span> + +<span class="keyword">namespace</span> +<span class="special">{</span> + <span class="emphasis"><em>unspecified-placeholder-type-1</em></span> <span class="identifier">_1</span><span class="special">;</span> + + <span class="emphasis"><em>unspecified-placeholder-type-2</em></span> <span class="identifier">_2</span><span class="special">;</span> + + <span class="emphasis"><em>unspecified-placeholder-type-3</em></span> <span class="identifier">_3</span><span class="special">;</span> + +<span class="comment">// implementation defined number of additional placeholder definitions</span> +<span class="special">}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.interface.common_requirements"></a><a class="link" href="bind.html#bind.interface.common_requirements" title="Common requirements">Common requirements</a> +</h3></div></div></div> +<p> + All <span class="emphasis"><em>unspecified-N</em></span> types returned by <code class="computeroutput"><span class="identifier">bind</span></code> + are <span class="emphasis"><em>CopyConstructible</em></span>. <span class="emphasis"><em>unspecified-N</em></span><code class="computeroutput"><span class="special">::</span><span class="identifier">result_type</span></code> + is defined as the return type of <span class="emphasis"><em>unspecified-N</em></span><code class="computeroutput"><span class="special">::</span><span class="keyword">operator</span><span class="special">()</span></code>. + </p> +<p> + All <span class="emphasis"><em>unspecified-placeholder-N</em></span> types are <span class="emphasis"><em>CopyConstructible</em></span>. + Their copy constructors do not throw exceptions. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.interface.common_definitions"></a><a class="link" href="bind.html#bind.interface.common_definitions" title="Common definitions">Common definitions</a> +</h3></div></div></div> +<p> + The function μ<code class="computeroutput"><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">v1</span><span class="special">,</span> + <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">)</span></code>, where <code class="computeroutput"><span class="identifier">m</span></code> + is a nonnegative integer, is defined as: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">x</span><span class="special">.</span><span class="identifier">get</span><span class="special">()</span></code>, + when <code class="computeroutput"><span class="identifier">x</span></code> is of type <a href="../../../../libs/core/doc/html/core/ref.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">reference_wrapper</span></code></a><code class="computeroutput"><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> for some type <code class="computeroutput"><span class="identifier">T</span></code>; + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">vk</span></code>, when <code class="computeroutput"><span class="identifier">x</span></code> is (a copy of) the placeholder <span class="emphasis"><em>_k</em></span> + for some positive integer <span class="emphasis"><em>k</em></span>; + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">x</span><span class="special">(</span><span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">)</span></code> when <code class="computeroutput"><span class="identifier">x</span></code> + is (a copy of) a function object returned by <code class="computeroutput"><span class="identifier">bind</span></code>; + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">x</span></code> otherwise. + </li> +</ul></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.interface.bind"></a><a class="link" href="bind.html#bind.interface.bind" title="bind"><code class="computeroutput"><span class="identifier">bind</span></code></a> +</h3></div></div></div> +<a name="bind_1"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> <span class="emphasis"><em>unspecified-1</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> A function object λ such that the + expression λ<code class="computeroutput"><span class="special">(</span><span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">)</span></code> + is equivalent to <code class="computeroutput"><span class="identifier">f</span><span class="special">()</span></code>, + implicitly converted to <code class="computeroutput"><span class="identifier">R</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing unless the copy constructor of + <code class="computeroutput"><span class="identifier">F</span></code> throws an exception. + </li> +</ul></div> +<a name="bind_1_1"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> <span class="emphasis"><em>unspecified-1-1</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Effects:</em></span> Equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="keyword">typename</span> + <span class="identifier">F</span><span class="special">::</span><span class="identifier">result_type</span><span class="special">,</span> + <span class="identifier">F</span><span class="special">>(</span><span class="identifier">f</span><span class="special">)</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Notes:</em></span> Implementations are allowed to infer the + return type of <code class="computeroutput"><span class="identifier">f</span></code> via + other means as an extension, without relying on the <code class="computeroutput"><span class="identifier">result_type</span></code> + member. + </li> +</ul></div> +<a name="bind_2"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="emphasis"><em>unspecified-2</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">())</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> A function object λ such that the + expression λ<code class="computeroutput"><span class="special">(</span><span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">)</span></code> + is equivalent to <code class="computeroutput"><span class="identifier">f</span><span class="special">()</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing. + </li> +</ul></div> +<a name="bind_3"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-3</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> A function object λ such that the + expression λ<code class="computeroutput"><span class="special">(</span><span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">)</span></code> + is equivalent to <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span></code>μ<code class="computeroutput"><span class="special">(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">))</span></code>, + implicitly converted to <code class="computeroutput"><span class="identifier">R</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing unless the copy constructors of + <code class="computeroutput"><span class="identifier">F</span></code> or <code class="computeroutput"><span class="identifier">A1</span></code> + throw an exception. + </li> +</ul></div> +<a name="bind_3_1"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-3-1</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Effects:</em></span> Equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="keyword">typename</span> + <span class="identifier">F</span><span class="special">::</span><span class="identifier">result_type</span><span class="special">,</span> + <span class="identifier">F</span><span class="special">,</span> + <span class="identifier">A1</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">)</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Notes:</em></span> Implementations are allowed to infer the + return type of <code class="computeroutput"><span class="identifier">f</span></code> via + other means as an extension, without relying on the <code class="computeroutput"><span class="identifier">result_type</span></code> + member. + </li> +</ul></div> +<a name="bind_4"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-4</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(</span><span class="identifier">B1</span><span class="special">),</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> A function object λ such that the + expression λ<code class="computeroutput"><span class="special">(</span><span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">)</span></code> + is equivalent to <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span></code>μ<code class="computeroutput"><span class="special">(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">))</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing unless the copy constructor of + <code class="computeroutput"><span class="identifier">A1</span></code> throws an exception. + </li> +</ul></div> +<a name="bind_5"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-5</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(),</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <span class="emphasis"><em>Effects:</em></span> Equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span></code><a href="../../../../libs/bind/mem_fn.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span></code></a><code class="computeroutput"><span class="special">(</span><span class="identifier">f</span><span class="special">),</span> <span class="identifier">a1</span><span class="special">)</span></code>. + </li></ul></div> +<a name="bind_6"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-6</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">()</span> <span class="keyword">const</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <span class="emphasis"><em>Effects:</em></span> Equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span></code><a href="../../../../libs/bind/mem_fn.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span></code></a><code class="computeroutput"><span class="special">(</span><span class="identifier">f</span><span class="special">),</span> <span class="identifier">a1</span><span class="special">)</span></code>. + </li></ul></div> +<a name="bind_6_1"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-6-1</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">R</span> <span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <span class="emphasis"><em>Effects:</em></span> Equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span></code><a href="../../../../libs/bind/mem_fn.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span></code></a><code class="computeroutput"><span class="special">(</span><span class="identifier">f</span><span class="special">),</span> <span class="identifier">a1</span><span class="special">)</span></code>. + </li></ul></div> +<a name="bind_7"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-7</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> A function object λ such that the + expression λ<code class="computeroutput"><span class="special">(</span><span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">)</span></code> + is equivalent to <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span></code>μ<code class="computeroutput"><span class="special">(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">),</span> </code>μ<code class="computeroutput"><span class="special">(</span><span class="identifier">a2</span><span class="special">,</span> <span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">))</span></code>, + implicitly converted to <code class="computeroutput"><span class="identifier">R</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing unless the copy constructors of + <code class="computeroutput"><span class="identifier">F</span></code>, <code class="computeroutput"><span class="identifier">A1</span></code> + or <code class="computeroutput"><span class="identifier">A2</span></code> throw an exception. + </li> +</ul></div> +<a name="bind_7_1"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-7-1</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Effects:</em></span> Equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="keyword">typename</span> + <span class="identifier">F</span><span class="special">::</span><span class="identifier">result_type</span><span class="special">,</span> + <span class="identifier">F</span><span class="special">,</span> + <span class="identifier">A1</span><span class="special">,</span> + <span class="identifier">A2</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">)</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Notes:</em></span> Implementations are allowed to infer the + return type of <code class="computeroutput"><span class="identifier">f</span></code> via + other means as an extension, without relying on the <code class="computeroutput"><span class="identifier">result_type</span></code> + member. + </li> +</ul></div> +<a name="bind_8"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-8</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(</span><span class="identifier">B1</span><span class="special">,</span> <span class="identifier">B2</span><span class="special">),</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> A function object λ such that the + expression λ<code class="computeroutput"><span class="special">(</span><span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">)</span></code> + is equivalent to <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span></code>μ<code class="computeroutput"><span class="special">(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">),</span> </code>μ<code class="computeroutput"><span class="special">(</span><span class="identifier">a2</span><span class="special">,</span> <span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">))</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing unless the copy constructors of + <code class="computeroutput"><span class="identifier">A1</span></code> or <code class="computeroutput"><span class="identifier">A2</span></code> + throw an exception. + </li> +</ul></div> +<a name="bind_9"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-9</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(</span><span class="identifier">B1</span><span class="special">),</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <span class="emphasis"><em>Effects:</em></span> Equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span></code><a href="../../../../libs/bind/mem_fn.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span></code></a><code class="computeroutput"><span class="special">(</span><span class="identifier">f</span><span class="special">),</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">)</span></code>. + </li></ul></div> +<a name="bind_10"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-10</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(</span><span class="identifier">B1</span><span class="special">)</span> <span class="keyword">const</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <span class="emphasis"><em>Effects:</em></span> Equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span></code><a href="../../../../libs/bind/mem_fn.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span></code></a><code class="computeroutput"><span class="special">(</span><span class="identifier">f</span><span class="special">),</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">)</span></code>. + </li></ul></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.interface.additional_overloads"></a><a class="link" href="bind.html#bind.interface.additional_overloads" title="Additional overloads">Additional overloads</a> +</h3></div></div></div> +<p> + Implementations are allowed to provide additional <code class="computeroutput"><span class="identifier">bind</span></code> + overloads in order to support more arguments or different function pointer + variations. + </p> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bind.implementation"></a><a class="link" href="bind.html#bind.implementation" title="Implementation">Implementation</a> +</h2></div></div></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.implementation.files"></a><a class="link" href="bind.html#bind.implementation.files" title="Files">Files</a> +</h3></div></div></div> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <a href="../../include/boost/bind.hpp" target="_top">boost/bind.hpp</a> (main + header) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/bind_cc.hpp" target="_top">boost/bind/bind_cc.hpp</a> + (used by <code class="computeroutput"><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span></code>, do not include directly) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/bind_mf_cc.hpp" target="_top">boost/bind/bind_mf_cc.hpp</a> + (used by <code class="computeroutput"><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span></code>, do not include directly) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/bind_template.hpp" target="_top">boost/bind/bind_template.hpp</a> + (used by <code class="computeroutput"><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span></code>, do not include directly) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/arg.hpp" target="_top">boost/bind/arg.hpp</a> + (defines the type of the placeholder arguments) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/placeholders.hpp" target="_top">boost/bind/placeholders.hpp</a> + (defines the <code class="computeroutput"><span class="identifier">_1</span></code>, <code class="computeroutput"><span class="identifier">_2</span></code>, ... <code class="computeroutput"><span class="identifier">_9</span></code> + placeholders) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/apply.hpp" target="_top">boost/bind/apply.hpp</a> + (<code class="computeroutput"><span class="identifier">apply</span></code> helper function + object) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/protect.hpp" target="_top">boost/bind/protect.hpp</a> + (<code class="computeroutput"><span class="identifier">protect</span></code> helper function) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/make_adaptable.hpp" target="_top">boost/bind/make_adaptable.hpp</a> + (<code class="computeroutput"><span class="identifier">make_adaptable</span></code> helper + function) + </li> +<li class="listitem"> + <a href="../../test/bind_test.cpp" target="_top">libs/bind/test/bind_test.cpp</a> + (test) + </li> +<li class="listitem"> + <a href="../../bind_as_compose.cpp" target="_top">libs/bind/bind_as_compose.cpp</a> + (function composition example) + </li> +<li class="listitem"> + <a href="../../bind_visitor.cpp" target="_top">libs/bind/bind_visitor.cpp</a> + (visitor example) + </li> +<li class="listitem"> + <a href="../../test/bind_stdcall_test.cpp" target="_top">libs/bind/test/bind_stdcall_test.cpp</a> + (test with <code class="computeroutput"><span class="identifier">__stdcall</span></code> + functions) + </li> +<li class="listitem"> + <a href="../../test/bind_stdcall_mf_test.cpp" target="_top">libs/bind/test/bind_stdcall_mf_test.cpp</a> + (test with <code class="computeroutput"><span class="identifier">__stdcall</span></code> + member functions) + </li> +<li class="listitem"> + <a href="../../test/bind_fastcall_test.cpp" target="_top">libs/bind/test/bind_fastcall_test.</a> + (test with <code class="computeroutput"><span class="identifier">__fastcall</span></code> + functions) + </li> +<li class="listitem"> + <a href="../../test/bind_fastcall_mf_test.cpp" target="_top">libs/bind/test/bind_fastcall_mf_test.cpp</a> + (test with <code class="computeroutput"><span class="identifier">__fastcall</span></code> + member functions) + </li> +</ul></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.implementation.dependencies"></a><a class="link" href="bind.html#bind.implementation.dependencies" title="Dependencies">Dependencies</a> +</h3></div></div></div> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <a href="../../../../libs/config/config.htm" target="_top">Boost.Config</a> + </li> +<li class="listitem"> + <a href="../../../../libs/core/doc/html/core/ref.html" target="_top">boost/ref.hpp</a> + </li> +<li class="listitem"> + <a href="../../../../libs/bind/mem_fn.html" target="_top">boost/mem_fn.hpp</a> + </li> +<li class="listitem"> + <a href="../../../../boost/type.hpp" target="_top">boost/type.hpp</a> + </li> +</ul></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.implementation.number_of_arguments"></a><a class="link" href="bind.html#bind.implementation.number_of_arguments" title="Number of Arguments">Number of Arguments</a> +</h3></div></div></div> +<p> + This implementation supports function objects with up to nine arguments. + This is an implementation detail, not an inherent limitation of the design. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.implementation.stdcall"></a><a class="link" href="bind.html#bind.implementation.stdcall" title="__stdcall, __cdecl, __fastcall, and pascal Support"><code class="computeroutput"><span class="identifier">__stdcall</span></code>, + <code class="computeroutput"><span class="identifier">__cdecl</span></code>, <code class="computeroutput"><span class="identifier">__fastcall</span></code>, + and <code class="computeroutput"><span class="identifier">pascal</span></code> Support</a> +</h3></div></div></div> +<p> + Some platforms allow several types of (member) functions that differ by their + calling convention (the rules by which the function is invoked: how are arguments + passed, how is the return value handled, and who cleans up the stack - if + any.) + </p> +<p> + For example, Windows API functions and COM interface member functions use + a calling convention known as <code class="computeroutput"><span class="identifier">__stdcall</span></code>. + Borland VCL components use <code class="computeroutput"><span class="identifier">__fastcall</span></code>. + Mac toolbox functions use a <code class="computeroutput"><span class="identifier">pascal</span></code> + calling convention. + </p> +<p> + To use <code class="computeroutput"><span class="identifier">bind</span></code> with <code class="computeroutput"><span class="identifier">__stdcall</span></code> functions, <code class="computeroutput"><span class="preprocessor">#define</span></code> + the macro <code class="computeroutput"><span class="identifier">BOOST_BIND_ENABLE_STDCALL</span></code> + before including <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>. + </p> +<p> + To use <code class="computeroutput"><span class="identifier">bind</span></code> with <code class="computeroutput"><span class="identifier">__stdcall</span></code> member functions, <code class="computeroutput"><span class="preprocessor">#define</span></code> the macro <code class="computeroutput"><span class="identifier">BOOST_MEM_FN_ENABLE_STDCALL</span></code> + before including <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>. + </p> +<p> + To use <code class="computeroutput"><span class="identifier">bind</span></code> with <code class="computeroutput"><span class="identifier">__fastcall</span></code> functions, <code class="computeroutput"><span class="preprocessor">#define</span></code> + the macro <code class="computeroutput"><span class="identifier">BOOST_BIND_ENABLE_FASTCALL</span></code> + before including <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>. + </p> +<p> + To use <code class="computeroutput"><span class="identifier">bind</span></code> with <code class="computeroutput"><span class="identifier">__fastcall</span></code> member functions, <code class="computeroutput"><span class="preprocessor">#define</span></code> the macro <code class="computeroutput"><span class="identifier">BOOST_MEM_FN_ENABLE_FASTCALL</span></code> + before including <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>. + </p> +<p> + To use <code class="computeroutput"><span class="identifier">bind</span></code> with <code class="computeroutput"><span class="identifier">pascal</span></code> functions, <code class="computeroutput"><span class="preprocessor">#define</span></code> + the macro <code class="computeroutput"><span class="identifier">BOOST_BIND_ENABLE_PASCAL</span></code> + before including <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>. + </p> +<p> + To use <code class="computeroutput"><span class="identifier">bind</span></code> with <code class="computeroutput"><span class="identifier">__cdecl</span></code> member functions, <code class="computeroutput"><span class="preprocessor">#define</span></code> the macro <code class="computeroutput"><span class="identifier">BOOST_MEM_FN_ENABLE_CDECL</span></code> + before including <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>. + </p> +<p> + <span class="bold"><strong>It is best to define these macros in the project options, + via <code class="computeroutput"><span class="special">-</span><span class="identifier">D</span></code> + on the command line, or as the first line in the translation unit (.cpp file) + where <code class="computeroutput"><span class="identifier">bind</span></code> is used.</strong></span> + Not following this rule can lead to obscure errors when a header includes + <code class="computeroutput"><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span></code> before the macro has been defined. + </p> +<p> + <span class="emphasis"><em>[Note:</em></span> this is a non-portable extension. It is not part + of the interface.<span class="emphasis"><em>]</em></span> + </p> +<p> + <span class="emphasis"><em>[Note:</em></span> Some compilers provide only minimal support for + the <code class="computeroutput"><span class="identifier">__stdcall</span></code> keyword.<span class="emphasis"><em>]</em></span> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.implementation.visit_each_support"></a><a class="link" href="bind.html#bind.implementation.visit_each_support" title="visit_each support"><code class="computeroutput"><span class="identifier">visit_each</span></code> support</a> +</h3></div></div></div> +<p> + Function objects returned by <code class="computeroutput"><span class="identifier">bind</span></code> + support the experimental and undocumented, as of yet, <code class="computeroutput"><span class="identifier">visit_each</span></code> + enumeration interface. + </p> +<p> + See <a href="../../bind_visitor.cpp" target="_top">bind_visitor.cpp</a> for an example. + </p> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bind.acknowledgements"></a><a class="link" href="bind.html#bind.acknowledgements" title="Acknowledgements">Acknowledgements</a> +</h2></div></div></div> +<p> + Earlier efforts that have influenced the library design: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + The <a href="http://staff.cs.utu.fi/BL/" target="_top">Binder Library</a> by Jaakko + Järvi; + </li> +<li class="listitem"> + The <a href="../../../../libs/lambda/index.html" target="_top">Lambda Library</a> (now + part of Boost) by Jaakko Järvi and Gary Powell (the successor to the + Binder Library); + </li> +<li class="listitem"> + <a href="http://more.sourceforge.net/" target="_top">Extensions to the STL</a> + by Petter Urkedal. + </li> +</ul></div> +<p> + Doug Gregor suggested that a visitor mechanism would allow <code class="computeroutput"><span class="identifier">bind</span></code> + to interoperate with a signal/slot library. + </p> +<p> + John Maddock fixed a MSVC-specific conflict between <code class="computeroutput"><span class="identifier">bind</span></code> + and the <a href="../../../../libs/type_traits/index.html" target="_top">type traits library</a>. + </p> +<p> + Numerous improvements were suggested during the formal review period by Ross + Smith, Richard Crossley, Jens Maurer, Ed Brey, and others. Review manager was + Darin Adler. + </p> +<p> + The precise semantics of <code class="computeroutput"><span class="identifier">bind</span></code> + were refined in discussions with Jaakko Järvi. + </p> +<p> + Dave Abrahams fixed a MSVC-specific conflict between <code class="computeroutput"><span class="identifier">bind</span></code> + and the <a href="../../../../libs/utility/iterator_adaptors.htm" target="_top">iterator adaptors + library</a>. + </p> +<p> + Dave Abrahams modified <code class="computeroutput"><span class="identifier">bind</span></code> + and <code class="computeroutput"><span class="identifier">mem_fn</span></code> to support <code class="computeroutput"><span class="keyword">void</span></code> returns on deficient compilers. + </p> +<p> + Mac Murrett contributed the "pascal" support enabled by <code class="computeroutput"><span class="identifier">BOOST_BIND_ENABLE_PASCAL</span></code>. + </p> +<p> + The alternative <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">type</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(),</span> <span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> + syntax was inspired by a discussion with Dave Abrahams and Joel de Guzman. + </p> +<p> + This documentation was ported to Quickbook by Agustín Bergé. + </p> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"><p><small>Last revised: April 07, 2015 at 22:47:13 GMT</small></p></td> +<td align="right"><div class="copyright-footer"></div></td> +</tr></table> +<hr> +<div class="spirit-nav"></div> +</body> +</html> diff --git a/libs/bind/doc/html/mem_fn.html b/libs/bind/doc/html/mem_fn.html new file mode 100644 index 000000000..0f61e7a14 --- /dev/null +++ b/libs/bind/doc/html/mem_fn.html @@ -0,0 +1,552 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Chapter 1. Boost.Member Function</title> +<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="mem_fn.html" title="Chapter 1. Boost.Member Function"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> +<td align="center"><a href="../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"></div> +<div class="chapter"> +<div class="titlepage"><div> +<div><h2 class="title"> +<a name="mem_fn"></a>Chapter 1. Boost.Member Function</h2></div> +<div><p class="copyright">Copyright © 2001, 2002 Peter Dimov and Multi Media Ltd.</p></div> +<div><p class="copyright">Copyright © 2003-2005 Peter Dimov</p></div> +<div><div class="legalnotice"> +<a name="mem_fn.legal"></a><p> + Distributed under the <a href="http://boost.org/LICENSE_1_0.txt" target="_top">Boost + Software License, Version 1.0</a>. + </p> +</div></div> +</div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="mem_fn.html#mem_fn.purpose">Purpose</a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.faq">Frequently Asked Questions</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="mem_fn.html#mem_fn.faq.can_mem_fn_be_used_instead_of_th">Can <code class="computeroutput"><span class="identifier">mem_fn</span></code> be used instead of the standard <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">mem_fun</span><span class="special">[</span><span class="identifier">_ref</span><span class="special">]</span></code> + adaptors?</a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.faq.should_i_replace_every_occurence">Should I + replace every occurence of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">mem_fun</span><span class="special">[</span><span class="identifier">_ref</span><span class="special">]</span></code> + with <code class="computeroutput"><span class="identifier">mem_fn</span></code> in my existing + code?</a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.faq.does_mem_fn_work_with_com_method">Does <code class="computeroutput"><span class="identifier">mem_fn</span></code> work with COM methods?</a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.faq.why_isn_t_boost_mem_fn_enable_st">Why isn't + <code class="computeroutput"><span class="identifier">BOOST_MEM_FN_ENABLE_STDCALL</span></code> + defined automatically?</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="mem_fn.html#mem_fn.interface">Interface</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="mem_fn.html#mem_fn.interface.synopsys">Synopsis</a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.interface.common_requirements">Common requirements</a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.interface.get_pointer"><code class="computeroutput"><span class="identifier">get_pointer</span></code></a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.interface.mem_fn"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a></span></dt> +</dl></dd> +<dt><span class="section"><a href="mem_fn.html#mem_fn.implementation">Implementation</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="mem_fn.html#mem_fn.implementation.files">Files</a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.implementation.dependencies">Dependencies</a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.implementation.number_of_arguments">Number of + Arguments</a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.implementation.stdcall"><code class="computeroutput"><span class="identifier">__stdcall</span></code>, + <code class="computeroutput"><span class="identifier">__cdecl</span></code>, and <code class="computeroutput"><span class="identifier">__fastcall</span></code> Support</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="mem_fn.html#mem_fn.acknowledgements">Acknowledgements</a></span></dt> +</dl> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="mem_fn.purpose"></a><a class="link" href="mem_fn.html#mem_fn.purpose" title="Purpose">Purpose</a> +</h2></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span></code> is a generalization of the standard + functions <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">mem_fun</span></code> and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">mem_fun_ref</span></code>. + It supports member function pointers with more than one argument, and the returned + function object can take a pointer, a reference, or a smart pointer to an object + instance as its first argument. <code class="computeroutput"><span class="identifier">mem_fn</span></code> + also supports pointers to data members by treating them as functions taking + no arguments and returning a (const) reference to the member. + </p> +<p> + The purpose of <code class="computeroutput"><span class="identifier">mem_fn</span></code> is twofold. + First, it allows users to invoke a member function on a container with the + familiar + </p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">v</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span><span class="special">(&</span><span class="identifier">Shape</span><span class="special">::</span><span class="identifier">draw</span><span class="special">));</span> +</pre> +<p> + syntax, even when the container stores smart pointers. + </p> +<p> + Second, it can be used as a building block by library developers that want + to treat a pointer to member function as a function object. A library might + define an enhanced <code class="computeroutput"><span class="identifier">for_each</span></code> + algorithm with an overload of the form: + </p> +<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">It</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">void</span> <span class="identifier">for_each</span><span class="special">(</span><span class="identifier">It</span> <span class="identifier">first</span><span class="special">,</span> <span class="identifier">It</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">())</span> +<span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span><span class="special">(</span><span class="identifier">pmf</span><span class="special">));</span> +<span class="special">}</span> +</pre> +<p> + that will allow the convenient syntax: + </p> +<pre class="programlisting"><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">v</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="special">&</span><span class="identifier">Shape</span><span class="special">::</span><span class="identifier">draw</span><span class="special">);</span> +</pre> +<p> + When documenting the feature, the library author will simply state: + </p> +<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">It</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">void</span> <span class="identifier">for_each</span><span class="special">(</span><span class="identifier">It</span> <span class="identifier">first</span><span class="special">,</span> <span class="identifier">It</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">());</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <span class="emphasis"><em>Effects:</em></span> Equivalent to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span><span class="special">(</span><span class="identifier">pmf</span><span class="special">))</span></code>. + </li></ul></div> +<p> + where <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span></code> can be a link to this page. See the + <a href="../../../../libs/bind/bind.html" target="_top">documentation of <code class="computeroutput"><span class="identifier">bind</span></code></a> + for an example. + </p> +<p> + <code class="computeroutput"><span class="identifier">mem_fn</span></code> takes one argument, + a pointer to a member, and returns a function object suitable for use with + standard or user-defined algorithms: + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">X</span> +<span class="special">{</span> + <span class="keyword">void</span> <span class="identifier">f</span><span class="special">();</span> +<span class="special">};</span> + +<span class="keyword">void</span> <span class="identifier">g</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="identifier">X</span><span class="special">></span> <span class="special">&</span> <span class="identifier">v</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">v</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">));</span> +<span class="special">};</span> + +<span class="keyword">void</span> <span class="identifier">h</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="identifier">X</span> <span class="special">*></span> <span class="keyword">const</span> <span class="special">&</span> <span class="identifier">v</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">v</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">));</span> +<span class="special">};</span> + +<span class="keyword">void</span> <span class="identifier">k</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">X</span><span class="special">></span> <span class="special">></span> <span class="keyword">const</span> <span class="special">&</span> <span class="identifier">v</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">v</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">));</span> +<span class="special">};</span> +</pre> +<p> + The returned function object takes the same arguments as the input member function + plus a "flexible" first argument that represents the object instance. + </p> +<p> + When the function object is invoked with a first argument <code class="computeroutput"><span class="identifier">x</span></code> + that is neither a pointer nor a reference to the appropriate class (<code class="computeroutput"><span class="identifier">X</span></code> in the example above), it uses <code class="computeroutput"><span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code> to obtain + a pointer from <code class="computeroutput"><span class="identifier">x</span></code>. Library authors + can "register" their smart pointer classes by supplying an appropriate + <code class="computeroutput"><span class="identifier">get_pointer</span></code> overload, allowing + <code class="computeroutput"><span class="identifier">mem_fn</span></code> to recognize and support + them. + </p> +<p> + <span class="emphasis"><em>[Note:</em></span> <code class="computeroutput"><span class="identifier">get_pointer</span></code> + is not restricted to return a pointer. Any object that can be used in a member + function call expression <code class="computeroutput"><span class="special">(</span><span class="identifier">x</span><span class="special">->*</span><span class="identifier">pmf</span><span class="special">)(...)</span></code> will work.<span class="emphasis"><em>]</em></span> + </p> +<p> + <span class="emphasis"><em>[Note:</em></span> the library uses an unqualified call to <code class="computeroutput"><span class="identifier">get_pointer</span></code>. Therefore, it will find, through + argument-dependent lookup, <code class="computeroutput"><span class="identifier">get_pointer</span></code> + overloads that are defined in the same namespace as the corresponding smart + pointer class, in addition to any <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">get_pointer</span></code> + overloads.<span class="emphasis"><em>]</em></span> + </p> +<p> + All function objects returned by <code class="computeroutput"><span class="identifier">mem_fn</span></code> + expose a <code class="computeroutput"><span class="identifier">result_type</span></code> typedef + that represents the return type of the member function. For data members, + <code class="computeroutput"><span class="identifier">result_type</span></code> is defined as the + type of the member. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="mem_fn.faq"></a><a class="link" href="mem_fn.html#mem_fn.faq" title="Frequently Asked Questions">Frequently Asked Questions</a> +</h2></div></div></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.faq.can_mem_fn_be_used_instead_of_th"></a><a class="link" href="mem_fn.html#mem_fn.faq.can_mem_fn_be_used_instead_of_th" title="Can mem_fn be used instead of the standard std::mem_fun[_ref] adaptors?">Can <code class="computeroutput"><span class="identifier">mem_fn</span></code> be used instead of the standard <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">mem_fun</span><span class="special">[</span><span class="identifier">_ref</span><span class="special">]</span></code> + adaptors?</a> +</h3></div></div></div> +<p> + Yes. For simple uses, <code class="computeroutput"><span class="identifier">mem_fn</span></code> + provides additional functionality that the standard adaptors do not. Complicated + expressions that use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind1st</span></code>, + <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind2nd</span></code> or <a href="http://www.boost.org/doc/libs/1_31_0/libs/compose/index.htm" target="_top">Boost.Compose</a> + along with the standard adaptors can be rewritten using <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span></code> + that automatically takes advantage of <code class="computeroutput"><span class="identifier">mem_fn</span></code>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.faq.should_i_replace_every_occurence"></a><a class="link" href="mem_fn.html#mem_fn.faq.should_i_replace_every_occurence" title="Should I replace every occurence of std::mem_fun[_ref] with mem_fn in my existing code?">Should I + replace every occurence of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">mem_fun</span><span class="special">[</span><span class="identifier">_ref</span><span class="special">]</span></code> + with <code class="computeroutput"><span class="identifier">mem_fn</span></code> in my existing + code?</a> +</h3></div></div></div> +<p> + No, unless you have good reasons to do so. <code class="computeroutput"><span class="identifier">mem_fn</span></code> + is not 100% compatible with the standard adaptors, although it comes pretty + close. In particular, <code class="computeroutput"><span class="identifier">mem_fn</span></code> + does not return objects of type <code class="computeroutput"><span class="identifier">std</span><span class="special">::[</span><span class="identifier">const_</span><span class="special">]</span><span class="identifier">mem_fun</span><span class="special">[</span><span class="number">1</span><span class="special">][</span><span class="identifier">_ref</span><span class="special">]</span><span class="identifier">_t</span></code>, + as the standard adaptors do, and it is not possible to fully describe the + type of the first argument using the standard <code class="computeroutput"><span class="identifier">argument_type</span></code> + and <code class="computeroutput"><span class="identifier">first_argument_type</span></code> nested + typedefs. Libraries that need adaptable function objects in order to function + might not like <code class="computeroutput"><span class="identifier">mem_fn</span></code>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.faq.does_mem_fn_work_with_com_method"></a><a class="link" href="mem_fn.html#mem_fn.faq.does_mem_fn_work_with_com_method" title="Does mem_fn work with COM methods?">Does <code class="computeroutput"><span class="identifier">mem_fn</span></code> work with COM methods?</a> +</h3></div></div></div> +<p> + Yes, if you <a class="link" href="mem_fn.html#mem_fn.implementation.stdcall" title="__stdcall, __cdecl, and __fastcall Support">`#define BOOST_MEM_FN_ENABLE_STDCALL</a>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.faq.why_isn_t_boost_mem_fn_enable_st"></a><a class="link" href="mem_fn.html#mem_fn.faq.why_isn_t_boost_mem_fn_enable_st" title="Why isn't BOOST_MEM_FN_ENABLE_STDCALL defined automatically?">Why isn't + <code class="computeroutput"><span class="identifier">BOOST_MEM_FN_ENABLE_STDCALL</span></code> + defined automatically?</a> +</h3></div></div></div> +<p> + Non-portable extensions, in general, should default to off to prevent vendor + lock-in. Had <code class="computeroutput"><span class="identifier">BOOST_MEM_FN_ENABLE_STDCALL</span></code> + been defined automatically, you could have accidentally taken advantage of + it without realizing that your code is, perhaps, no longer portable. In addition, + it is possible for the default calling convention to be <code class="computeroutput"><span class="identifier">__stdcall</span></code>, + in which case enabling <code class="computeroutput"><span class="identifier">__stdcall</span></code> + support will result in duplicate definitions. + </p> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="mem_fn.interface"></a><a class="link" href="mem_fn.html#mem_fn.interface" title="Interface">Interface</a> +</h2></div></div></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.interface.synopsys"></a><a class="link" href="mem_fn.html#mem_fn.interface.synopsys" title="Synopsis">Synopsis</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> +<span class="special">{</span> + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="identifier">T</span> <span class="special">*</span> <a class="link" href="mem_fn.html#get_pointer_1"><code class="computeroutput"><span class="identifier">get_pointer</span></code></a><span class="special">(</span><span class="identifier">T</span> <span class="special">*</span> <span class="identifier">p</span><span class="special">);</span> + + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="emphasis"><em>unspecified-1</em></span> <a class="link" href="mem_fn.html#mem_fn_1"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">());</span> + + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="emphasis"><em>unspecified-2</em></span> <a class="link" href="mem_fn.html#mem_fn_2"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">()</span> <span class="keyword">const</span><span class="special">);</span> + + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="emphasis"><em>unspecified-2-1</em></span> <a class="link" href="mem_fn.html#mem_fn_2_1"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="identifier">T</span><span class="special">::*</span><span class="identifier">pm</span><span class="special">);</span> + + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-3</em></span> <a class="link" href="mem_fn.html#mem_fn_3"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">(</span><span class="identifier">A1</span><span class="special">));</span> + + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-4</em></span> <a class="link" href="mem_fn.html#mem_fn_4"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">(</span><span class="identifier">A1</span><span class="special">)</span> <span class="keyword">const</span><span class="special">);</span> + + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-5</em></span> <a class="link" href="mem_fn.html#mem_fn_5"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">(</span><span class="identifier">A1</span><span class="special">,</span> <span class="identifier">A2</span><span class="special">));</span> + + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-6</em></span> <a class="link" href="mem_fn.html#mem_fn_6"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">(</span><span class="identifier">A1</span><span class="special">,</span> <span class="identifier">A2</span><span class="special">)</span> <span class="keyword">const</span><span class="special">);</span> + + <span class="comment">// implementation defined number of additional overloads for more arguments</span> +<span class="special">}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.interface.common_requirements"></a><a class="link" href="mem_fn.html#mem_fn.interface.common_requirements" title="Common requirements">Common requirements</a> +</h3></div></div></div> +<p> + All <span class="emphasis"><em>unspecified-N</em></span> types mentioned in the Synopsis are + <span class="emphasis"><em>CopyConstructible</em></span> and <span class="emphasis"><em>Assignable</em></span>. + Their copy constructors and assignment operators do not throw exceptions. + <span class="emphasis"><em>unspecified-N</em></span><code class="computeroutput"><span class="special">::</span><span class="identifier">result_type</span></code> is defined as the return type + of the member function pointer passed as an argument to <code class="computeroutput"><span class="identifier">mem_fn</span></code> + (<code class="computeroutput"><span class="identifier">R</span></code> in the Synopsis.) <span class="emphasis"><em>unspecified-2-1</em></span><code class="computeroutput"><span class="special">::</span><span class="identifier">result_type</span></code> + is defined as <code class="computeroutput"><span class="identifier">R</span></code>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.interface.get_pointer"></a><a class="link" href="mem_fn.html#mem_fn.interface.get_pointer" title="get_pointer"><code class="computeroutput"><span class="identifier">get_pointer</span></code></a> +</h3></div></div></div> +<a name="get_pointer_1"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="identifier">T</span> <span class="special">*</span> <span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">T</span> <span class="special">*</span> <span class="identifier">p</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> <code class="computeroutput"><span class="identifier">p</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing. + </li> +</ul></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.interface.mem_fn"></a><a class="link" href="mem_fn.html#mem_fn.interface.mem_fn" title="mem_fn"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a> +</h3></div></div></div> +<a name="mem_fn_1"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="emphasis"><em>unspecified-1</em></span> <span class="identifier">mem_fn</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">())</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> a function object ϝ such that the + expression ϝ<code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">)</span></code> is equivalent to <code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">.*</span><span class="identifier">pmf</span><span class="special">)()</span></code> + when <code class="computeroutput"><span class="identifier">t</span></code> is an l-value + of type <code class="computeroutput"><span class="identifier">T</span></code> or derived, + <code class="computeroutput"><span class="special">(</span><span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">t</span><span class="special">)->*</span><span class="identifier">pmf</span><span class="special">)()</span></code> otherwise. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing. + </li> +</ul></div> +<a name="mem_fn_2"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="emphasis"><em>unspecified-2</em></span> <span class="identifier">mem_fn</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">()</span> <span class="keyword">const</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> a function object ϝ such that the + expression ϝ<code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">)</span></code> is equivalent to <code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">.*</span><span class="identifier">pmf</span><span class="special">)()</span></code> + when <code class="computeroutput"><span class="identifier">t</span></code> is of type <code class="computeroutput"><span class="identifier">T</span></code> <span class="emphasis"><em>[</em></span><code class="computeroutput"><span class="keyword">const</span></code><span class="emphasis"><em>]</em></span> or derived, + <code class="computeroutput"><span class="special">(</span><span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">t</span><span class="special">)->*</span><span class="identifier">pmf</span><span class="special">)()</span></code> otherwise. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing. + </li> +</ul></div> +<a name="mem_fn_2_1"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="emphasis"><em>unspecified-2-1</em></span> <span class="identifier">mem_fn</span><span class="special">(</span><span class="identifier">R</span> <span class="identifier">T</span><span class="special">::*</span><span class="identifier">pm</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> a function object ϝ such that the + expression ϝ<code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">)</span></code> is equivalent to <code class="computeroutput"><span class="identifier">t</span><span class="special">.*</span><span class="identifier">pm</span></code> + when <code class="computeroutput"><span class="identifier">t</span></code> is of type <code class="computeroutput"><span class="identifier">T</span></code> <span class="emphasis"><em>[</em></span><code class="computeroutput"><span class="keyword">const</span></code><span class="emphasis"><em>]</em></span> or derived, + <code class="computeroutput"><span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">t</span><span class="special">)->*</span><span class="identifier">pm</span></code> otherwise. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing. + </li> +</ul></div> +<a name="mem_fn_3"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-3</em></span> <span class="identifier">mem_fn</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">(</span><span class="identifier">A1</span><span class="special">))</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> a function object ϝ such that the + expression ϝ<code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">)</span></code> is equivalent to <code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">.*</span><span class="identifier">pmf</span><span class="special">)(</span><span class="identifier">a1</span><span class="special">)</span></code> + when <code class="computeroutput"><span class="identifier">t</span></code> is an l-value + of type <code class="computeroutput"><span class="identifier">T</span></code> or derived, + <code class="computeroutput"><span class="special">(</span><span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">t</span><span class="special">)->*</span><span class="identifier">pmf</span><span class="special">)(</span><span class="identifier">a1</span><span class="special">)</span></code> otherwise. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing. + </li> +</ul></div> +<a name="mem_fn_4"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-4</em></span> <span class="identifier">mem_fn</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">(</span><span class="identifier">A1</span><span class="special">)</span> <span class="keyword">const</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> a function object ϝ such that the + expression ϝ<code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">)</span></code> is equivalent to <code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">.*</span><span class="identifier">pmf</span><span class="special">)(</span><span class="identifier">a1</span><span class="special">)</span></code> + when <code class="computeroutput"><span class="identifier">t</span></code> is of type <code class="computeroutput"><span class="identifier">T</span></code> <span class="emphasis"><em>[</em></span><code class="computeroutput"><span class="keyword">const</span></code><span class="emphasis"><em>]</em></span> or derived, + <code class="computeroutput"><span class="special">(</span><span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">t</span><span class="special">)->*</span><span class="identifier">pmf</span><span class="special">)(</span><span class="identifier">a1</span><span class="special">)</span></code> otherwise. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing. + </li> +</ul></div> +<a name="mem_fn_5"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-5</em></span> <span class="identifier">mem_fn</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">(</span><span class="identifier">A1</span><span class="special">,</span> <span class="identifier">A2</span><span class="special">))</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> a function object ϝ such that the + expression ϝ<code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">)</span></code> is equivalent to <code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">.*</span><span class="identifier">pmf</span><span class="special">)(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">)</span></code> + when <code class="computeroutput"><span class="identifier">t</span></code> is an l-value + of type <code class="computeroutput"><span class="identifier">T</span></code> or derived, + <code class="computeroutput"><span class="special">(</span><span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">t</span><span class="special">)->*</span><span class="identifier">pmf</span><span class="special">)(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">)</span></code> otherwise. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing. + </li> +</ul></div> +<a name="mem_fn_6"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-6</em></span> <span class="identifier">mem_fn</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">(</span><span class="identifier">A1</span><span class="special">,</span> <span class="identifier">A2</span><span class="special">)</span> <span class="keyword">const</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> a function object ϝ such that the + expression ϝ<code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">)</span></code> is equivalent to <code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">.*</span><span class="identifier">pmf</span><span class="special">)(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">)</span></code> + when <code class="computeroutput"><span class="identifier">t</span></code> is of type <code class="computeroutput"><span class="identifier">T</span></code> <span class="emphasis"><em>[</em></span><code class="computeroutput"><span class="keyword">const</span></code><span class="emphasis"><em>]</em></span> or derived, + <code class="computeroutput"><span class="special">(</span><span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">t</span><span class="special">)->*</span><span class="identifier">pmf</span><span class="special">)(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">)</span></code> otherwise. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing. + </li> +</ul></div> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="mem_fn.implementation"></a><a class="link" href="mem_fn.html#mem_fn.implementation" title="Implementation">Implementation</a> +</h2></div></div></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.implementation.files"></a><a class="link" href="mem_fn.html#mem_fn.implementation.files" title="Files">Files</a> +</h3></div></div></div> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <a href="../../include/boost/mem_fn.hpp" target="_top">boost/mem_fn.hpp</a> + (main header) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/mem_fn_cc.hpp" target="_top">boost/bind/mem_fn_cc.hpp</a> + (used by <code class="computeroutput"><span class="identifier">mem_fn</span><span class="special">.</span><span class="identifier">hpp</span></code>, do not include directly) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/mem_fn_vw.hpp" target="_top">boost/bind/mem_fn_vw.hpp</a> + (used by <code class="computeroutput"><span class="identifier">mem_fn</span><span class="special">.</span><span class="identifier">hpp</span></code>, do not include directly) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/mem_fn_template.hpp" target="_top">boost/bind/mem_fn_template.hpp</a> + (used by <code class="computeroutput"><span class="identifier">mem_fn</span><span class="special">.</span><span class="identifier">hpp</span></code>, do not include directly) + </li> +<li class="listitem"> + <a href="../../test/mem_fn_test.cpp" target="_top">libs/bind/test/mem_fn_test.cpp</a> + (test) + </li> +<li class="listitem"> + <a href="../../test/mem_fn_derived_test.cpp" target="_top">libs/bind/test/mem_fn_derived_test.cpp</a> + (test with derived objects) + </li> +<li class="listitem"> + <a href="../../test/mem_fn_fastcall_test.cpp" target="_top">libs/bind/test/mem_fn_fastcall_test.cpp</a> + (test for <code class="computeroutput"><span class="identifier">__fastcall</span></code>) + </li> +<li class="listitem"> + <a href="../../test/mem_fn_stdcall_test.cpp" target="_top">libs/bind/test/mem_fn_stdcall_test.cpp</a> + (test for <code class="computeroutput"><span class="identifier">__stdcall</span></code>) + </li> +<li class="listitem"> + <a href="../../test/mem_fn_void_test.cpp" target="_top">libs/bind/test/mem_fn_void_test.cpp</a> + (test for <code class="computeroutput"><span class="keyword">void</span></code> returns) + </li> +</ul></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.implementation.dependencies"></a><a class="link" href="mem_fn.html#mem_fn.implementation.dependencies" title="Dependencies">Dependencies</a> +</h3></div></div></div> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <a href="../../../../libs/config/config.htm" target="_top">Boost.Config</a> + </li></ul></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.implementation.number_of_arguments"></a><a class="link" href="mem_fn.html#mem_fn.implementation.number_of_arguments" title="Number of Arguments">Number of + Arguments</a> +</h3></div></div></div> +<p> + This implementation supports member functions with up to eight arguments. + This is not an inherent limitation of the design, but an implementation detail. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.implementation.stdcall"></a><a class="link" href="mem_fn.html#mem_fn.implementation.stdcall" title="__stdcall, __cdecl, and __fastcall Support"><code class="computeroutput"><span class="identifier">__stdcall</span></code>, + <code class="computeroutput"><span class="identifier">__cdecl</span></code>, and <code class="computeroutput"><span class="identifier">__fastcall</span></code> Support</a> +</h3></div></div></div> +<p> + Some platforms allow several types of member functions that differ by their + calling convention (the rules by which the function is invoked: how are arguments + passed, how is the return value handled, and who cleans up the stack - if + any.) + </p> +<p> + For example, Windows API functions and COM interface member functions use + a calling convention known as <code class="computeroutput"><span class="identifier">__stdcall</span></code>. + Borland VCL components use <code class="computeroutput"><span class="identifier">__fastcall</span></code>. + UDK, the component model of OpenOffice.org, uses <code class="computeroutput"><span class="identifier">__cdecl</span></code>. + </p> +<p> + To use <code class="computeroutput"><span class="identifier">mem_fn</span></code> with <code class="computeroutput"><span class="identifier">__stdcall</span></code> member functions, <code class="computeroutput"><span class="preprocessor">#define</span></code> the macro <code class="computeroutput"><span class="identifier">BOOST_MEM_FN_ENABLE_STDCALL</span></code> + before including <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">mem_fn</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>. + </p> +<p> + To use <code class="computeroutput"><span class="identifier">mem_fn</span></code> with <code class="computeroutput"><span class="identifier">__fastcall</span></code> member functions, <code class="computeroutput"><span class="preprocessor">#define</span></code> the macro <code class="computeroutput"><span class="identifier">BOOST_MEM_FN_ENABLE_FASTCALL</span></code> + before including <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">mem_fn</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>. + </p> +<p> + To use <code class="computeroutput"><span class="identifier">mem_fn</span></code> with <code class="computeroutput"><span class="identifier">__cdecl</span></code> member functions, <code class="computeroutput"><span class="preprocessor">#define</span></code> the macro <code class="computeroutput"><span class="identifier">BOOST_MEM_FN_ENABLE_CDECL</span></code> + before including <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">mem_fn</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>. + </p> +<p> + <span class="bold"><strong>It is best to define these macros in the project options, + via <code class="computeroutput"><span class="special">-</span><span class="identifier">D</span></code> + on the command line, or as the first line in the translation unit (.cpp file) + where <code class="computeroutput"><span class="identifier">mem_fn</span></code> is used.</strong></span> + Not following this rule can lead to obscure errors when a header includes + <code class="computeroutput"><span class="identifier">mem_fn</span><span class="special">.</span><span class="identifier">hpp</span></code> before the macro has been defined. + </p> +<p> + <span class="emphasis"><em>[Note:</em></span> this is a non-portable extension. It is not part + of the interface.<span class="emphasis"><em>]</em></span> + </p> +<p> + <span class="emphasis"><em>[Note:</em></span> Some compilers provide only minimal support for + the <code class="computeroutput"><span class="identifier">__stdcall</span></code> keyword.<span class="emphasis"><em>]</em></span> + </p> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="mem_fn.acknowledgements"></a><a class="link" href="mem_fn.html#mem_fn.acknowledgements" title="Acknowledgements">Acknowledgements</a> +</h2></div></div></div> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + Rene Jager's initial suggestion of using traits classes to make <code class="computeroutput"><span class="identifier">mem_fn</span></code> adapt to user-defined smart pointers + inspired the <code class="computeroutput"><span class="identifier">get_pointer</span></code>-based + design. + </li> +<li class="listitem"> + Numerous improvements were suggested during the formal review period by + Richard Crossley, Jens Maurer, Ed Brey, and others. Review manager was + Darin Adler. + </li> +<li class="listitem"> + Steve Anichini pointed out that COM interfaces use <code class="computeroutput"><span class="identifier">__stdcall</span></code>. + </li> +<li class="listitem"> + Dave Abrahams modified <code class="computeroutput"><span class="identifier">bind</span></code> + and <code class="computeroutput"><span class="identifier">mem_fn</span></code> to support + <code class="computeroutput"><span class="keyword">void</span></code> returns on deficient + compilers. + </li> +<li class="listitem"> + Daniel Boelzle pointed out that UDK uses <code class="computeroutput"><span class="identifier">__cdecl</span></code>. + </li> +</ul></div> +<p> + This documentation was ported to Quickbook by Agustín Bergé. + </p> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"><p><small>Last revised: April 07, 2015 at 22:47:15 GMT</small></p></td> +<td align="right"><div class="copyright-footer"></div></td> +</tr></table> +<hr> +<div class="spirit-nav"></div> +</body> +</html> diff --git a/libs/bind/doc/html/standalone_bind_HTML.manifest b/libs/bind/doc/html/standalone_bind_HTML.manifest new file mode 100644 index 000000000..de245279a --- /dev/null +++ b/libs/bind/doc/html/standalone_bind_HTML.manifest @@ -0,0 +1 @@ +bind.html diff --git a/libs/bind/doc/html/standalone_mem_fn_HTML.manifest b/libs/bind/doc/html/standalone_mem_fn_HTML.manifest new file mode 100644 index 000000000..5e71f4675 --- /dev/null +++ b/libs/bind/doc/html/standalone_mem_fn_HTML.manifest @@ -0,0 +1 @@ +mem_fn.html diff --git a/libs/bind/doc/mem_fn.qbk b/libs/bind/doc/mem_fn.qbk new file mode 100644 index 000000000..9fe88d35d --- /dev/null +++ b/libs/bind/doc/mem_fn.qbk @@ -0,0 +1,32 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2005 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) + /] + +[library Boost.Member Function + [quickbook 1.6] + [id mem_fn] + [copyright 2001, 2002 Peter Dimov and Multi Media Ltd.] + [copyright 2003-2005 Peter Dimov] + [dirname bind] + [license Distributed under the + [@http://boost.org/LICENSE_1_0.txt Boost Software License, + Version 1.0]. + ] +] + +[template simplesect[title] +[block '''<simplesect><title>'''[title]'''</title>''']] + +[template endsimplesect[] +[block '''</simplesect>''']] + +[include mem_fn/purpose.qbk] +[include mem_fn/faq.qbk] +[include mem_fn/interface.qbk] +[include mem_fn/implementation.qbk] +[include mem_fn/acknowledgements.qbk] diff --git a/libs/bind/doc/mem_fn/acknowledgements.qbk b/libs/bind/doc/mem_fn/acknowledgements.qbk new file mode 100644 index 000000000..46d2b82fa --- /dev/null +++ b/libs/bind/doc/mem_fn/acknowledgements.qbk @@ -0,0 +1,28 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2005 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:acknowledgements Acknowledgements] + +* Rene Jager's initial suggestion of using traits classes to make `mem_fn` +adapt to user-defined smart pointers inspired the `get_pointer`-based design. + +* Numerous improvements were suggested during the formal review period by +Richard Crossley, Jens Maurer, Ed Brey, and others. Review manager was Darin +Adler. + +* Steve Anichini pointed out that COM interfaces use `__stdcall`. + +* Dave Abrahams modified `bind` and `mem_fn` to support `void` returns on +deficient compilers. + +* Daniel Boelzle pointed out that UDK uses `__cdecl`. + +This documentation was ported to Quickbook by Agustín Bergé. + +[endsect] diff --git a/libs/bind/doc/mem_fn/faq.qbk b/libs/bind/doc/mem_fn/faq.qbk new file mode 100644 index 000000000..169c8f14f --- /dev/null +++ b/libs/bind/doc/mem_fn/faq.qbk @@ -0,0 +1,53 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2005 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:faq Frequently Asked Questions] + +[section Can `mem_fn` be used instead of the standard `std::mem_fun[_ref]` +adaptors?] + +Yes. For simple uses, `mem_fn` provides additional functionality that the +standard adaptors do not. Complicated expressions that use `std::bind1st`, +`std::bind2nd` or [@http://www.boost.org/doc/libs/1_31_0/libs/compose/index.htm Boost.Compose] +along with the standard adaptors can be rewritten using `boost::bind` that +automatically takes advantage of `mem_fn`. + +[endsect] + +[section Should I replace every occurence of `std::mem_fun[_ref]` with +`mem_fn` in my existing code?] + +No, unless you have good reasons to do so. `mem_fn` is not 100% compatible +with the standard adaptors, although it comes pretty close. In particular, +`mem_fn` does not return objects of type `std::[const_]mem_fun[1][_ref]_t`, as +the standard adaptors do, and it is not possible to fully describe the type of +the first argument using the standard `argument_type` and `first_argument_type` +nested typedefs. Libraries that need adaptable function objects in order to +function might not like `mem_fn`. + +[endsect] + +[section Does `mem_fn` work with COM methods?] + +Yes, if you [link mem_fn.implementation.stdcall `#define BOOST_MEM_FN_ENABLE_STDCALL]. + +[endsect] + +[section Why isn't `BOOST_MEM_FN_ENABLE_STDCALL` defined automatically?] + +Non-portable extensions, in general, should default to off to prevent vendor +lock-in. Had `BOOST_MEM_FN_ENABLE_STDCALL` been defined automatically, you +could have accidentally taken advantage of it without realizing that your code +is, perhaps, no longer portable. In addition, it is possible for the default +calling convention to be `__stdcall`, in which case enabling `__stdcall` +support will result in duplicate definitions. + +[endsect] + +[endsect] diff --git a/libs/bind/doc/mem_fn/implementation.qbk b/libs/bind/doc/mem_fn/implementation.qbk new file mode 100644 index 000000000..f7314ad48 --- /dev/null +++ b/libs/bind/doc/mem_fn/implementation.qbk @@ -0,0 +1,70 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2005 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:implementation Implementation] + +[section Files] + +* [@../../include/boost/mem_fn.hpp boost/mem_fn.hpp] (main header) +* [@../../include/boost/bind/mem_fn_cc.hpp boost/bind/mem_fn_cc.hpp] (used by `mem_fn.hpp`, do not include directly) +* [@../../include/boost/bind/mem_fn_vw.hpp boost/bind/mem_fn_vw.hpp] (used by `mem_fn.hpp`, do not include directly) +* [@../../include/boost/bind/mem_fn_template.hpp boost/bind/mem_fn_template.hpp] (used by `mem_fn.hpp`, do not include directly) +* [@../../test/mem_fn_test.cpp libs/bind/test/mem_fn_test.cpp] (test) +* [@../../test/mem_fn_derived_test.cpp libs/bind/test/mem_fn_derived_test.cpp] (test with derived objects) +* [@../../test/mem_fn_fastcall_test.cpp libs/bind/test/mem_fn_fastcall_test.cpp] (test for `__fastcall`) +* [@../../test/mem_fn_stdcall_test.cpp libs/bind/test/mem_fn_stdcall_test.cpp] (test for `__stdcall`) +* [@../../test/mem_fn_void_test.cpp libs/bind/test/mem_fn_void_test.cpp] (test for `void` returns) + +[endsect] + +[section Dependencies] + +* [@boost:/libs/config/config.htm Boost.Config] + +[endsect] + +[section Number of Arguments] + +This implementation supports member functions with up to eight arguments. This +is not an inherent limitation of the design, but an implementation detail. + +[endsect] + +[section:stdcall `__stdcall`, `__cdecl`, and `__fastcall` Support] + +Some platforms allow several types of member functions that differ by their +calling convention (the rules by which the function is invoked: how are +arguments passed, how is the return value handled, and who cleans up the stack + - if any.) + +For example, Windows API functions and COM interface member functions use a +calling convention known as `__stdcall`. Borland VCL components use +`__fastcall`. UDK, the component model of OpenOffice.org, uses `__cdecl`. + +To use `mem_fn` with `__stdcall` member functions, `#define` the macro +`BOOST_MEM_FN_ENABLE_STDCALL` before including `<boost/mem_fn.hpp>`. + +To use `mem_fn` with `__fastcall` member functions, `#define` the macro +`BOOST_MEM_FN_ENABLE_FASTCALL` before including `<boost/mem_fn.hpp>`. + +To use `mem_fn` with `__cdecl` member functions, `#define` the macro +`BOOST_MEM_FN_ENABLE_CDECL` before including `<boost/mem_fn.hpp>`. + +[*It is best to define these macros in the project options, via `-D` on the +command line, or as the first line in the translation unit (.cpp file) where +`mem_fn` is used.] Not following this rule can lead to obscure errors when a +header includes `mem_fn.hpp` before the macro has been defined. + +/[Note:/ this is a non-portable extension. It is not part of the interface./]/ + +/[Note:/ Some compilers provide only minimal support for the `__stdcall` keyword./]/ + +[endsect] + +[endsect] diff --git a/libs/bind/doc/mem_fn/interface.qbk b/libs/bind/doc/mem_fn/interface.qbk new file mode 100644 index 000000000..c0528a535 --- /dev/null +++ b/libs/bind/doc/mem_fn/interface.qbk @@ -0,0 +1,133 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2005 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:interface Interface] + +[section:synopsys Synopsis] + + namespace boost + { + template<class T> T * ``[link get_pointer_1 `get_pointer`]``(T * p); + + template<class R, class T> ``/unspecified-1/`` ``[link mem_fn_1 `mem_fn`]``(R (T::*pmf) ()); + + template<class R, class T> ``/unspecified-2/`` ``[link mem_fn_2 `mem_fn`]``(R (T::*pmf) () const); + + template<class R, class T> ``/unspecified-2-1/`` ``[link mem_fn_2_1 `mem_fn`]``(R T::*pm); + + template<class R, class T, class A1> ``/unspecified-3/`` ``[link mem_fn_3 `mem_fn`]``(R (T::*pmf) (A1)); + + template<class R, class T, class A1> ``/unspecified-4/`` ``[link mem_fn_4 `mem_fn`]``(R (T::*pmf) (A1) const); + + template<class R, class T, class A1, class A2> ``/unspecified-5/`` ``[link mem_fn_5 `mem_fn`]``(R (T::*pmf) (A1, A2)); + + template<class R, class T, class A1, class A2> ``/unspecified-6/`` ``[link mem_fn_6 `mem_fn`]``(R (T::*pmf) (A1, A2) const); + + // implementation defined number of additional overloads for more arguments + } + +[endsect] + +[section Common requirements] + +All /unspecified-N/ types mentioned in the Synopsis are /CopyConstructible/ +and /Assignable/. Their copy constructors and assignment operators do not +throw exceptions. /unspecified-N/`::result_type` is defined as the return type +of the member function pointer passed as an argument to `mem_fn` (`R` in the +Synopsis.) /unspecified-2-1/`::result_type` is defined as `R`. + +[endsect] + +[section `get_pointer`] + +[#get_pointer_1] + + template<class T> T * get_pointer(T * p) + +* /Returns:/ `p`. + +* /Throws:/ Nothing. + +[endsect] + +[section `mem_fn`] + +[#mem_fn_1] + + template<class R, class T> ``/unspecified-1/`` mem_fn(R (T::*pmf) ()) + +* /Returns:/ a function object \u03DD such that the expression \u03DD`(t)` is +equivalent to `(t.*pmf)()` when `t` is an l-value of type `T` or derived, +`(get_pointer(t)->*pmf)()` otherwise. + +* /Throws:/ Nothing. + +[#mem_fn_2] + + template<class R, class T> ``/unspecified-2/`` mem_fn(R (T::*pmf) () const) + +* /Returns:/ a function object \u03DD such that the expression \u03DD`(t)` is +equivalent to `(t.*pmf)()` when `t` is of type `T` /[/`const`/]/ or derived, +`(get_pointer(t)->*pmf)()` otherwise. + +* /Throws:/ Nothing. + +[#mem_fn_2_1] + + template<class R, class T> ``/unspecified-2-1/`` mem_fn(R T::*pm) + +* /Returns:/ a function object \u03DD such that the expression \u03DD`(t)` is +equivalent to `t.*pm` when `t` is of type `T` /[/`const`/]/ or derived, +`get_pointer(t)->*pm` otherwise. + +* /Throws:/ Nothing. + +[#mem_fn_3] + + template<class R, class T, class A1> ``/unspecified-3/`` mem_fn(R (T::*pmf) (A1)) + +* /Returns:/ a function object \u03DD such that the expression \u03DD`(t, a1)` +is equivalent to `(t.*pmf)(a1)` when `t` is an l-value of type `T` or derived, +`(get_pointer(t)->*pmf)(a1)` otherwise. + +* /Throws:/ Nothing. + +[#mem_fn_4] + + template<class R, class T, class A1> ``/unspecified-4/`` mem_fn(R (T::*pmf) (A1) const) + +* /Returns:/ a function object \u03DD such that the expression \u03DD`(t, a1)` +is equivalent to `(t.*pmf)(a1)` when `t` is of type `T` /[/`const`/]/ or derived, +`(get_pointer(t)->*pmf)(a1)` otherwise. + +* /Throws:/ Nothing. + +[#mem_fn_5] + + template<class R, class T, class A1, class A2> ``/unspecified-5/`` mem_fn(R (T::*pmf) (A1, A2)) + +* /Returns:/ a function object \u03DD such that the expression \u03DD`(t, a1, a2)` +is equivalent to `(t.*pmf)(a1, a2)` when `t` is an l-value of type `T` or derived, +`(get_pointer(t)->*pmf)(a1, a2)` otherwise. + +* /Throws:/ Nothing. + +[#mem_fn_6] + + template<class R, class T, class A1, class A2> ``/unspecified-6/`` mem_fn(R (T::*pmf) (A1, A2) const) + +* /Returns:/ a function object \u03DD such that the expression \u03DD`(t, a1, a2)` +is equivalent to `(t.*pmf)(a1, a2)` when `t` is of type `T` /[/`const`/]/ or derived, +`(get_pointer(t)->*pmf)(a1, a2)` otherwise. + +* /Throws:/ Nothing. + +[endsect] + +[endsect] diff --git a/libs/bind/doc/mem_fn/purpose.qbk b/libs/bind/doc/mem_fn/purpose.qbk new file mode 100644 index 000000000..5fc649919 --- /dev/null +++ b/libs/bind/doc/mem_fn/purpose.qbk @@ -0,0 +1,93 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2005 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:purpose Purpose] + +`boost::mem_fn` is a generalization of the standard functions `std::mem_fun` +and `std::mem_fun_ref`. It supports member function pointers with more than +one argument, and the returned function object can take a pointer, a +reference, or a smart pointer to an object instance as its first argument. +`mem_fn` also supports pointers to data members by treating them as functions +taking no arguments and returning a (const) reference to the member. + +The purpose of `mem_fn` is twofold. First, it allows users to invoke a member +function on a container with the familiar + + std::for_each(v.begin(), v.end(), boost::mem_fn(&Shape::draw)); + +syntax, even when the container stores smart pointers. + +Second, it can be used as a building block by library developers that want to +treat a pointer to member function as a function object. A library might +define an enhanced `for_each` algorithm with an overload of the form: + + template<class It, class R, class T> void for_each(It first, It last, R (T::*pmf) ()) + { + std::for_each(first, last, boost::mem_fn(pmf)); + } + +that will allow the convenient syntax: + + for_each(v.begin(), v.end(), &Shape::draw); + +When documenting the feature, the library author will simply state: + + template<class It, class R, class T> void for_each(It first, It last, R (T::*pmf) ()); + +* /Effects:/ Equivalent to `std::for_each(first, last, boost::mem_fn(pmf))`. + +where `boost::mem_fn` can be a link to this page. See the +[@boost:/libs/bind/bind.html documentation of `bind`] for an example. + +`mem_fn` takes one argument, a pointer to a member, and returns a function +object suitable for use with standard or user-defined algorithms: + + struct X + { + void f(); + }; + + void g(std::vector<X> & v) + { + std::for_each(v.begin(), v.end(), boost::mem_fn(&X::f)); + }; + + void h(std::vector<X *> const & v) + { + std::for_each(v.begin(), v.end(), boost::mem_fn(&X::f)); + }; + + void k(std::vector<boost::shared_ptr<X> > const & v) + { + std::for_each(v.begin(), v.end(), boost::mem_fn(&X::f)); + }; + +The returned function object takes the same arguments as the input member +function plus a "flexible" first argument that represents the object instance. + +When the function object is invoked with a first argument `x` that is neither +a pointer nor a reference to the appropriate class (`X` in the example above), +it uses `get_pointer(x)` to obtain a pointer from `x`. Library authors can +"register" their smart pointer classes by supplying an appropriate +`get_pointer` overload, allowing `mem_fn` to recognize and support them. + + +/[Note:/ `get_pointer` is not restricted to return a pointer. Any object that +can be used in a member function call expression `(x->*pmf)(...)` will work./]/ + +/[Note:/ the library uses an unqualified call to `get_pointer`. Therefore, it +will find, through argument-dependent lookup, `get_pointer` overloads that are +defined in the same namespace as the corresponding smart pointer class, in +addition to any `boost::get_pointer` overloads./]/ + +All function objects returned by `mem_fn` expose a `result_type` typedef that +represents the return type of the member function. For data members, +`result_type` is defined as the type of the member. + +[endsect] |