mirror of
https://github.com/boostorg/function.git
synced 2025-07-18 07:02:11 +02:00
e9ce99dede
test/function_test.cpp: - Don't use deprecated functions index.html: doc/reference.html: - Describe deprecations [SVN r14540]
290 lines
18 KiB
HTML
290 lines
18 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<title>Boost.Function Reference Manual</title>
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080">
|
|
|
|
<h1><IMG SRC="../../../c++boost.gif" WIDTH="276" HEIGHT="86">Boost.Function Reference Manual</h1>
|
|
|
|
<h2><a name="header">Header <code><<a href="../../../boost/function.hpp">boost/function.hpp</a>></code> synopsis</a></h2>
|
|
<p> Here <code><i>MAX_ARGS</i></code> is an implementation-defined constant that defines the maximum number of function arguments supported by Boost.Function and will be at least 10. The <code><i>MAX_ARGS</i></code> constant referred to in this document need not have any direct representation in the library.
|
|
|
|
<pre>
|
|
<b>namespace</b> boost {
|
|
<b>class</b> <a href="#function_base">function_base</a>
|
|
{
|
|
<b>typedef</b> <em>implementation-defined</em> safe_bool;
|
|
<a href="#empty"><b>bool</b> empty() <b>const</b></a>;
|
|
<a href="#bool"><b>operator</b> safe_bool() <b>const</b></a>;
|
|
<a href="#not">safe_bool <b>operator!</b>() <b>const</b></a>;
|
|
};
|
|
|
|
// For <i>N</i> in [0, <i>MAX_ARGS</i>]
|
|
<b>template</b><<b>typename</b> Signature,
|
|
<b>typename</b> Arg1,
|
|
<b>typename</b> Arg2,
|
|
<i>...</i>
|
|
<b>typename</b> Arg<i>N</i>,
|
|
<b>typename</b> Policy = empty_function_policy, <em>// Deprecated</em>
|
|
<b>typename</b> Mixin = empty_function_mixin, <em>// Deprecated</em>
|
|
<b>typename</b> Allocator = std::allocator<function_base> >
|
|
<b>class</b> <a href="#functionN">function<i>N</i></a> : <b>public</b> <a href="#function_base">function_base</a>, <b>public</b> Mixin
|
|
{
|
|
<b>typedef</b> ResultType result_type; <em>// <a href="#novoid">[1]</a></em>
|
|
<b>typedef</b> Policy policy_type; <em>// Deprecated</em>
|
|
<b>typedef</b> Mixin mixin_type; <em>// Deprecated</em>
|
|
<b>typedef</b> Allocator allocator_type;
|
|
|
|
<b>typedef</b> Arg1 argument_type; <i>// If N == 1</i>
|
|
|
|
<b>typedef</b> Arg1 first_argument_type; <i>// If N == 2</i>
|
|
<b>typedef</b> Arg2 second_argument_type; <i>// If N == 2</i>
|
|
|
|
<i>// Construction</i>
|
|
<a href="#functionN_default"><b>explicit</b> function<i>N</i>(<b>const</b> Mixin<b>&</b> = Mixin())</a>;
|
|
<a href="#functionN_copy">function<i>N</i>(<b>const</b> function<i>N</i><b>&</b>)</a>;
|
|
<a href="#functionN_target"><b>template</b><<b>typename</b> F> function<i>N</i>(F, <b>const</b> Mixin<b>&</b> = Mixin())</a>;
|
|
<a href="#functionN_target_ref"><b>template</b><<b>typename</b> F> function<i>N</i>(reference_wrapper<F>)</a>;
|
|
|
|
<i>// Assignment</i>
|
|
<a href="#functionN_copy_assn">function<i>N</i><b>&</b> <b>operator</b>=(<b>const</b> function<i>N</i><b>&</b>)</a>;
|
|
<a href="#functionN_target_assn"><b>template</b><<b>typename</b> F> function<i>N</i><b>&</b> <b>operator</b>=(F)</a>;
|
|
<a href="#functionN_target_ref_assn"><b>template</b><<b>typename</b> F> function<i>N</i><b>&</b> <b>operator</b>=(reference_wrapper<F>)</a>;
|
|
<a href="#functionN_copy_set"><b>void</b> set(<b>const</b> function<i>N</i><b>&</b>)</a>; <em>// Deprecated</em>
|
|
<a href="#functionN_target_set"><b>template</b><<b>typename</b> F> <b>void</b> set(F)</a>; <em>// Deprecated</em>
|
|
<a href="#functionN_swap"><b>void</b> swap(function<i>N</i><b>&</b>)</a>;
|
|
<a href="#functionN_clear"><b>void</b> clear()</a>;
|
|
|
|
<i>// Invocation</i>
|
|
<a href="#functionN_call_const">result_type <b>operator</b>()(Arg1 a1, Arg2 a2, <i>...</i>, Arg<i>N</i> a<i>N</i>) <b>const</b></a>;
|
|
};
|
|
|
|
<b>template</b><<b>typename</b> ResultType,
|
|
<b>typename</b> Arg1,
|
|
<b>typename</b> Arg2,
|
|
<i>...</i>
|
|
<b>typename</b> Arg<i>N</i>,
|
|
<b>typename</b> Policy, <em>// Deprecated</em>
|
|
<b>typename</b> Mixin, <em>// Deprecated</em>
|
|
<b>typename</b> Allocator>
|
|
<b>void</b> <a href="#swap_functionN">swap</a>(function<em>N</em><ResultType, Arg1, Arg2, <i>...</i>, Arg<i>N</i>, Policy, Mixin, Allocator><b>&</b>,
|
|
function<em>N</em><ResultType, Arg1, Arg2, <i>...</i>, Arg<i>N</i>, Policy, Mixin, Allocator><b>&</b>);
|
|
|
|
// For any <i>N</i> in [0, <i>MAX_ARGS</i>]
|
|
<b>template</b><<b>typename</b> Signature, <em>// Function type: ResultType (Arg1, Arg2, ..., Arg<em>N</em>)</em>
|
|
<b>typename</b> Policy = empty_function_policy, <em>// Deprecated</em>
|
|
<b>typename</b> Mixin = empty_function_mixin, <em>// Deprecated</em>
|
|
<b>typename</b> Allocator = std::allocator<function_base> >
|
|
<b>class</b> <a href="#function">function</a> : <b>public</b> <a href="#functionN">function<i>N</i></a><ResultType, Arg1, Arg2, <i>...</i>, Arg<i>N</i>>
|
|
{
|
|
<i>// Construction</i>
|
|
function();
|
|
function(<b>const</b> function<b>&</b>);
|
|
function(<b>const</b> function<i>N</i><ResultType, Arg1, Arg2, ..., Arg<i>N</i>><b>&</b>);
|
|
<b>template</b><<b>typename</b> F> function<i>N</i>(F);
|
|
|
|
<i>// Assignment</i>
|
|
function<b>&</b> <b>operator</b>=(<b>const</b> function<b>&</b>);
|
|
function<b>&</b> <b>operator</b>=(<b>const</b> function<i>N</i><ResultType, Arg1, Arg2, ..., Arg<i>N</i>><b>&</b>);
|
|
<b>template</b><<b>typename</b> F> function<b>&</b> <b>operator</b>=(F);
|
|
<b>void</b> set(<b>const</b> function<b>&</b>); <em>// Deprecated</em>
|
|
<b>void</b> set(<b>const</b> function<i>N</i><ResultType, Arg1, Arg2, ..., Arg<i>N</i>><b>&</b>); <em>// Deprecated</em>
|
|
<b>template</b><<b>typename</b> F> <b>void</b> set(F); <em>// Deprecated</em>
|
|
};
|
|
|
|
<b>template</b><<b>typename</b> Signature, <b>typename</b> Policy, <b>typename</b> Mixin, <b>typename</b> Allocator>
|
|
<b>void</b> <a href="#swap_function">swap</a>(function<Signature, Policy, Mixin, Allocator><b>&</b>,
|
|
function<Signature, Policy, Mixin, Allocator><b>&</b>);
|
|
}
|
|
</pre>
|
|
|
|
<h2>Definitions</h2>
|
|
<p>
|
|
<ul>
|
|
<li><a name="compatible"></a>A function object <code>f</code> is <em>compatible</em> if for the given set of argument types <code>Arg1</code>, <code>Arg2</code>, ..., <code>Arg<em>N</em></code> and a return type <code>ResultType</code>, the appropriate following function is well-formed:
|
|
<pre>
|
|
<em>// if ResultType is not <b>void</b></em>
|
|
ResultType foo(Arg1 arg1, Arg2 arg2, ..., Arg<em>N</em> arg<em>N</em>)
|
|
{
|
|
<b>return</b> f(arg1, arg2, ..., arg<em>N</em>);
|
|
}
|
|
|
|
<em>// if ResultType is <b>void</b></em>
|
|
ResultType foo(Arg1 arg1, Arg2 arg2, ..., Arg<em>N</em> arg<em>N</em>)
|
|
{
|
|
f(arg1, arg2, ..., arg<em>N</em>);
|
|
}
|
|
</pre>
|
|
<p> A special provision is made for pointers to member functions. Though they are not function objects, Boost.Function will adapt them internally to function objects. This requires that a pointer to member function of the form <code>R (X::*mf)(Arg1, Arg2, ..., Arg<em>N</em>) <em>cv-quals</em></code> be adapted to a function object with the following function call operator overloads:
|
|
<pre>
|
|
<b>template</b><<b>typename P</b>>
|
|
R <b>operator</b>()(<em>cv-quals</em> P& x, Arg1 arg1, Arg2 arg2, ..., Arg<em>N</em> arg<em>N</em>) <b>const</b>
|
|
{
|
|
<b>return</b> (*x).*mf(arg1, arg2, ..., arg<em>N</em>);
|
|
}
|
|
</pre>
|
|
<li><a name="stateless"></a>A function object <code>f</code> of type <code>F</code> is <em>stateless</em> if it is a function pointer or if <a href="../../type_traits/index.htm#properties"><code>boost::is_stateless<T></code></a> is true. The construction of or copy to a Boost.Function object from a stateless function object will not cause exceptions to be thrown and will not allocate any storage.</li>
|
|
</ul>
|
|
|
|
<h2><a name="function_base">Class <code>function_base</code></a></h2>
|
|
<p> Class <code>function_base</code> is the common base class for all Boost.Function objects. Objects of type <code>function_base</code> may not be created directly.
|
|
|
|
<p> <a name="empty"><code><b>bool</b> empty() <b>const</b></code></a>
|
|
<ul>
|
|
<li><b>Returns</b>: <code>true</code> if the function object has a target, <code>false</code> otherwise.</li>
|
|
<li><b>Throws</b>: will not throw.</li>
|
|
</ul>
|
|
|
|
<p> <a name="bool"><code><b>operator</b> safe_bool() <b>const</b></code></a>
|
|
<ul>
|
|
<li><b>Returns</b>: <code>safe_bool</code> equivalent of <code>!<a href="#empty">empty</a>()</code></li>
|
|
<li><b>Throws</b>: will not throw.</li>
|
|
<li><b>Notes</b>: The <code>safe_bool</code> type can be used in contexts where a <b>bool</b> is expected (e.g., an <b>if</b> condition); however, implicit conversions (e.g., to <b>int</b>) that can occur with <b>bool</b> are not allowed, eliminating some sources of user error.
|
|
</ul>
|
|
|
|
<p> <a name="not"><code>safe_bool <b>operator!</b>() <b>const</b></code></a>
|
|
<ul>
|
|
<li><b>Returns</b>: <code>safe_bool</code> equivalent of <code><a href="#empty">empty</a>()</code></li>
|
|
<li><b>Throws</b>: will not throw.</li>
|
|
<li><b>Notes</b>: See <a href="#bool"><code>safe_bool</code> conversion</a>
|
|
</ul>
|
|
|
|
<h2><a name="functionN">Class template <code>function<i>N</i></code></a></h2>
|
|
<p> Class template <code>function<i>N</i></code> is actually a family of related classes <code>function0</code>, <code>function1</code>, etc., up to some implementation-defined maximum. In this context, <code><i>N</i></code> refers to the number of parameters and <code>f</code> refers to the implicit object parameter.
|
|
|
|
<p> <a name="functionN_default"><code><b>explicit</b> function<i>N</i>(<b>const</b> Mixin<b>&</b> = Mixin());</code></a>
|
|
<ul>
|
|
<li><b>Effects</b>: Constructs the <code>Mixin</code> subobject with the given mixin.</li>
|
|
<li><b>Postconditions</b>: <code>f.<a href="#empty">empty</a>()</code>.</li>
|
|
<li><b>Throws</b>: will not throw unless construction of the <code>Mixin</code> subobject throws.</li>
|
|
</ul>
|
|
|
|
<p> <a name="functionN_copy"><code>function<i>N</i>(<b>const</b> function<i>N</i><b>&</b> g);</code></a>
|
|
<ul>
|
|
<li><b>Postconditions</b>: <code>f</code> contains a copy of the <code>g</code>'s target, if it has one, or is empty if <code>g.<a href="#empty">empty</a>()</code>. The mixin for the <code>f</code> is copy-constructed from the mixin of <code>g</code>.</li>
|
|
<li><b>Throws</b>: will not throw unless copying the target of <code>g</code> or construction of the <code>Mixin</code> subobject throws.</li>
|
|
</ul>
|
|
|
|
<p> <a name="functionN_target"><code><b>template</b><<b>typename</b> F> function<i>N</i>(F g, <b>const</b> Mixin<b>&</b> = Mixin());</code></a>
|
|
<ul>
|
|
<li><b>Requires</b>: <code>g</code> is a <a href="#compatible">compatible</a> function object.</li>
|
|
<li><b>Effects</b>: Constructs the <code>Mixin</code> subobject from the given mixin.</li>
|
|
<li><b>Postconditions</b>: <code>f</code> targets a copy of <code>g</code> if <code>g</code> is nonempty, or <code>f.<a href="#empty">empty</a>()</code> if <code>g</code> is empty.</li>
|
|
<li><b>Throws</b>: will not throw when <code>g</code> is a <a href="#stateless">stateless</a> function object unless construction of the <code>Mixin</code> subobject throws.</li>
|
|
</ul>
|
|
|
|
<p> <a name="functionN_target_ref"><code><b>template</b><<b>typename</b> F> function<i>N</i>(<a href="../../bind/ref.html">reference_wrapper</a><F> g);</code></a>
|
|
<ul>
|
|
<li><b>Requires</b>: <code>g.get()</code> is a <a href="#compatible">compatible</a> function object.</li>
|
|
<li><b>Effects</b>: Constructs the <code>Mixin</code> subobject from the given mixin.</li>
|
|
<li><b>Postconditions</b>: <code>this</code> object targets <code>g</code> (<em>not</em> a copy of <code>g.get()</code>) if <code>g.get()</code> is nonempty, or <code>this->empty()</code> if <code>g.get()</code> is empty.</li>
|
|
<li><b>Throws</b>: will not throw unless the construction of the <code>Mixin</code> subobject throws.</li>
|
|
</ul>
|
|
|
|
<p> <a name="functionN_copy_assn"><code>function<i>N</i><b>&</b> <b>operator</b>=(<b>const</b> function<i>N</i><b>&</b> g);</code></a>
|
|
<ul>
|
|
<li><b>Postconditions</b>: <code>f</code> targets a copy of <code>g</code>'s target, if it has one, or is empty if <code>g.<a href="#empty">empty</a>()</code>. The mixin for <code>f</code> is assigned the value of the mixin for <code>g</code>.</li>
|
|
<li><b>Returns</b>: <code>*this</code>.</li>
|
|
<li><b>Throws</b>: will not throw when the target of <code>g</code> is a <a href="#stateless">stateless</a> function object or a reference to the function object, unless the copy of the <code>Mixin</code> subobject throws.</li>
|
|
</ul>
|
|
|
|
<p> <a name="functionN_target_assn"><code><b>template</b><<b>typename</b> F> function<i>N</i><b>&</b> <b>operator</b>=(F g);</code></a>
|
|
<ul>
|
|
<li><b>Requires</b>: <code>g</code> is a <a href="#compatible">compatible</a> function object.</li>
|
|
<li><b>Postconditions</b>: <code>f</code> targets a copy of <code>g</code> if <code>g</code> is nonempty, or <code>f.<a href="#empty">empty</a>()</code> if <code>g</code> is empty.</li>
|
|
<li><b>Returns</b>: <code>*this</code>.</li>
|
|
<li><b>Throws</b>: will not throw when <code>g</code> is a <a href="#stateless">stateless</a> function object.</li>
|
|
</ul>
|
|
|
|
<p> <a name="functionN_target_ref_assn"><code><b>template</b><<b>typename</b> F> function<i>N</i><b>&</b> <b>operator</b>=(<a href="../../bind/ref.html">reference_wrapper</a><F> g);</code></a>
|
|
<ul>
|
|
<li><b>Requires</b>: <code>g.get()</code> is a <a href="#compatible">compatible</a> function object.</li>
|
|
<li><b>Postconditions</b>: <code>f</code> targets <code>g.get()</code> (not a copy of <code>g.get()</code>) if <code>g.get()</code> is nonempty, or <code>f.<a href="#empty">empty</a>()</code> if <code>g.get()</code> is empty.</li>
|
|
<li><b>Returns</b>: <code>*this</code>.</li>
|
|
<li><b>Throws</b>: will throw only if the destruction or deallocation of the target of <code>this</code> throws.</li>
|
|
</ul>
|
|
|
|
<p> <a name="functionN_copy_set"><code><b>void</b> set(<b>const</b> function<i>N</i><b>&</b> g);</code></a>
|
|
<ul>
|
|
<li><b>Effects</b>: <code><a href="#functionN_copy_assn">*this = g</a></code>.</li>
|
|
<li><b>Note</b>: This function is deprecated and will be removed in future versions of Boost.Function. Please use the assignment operator instead.</li>
|
|
</ul>
|
|
|
|
<p> <a name="functionN_target_set"><code><b>template</b><<b>typename</b> F> <b>void</b> set(F g);</code></a>
|
|
<ul>
|
|
<li><b>Effects</b>: <code><a href="#functionN_target_assn">*this = g</a></code>.</li>
|
|
<li><b>Note</b>: This function is deprecated and will be removed in future versions of Boost.Function. Please use the assignment operator instead.</li>
|
|
</ul>
|
|
|
|
<p> <a name="functionN_swap"><code><b>void</b> swap(function<i>N</i><b>&</b> g);</code></a>
|
|
<ul>
|
|
<li><b>Effects</b>: interchanges the targets of <code>f</code> and <code>g</code> and swaps the mixins of <code>f</code> and <code>g</code>.</li>
|
|
<li><b>Throws</b>: will not throw.</li>
|
|
</ul>
|
|
|
|
<p> <a name="functionN_clear"><code><b>void</b> clear(); </code></a>
|
|
<ul>
|
|
<li><b>Effects</b>: If <code>!<a href="#empty">empty</a>()</code>, deallocates current target.</li>
|
|
<li><b>Postconditions</b>: <code><a href="#empty">empty</a>()</code>.</li>
|
|
</ul>
|
|
|
|
<p> <a name="functionN_call_const"><code> result_type <b>operator</b>()(Arg1 a1, Arg2 a2, <i>...</i>, Arg<i>N</i> a<i>N</i>) <b>const</b>;</code></a>
|
|
<ul>
|
|
<li><b>Requires</b>: <code>!<a href="#empty">empty</a>()</code>.</li>
|
|
<li><b>Effects</b>: <i>target</i> is the underlying function target. It is not <code><b>const</b></code> or <code><b>volatile</b></code> qualified.
|
|
<ol>
|
|
<li><code>policy_type policy;</code></li>
|
|
<li><code>policy.precall(this);</code></li>
|
|
<li><code><i>target</i>(a1, a2, <i>...</i>, a<i>N</i>);</code></li>
|
|
<li><code>policy.postcall(this);</code></li>
|
|
</ol>
|
|
<li><b>Returns</b>: the value returned by <i>target</i>.</li>
|
|
<li><b>Note</b>: invocation policies have been deprecated and will be removed in a later release.</li>
|
|
</ul>
|
|
|
|
<h2><a name="function">Class template <code>function</code></a></h2>
|
|
<p> Class template <code>function</code> is a thin wrapper around the numbered class templates <code>function0</code>, <code>function1</code>, etc. It accepts up to <i>MAX_ARGS</i> arguments, but when passed <i>N</i> arguments it will derive from <code>function<i>N</i></code> specialized with the arguments it receives.
|
|
|
|
<p> The semantics of all operations in class template <code>function</code> are equivalent to that of the underlying <code>function<i>N</i></code> object, although additional member functions are required to allow proper copy construction and copy assignment of <code>function</code> objects.
|
|
|
|
<h2><a name="operations">Operations</a></h2>
|
|
<p>
|
|
<pre>
|
|
<b>template</b><<b>typename</b> ResultType,
|
|
<b>typename</b> Arg1,
|
|
<b>typename</b> Arg2,
|
|
<i>...</i>
|
|
<b>typename</b> Arg<i>N</i>,
|
|
<b>typename</b> Policy, <em>// Deprecated</em>
|
|
<b>typename</b> Mixin, <em>// Deprecated</em>
|
|
<b>typename</b> Allocator>
|
|
<b>void</b> <a name="swap_functionN">swap</a>(function<i>N</i><ResultType, Arg1, Arg2, <i>...</i>, Arg<i>N</i>, Policy, Mixin, Allocator><b>&</b> f,
|
|
function<i>N</i><ResultType, Arg1, Arg2, <i>...</i>, Arg<i>N</i>, Policy, Mixin, Allocator><b>&</b> g);
|
|
</pre>
|
|
<ul>
|
|
<li><b>Effects</b>: <code>f.<a href="#functionN_swap">swap</a>(g);</code></li>
|
|
</ul>
|
|
|
|
<p>
|
|
<pre>
|
|
<b>template</b><<b>typename</b> Signature, <b>typename</b> Policy, <b>typename</b> Mixin, <b>typename</b> Allocator>
|
|
<b>void</b> <a name="swap_function">swap</a>(function<Signature, Policy, Mixin, Allocator><b>&</b> f,
|
|
function<Signature, Policy, Mixin, Allocator><b>&</b> g);
|
|
</pre>
|
|
<ul>
|
|
<li><b>Effects</b>: <code>f.<a href="#functionN_swap">swap</a>(g);</code></li>
|
|
</ul>
|
|
|
|
<hr>
|
|
<p><a name="novoid">[1]</a> On compilers not supporting void returns, when the <code>ReturnType</code> is <b>void</b>, the <code>result_type</code> of a Boost.Function object is implementation-defined.
|
|
<hr>
|
|
<address><a href="mailto:gregod@cs.rpi.edu">Douglas Gregor</a></address>
|
|
<!-- Created: Fri Jul 13 10:57:20 EDT 2001 -->
|
|
<!-- hhmts start -->
|
|
Last modified: Fri Jul 19 16:40:00 EDT 2002
|
|
<!-- hhmts end -->
|
|
</body>
|
|
</html>
|