2003-03-12 23:27:25 +00:00
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<library-reference id= "function.reference" last-revision= "$Date$" >
<section id= "function.definitions" >
<title> Definitions</title>
<para>
<itemizedlist>
<listitem>
<para> A function object <computeroutput> f</computeroutput> is
<emphasis> compatible</emphasis> if for the given set of argument
types <computeroutput> Arg1</computeroutput> ,
<computeroutput> Arg2</computeroutput> , ...,
<computeroutput> ArgN</computeroutput> and a
return type <computeroutput> ResultType</computeroutput> , the
appropriate following function is well-formed:
<programlisting>
<emphasis> // if ResultType is not <emphasis role= "bold" > void</emphasis></emphasis>
ResultType foo(Arg1 arg1, Arg2 arg2, ..., Arg<emphasis> N</emphasis> arg<emphasis> N</emphasis> )
{
<emphasis role= "bold" > return</emphasis> f(arg1, arg2, ..., arg<emphasis> N</emphasis> );
}
<emphasis> // if ResultType is <emphasis role= "bold" > void</emphasis></emphasis>
ResultType foo(Arg1 arg1, Arg2 arg2, ..., Arg<emphasis> N</emphasis> arg<emphasis> N</emphasis> )
{
f(arg1, arg2, ..., arg<emphasis> N</emphasis> );
}
</programlisting></para>
<para> 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, ..., ArgN)
cv-quals</code> be adapted to a
function object with the following function call operator
overloads:
<programlisting>
<emphasis role= "bold" > template</emphasis> < <emphasis role= "bold" > typename P</emphasis> >
R <emphasis role= "bold" > operator</emphasis> ()(<emphasis> cv-quals</emphasis> P& x, Arg1 arg1, Arg2 arg2, ..., Arg<emphasis> N</emphasis> arg<emphasis> N</emphasis> ) <emphasis role= "bold" > const</emphasis>
{
<emphasis role= "bold" > return</emphasis> (*x).*mf(arg1, arg2, ..., arg<emphasis> N</emphasis> );
}
</programlisting>
</para>
</listitem>
<listitem>
<para> A function object <code> f</code> of
type <code> F</code> is
<emphasis> stateless</emphasis> if it is a function pointer or if
<code><classname> boost::is_stateless</classname> < T> </code>
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.
</para>
</listitem>
</itemizedlist>
</para>
</section>
<header name= "boost/function.hpp" >
<namespace name= "boost" >
<class name= "bad_function_call" >
<inherit access= "public" ><classname> std::runtime_error</classname></inherit>
<purpose> An exception type thrown when an instance of a <code> function</code> object is empty when invoked.</purpose>
<constructor>
<effects><simpara> Constructs a <code><classname> bad_function_call</classname></code> exception object.</simpara></effects>
</constructor>
</class>
<class name= "function_base" >
<purpose> The common base class for all Boost.Function
objects. Objects of type function_base may not be created
directly.</purpose>
2003-03-15 23:12:35 +00:00
<method-group name= "capacity" >
<method name= "empty" cv= "const" >
<type> bool</type>
2003-03-12 23:27:25 +00:00
<returns><simpara><code> true</code> if <code> this</code> has a target, and <code> false</code> otherwise.</simpara></returns>
<throws><simpara> Will not throw.</simpara></throws>
</method>
2003-03-15 23:12:35 +00:00
</method-group>
2004-01-25 00:38:26 +00:00
<method-group name= "target access" >
<overloaded-method name= "target" >
<signature>
<template>
<template-type-parameter name= "Functor" />
</template>
<type> Functor*</type>
</signature>
<signature cv= "const" >
<template>
<template-type-parameter name= "Functor" />
</template>
<type> const Functor*</type>
</signature>
<returns><simpara> If <code> this</code> stores a target of type
<code> Functor</code> , returns the address of the
target. Otherwise, returns the NULL
pointer.</simpara></returns>
<throws><simpara> Will not throw.</simpara></throws>
</overloaded-method>
</method-group>
2003-03-12 23:27:25 +00:00
</class>
<class name= "functionN" >
<template>
<template-type-parameter name= "R" />
<template-type-parameter name= "T1" />
<template-type-parameter name= "T2" />
<template-varargs/>
<template-type-parameter name= "TN" />
<template-type-parameter name= "Allocator" >
<default><classname> std::allocator</classname> < void> </default>
</template-type-parameter>
</template>
<inherit access= "public" ><classname> function_base</classname></inherit>
<purpose> A set of generalized function pointers that can be used for callbacks or wrapping function objects.</purpose>
2003-03-13 00:08:34 +00:00
<description>
<para> Class template <classname> functionN</classname> is
actually a family of related classes <classname
alt= "functionN" > function0</classname> , <classname
alt= "functionN" > function1</classname> , etc., up to some
implementation-defined maximum. In this context, <code> N</code>
refers to the number of parameters.</para>
</description>
2003-03-12 23:27:25 +00:00
<typedef name= "result_type" ><type> R</type></typedef>
<typedef name= "allocator_type" ><type> Allocator</type></typedef>
<typedef name= "argument_type" >
<type> T1</type><purpose> If N == 1</purpose>
</typedef>
<typedef name= "first_argument_type" >
<type> T1</type>
<purpose> If N == 2</purpose>
</typedef>
<typedef name= "second_argument_type" >
<type> T2</type>
<purpose> If N == 2</purpose>
</typedef>
<typedef name= "arg1_type" ><type> T1</type></typedef>
<typedef name= "arg2_type" ><type> T2</type></typedef>
2003-03-15 23:12:35 +00:00
<typedef name= "..." ><type/></typedef>
2003-03-12 23:27:25 +00:00
<typedef name= "argN_type" ><type> TN</type></typedef>
2003-03-13 00:29:57 +00:00
<static-constant name= "arity" >
<type> int</type>
<default> N</default>
</static-constant>
2003-03-12 23:27:25 +00:00
2003-03-16 02:00:20 +00:00
<struct name= "sig" >
<template>
<template-type-parameter name= "Args" />
</template>
<purpose>
<simpara><libraryname> Lambda</libraryname> library support</simpara>
</purpose>
<typedef name= "type" ><type> result_type</type></typedef>
</struct>
2003-03-12 23:27:25 +00:00
<constructor>
<postconditions><simpara><code> this-><methodname> empty</methodname> ()</code></simpara></postconditions>
<throws><simpara> Will not throw.</simpara></throws>
</constructor>
<constructor>
<parameter name= "f" >
<paramtype> const <classname> functionN</classname> & </paramtype>
</parameter>
<postconditions><simpara> Contains a copy of the <code> f</code> 's target, if it has one, or is empty if <code> f.<methodname> empty</methodname> ()</code> .</simpara></postconditions>
<throws><simpara> Will not throw unless copying the target of <code> f</code> throws.</simpara></throws>
</constructor>
<constructor>
<template>
<template-type-parameter name= "F" />
</template>
<parameter name= "f" ><paramtype> F</paramtype></parameter>
<requires><simpara> F is a function object Callable from <code> this</code> .</simpara></requires>
<postconditions><simpara><code> *this</code> targets a copy of <code> f</code> if <code> f</code> is nonempty, or <code> this-> <methodname> empty</methodname> ()</code> if <code> f</code> is empty.</simpara></postconditions>
<throws><simpara> Will not throw when <code> f</code> is a stateless function object.</simpara></throws>
</constructor>
<destructor>
<effects><simpara> If <code> !this-><methodname> empty</methodname> ()</code> , destroys the target of this.</simpara></effects>
</destructor>
<copy-assignment>
<parameter name= "f" >
<paramtype> const <classname> functionN</classname> & </paramtype>
</parameter>
<postconditions><simpara><code> *this</code> targets a copy of <code> f</code> 's target, if it has one, or is empty if <code> f.<methodname> empty</methodname> ()</code> .</simpara></postconditions>
<throws><simpara> Will not throw when the target of <code> f</code> is a stateless function object or a reference to the function object.</simpara></throws>
</copy-assignment>
2003-03-15 23:12:35 +00:00
<method-group name= "modifiers" >
<method name= "swap" >
<type> void</type>
2003-03-12 23:27:25 +00:00
<parameter name= "f" ><paramtype> const <classname> functionN</classname> & </paramtype></parameter>
<effects><simpara> Interchanges the targets of <code> *this</code> and <code> f</code> .</simpara></effects>
<throws><simpara> Will not throw.</simpara></throws>
</method>
2003-03-15 23:12:35 +00:00
<method name= "clear" >
<type> void</type>
2003-03-12 23:27:25 +00:00
<postconditions><simpara> this-> <methodname> empty</methodname> ()</simpara></postconditions>
<throws><simpara> Will not throw.</simpara></throws>
</method>
2003-03-15 23:12:35 +00:00
</method-group>
2003-03-12 23:27:25 +00:00
2003-03-15 23:12:35 +00:00
<method-group name= "capacity" >
2003-03-12 23:27:25 +00:00
<method name= "empty" cv= "const" >
<type> bool</type>
<returns><simpara><code> true</code> if <code> this</code> has a target, and <code> false</code> otherwise.</simpara></returns>
<throws><simpara> Will not throw.</simpara></throws>
</method>
2003-03-15 23:12:35 +00:00
<method name= "conversion-operator" cv= "const" >
<type> safe_bool</type>
2003-03-12 23:27:25 +00:00
<returns><simpara> A <code> safe_bool</code> that evaluates <code> false</code> in a boolean context when <code> this-> <methodname> empty</methodname> ()</code> , and <code> true</code> otherwise.</simpara></returns>
<throws><simpara> Will not throw.</simpara></throws>
</method>
2003-03-15 23:12:35 +00:00
<method name= "operator!" cv= "const" >
<type> bool</type>
2003-03-12 23:27:25 +00:00
<returns><simpara><code> this-> <methodname> empty</methodname> ()</code></simpara></returns>
<throws><simpara> Will not throw.</simpara></throws>
</method>
2003-03-15 23:12:35 +00:00
</method-group>
2003-03-12 23:27:25 +00:00
2004-01-25 00:38:26 +00:00
<method-group name= "target access" >
<overloaded-method name= "target" >
<signature>
<template>
<template-type-parameter name= "Functor" />
</template>
<type> Functor*</type>
</signature>
<signature cv= "const" >
<template>
<template-type-parameter name= "Functor" />
</template>
<type> const Functor*</type>
</signature>
<returns><simpara> If <code> this</code> stores a target of type
<code> Functor</code> , returns the address of the
target. Otherwise, returns the NULL
pointer.</simpara></returns>
<throws><simpara> Will not throw.</simpara></throws>
</overloaded-method>
</method-group>
2003-03-15 23:12:35 +00:00
<method-group name= "invocation" >
<method name= "operator()" cv= "const" >
<type> result_type</type>
2003-03-12 23:27:25 +00:00
<parameter name= "a1" ><paramtype> arg1_type</paramtype></parameter>
<parameter name= "a2" ><paramtype> arg2_type</paramtype></parameter>
<parameter><paramtype> ...</paramtype></parameter>
<parameter name= "aN" ><paramtype> argN_type</paramtype></parameter>
<effects><simpara><code> f(a1, a2, ..., aN)</code> , where <code> f</code> is the target of <code> *this</code> .</simpara></effects>
<returns><simpara> if <code> R</code> is <code> void</code> , nothing is returned; otherwise, the return value of the call to <code> f</code> is returned.</simpara></returns>
<throws><simpara><code><classname> bad_function_call</classname></code> if <code> !this-> <methodname> empty</methodname> ()</code> . Otherwise, may through any exception thrown by the target function <code> f</code> .</simpara></throws>
</method>
2003-03-15 23:12:35 +00:00
</method-group>
2003-03-12 23:27:25 +00:00
<free-function-group name= "specialized algorithms" >
2003-03-15 23:12:35 +00:00
<function name= "swap" >
2003-03-12 23:27:25 +00:00
<template>
<template-type-parameter name= "T1" />
<template-type-parameter name= "T2" />
<template-varargs/>
<template-type-parameter name= "TN" />
<template-type-parameter name= "Allocator" />
</template>
2003-03-15 23:12:35 +00:00
<type> void</type>
2003-03-12 23:27:25 +00:00
<parameter name= "f1" ><paramtype><classname> functionN</classname> < T1, T2, ..., TN, Allocator>& </paramtype></parameter>
<parameter name= "f2" ><paramtype><classname> functionN</classname> < T1, T2, ..., TN, Allocator>& </paramtype></parameter>
<effects><simpara><code> f1.<methodname> swap</methodname> (f2)</code></simpara></effects>
<throws><simpara> Will not throw.</simpara></throws>
</function>
</free-function-group>
2004-01-25 00:38:26 +00:00
<free-function-group name= "comparison operators" >
<overloaded-function name= "operator==" >
<signature>
<template>
<template-type-parameter name= "T1" />
<template-type-parameter name= "T2" />
<template-varargs/>
<template-type-parameter name= "TN" />
<template-type-parameter name= "Allocator" />
<template-type-parameter name= "Functor" />
</template>
<type> bool</type>
<parameter name= "f" ><paramtype> const <classname> functionN</classname> < T1, T2, ..., TN, Allocator>& </paramtype></parameter>
<parameter name= "g" ><paramtype> Functor</paramtype></parameter>
</signature>
<signature>
<template>
<template-type-parameter name= "T1" />
<template-type-parameter name= "T2" />
<template-varargs/>
<template-type-parameter name= "TN" />
<template-type-parameter name= "Allocator" />
<template-type-parameter name= "Functor" />
</template>
<type> bool</type>
<parameter name= "g" ><paramtype> Functor</paramtype></parameter>
<parameter name= "f" ><paramtype> const <classname> functionN</classname> < T1, T2, ..., TN, Allocator>& </paramtype></parameter>
</signature>
<signature>
<template>
<template-type-parameter name= "T1" />
<template-type-parameter name= "T2" />
<template-varargs/>
<template-type-parameter name= "TN" />
<template-type-parameter name= "Allocator" />
<template-type-parameter name= "Functor" />
</template>
<type> bool</type>
<parameter name= "f" ><paramtype> const <classname> functionN</classname> < T1, T2, ..., TN, Allocator>& </paramtype></parameter>
<parameter name= "g" ><paramtype><classname> reference_wrapper</classname> < Functor> </paramtype></parameter>
</signature>
<signature>
<template>
<template-type-parameter name= "T1" />
<template-type-parameter name= "T2" />
<template-varargs/>
<template-type-parameter name= "TN" />
<template-type-parameter name= "Allocator" />
<template-type-parameter name= "Functor" />
</template>
<type> bool</type>
<parameter name= "g" ><paramtype><classname> reference_wrapper</classname> < Functor> </paramtype></parameter>
<parameter name= "f" ><paramtype> const <classname> functionN</classname> < T1, T2, ..., TN, Allocator>& </paramtype></parameter>
</signature>
<signature>
<template>
<template-type-parameter name= "T1" />
<template-type-parameter name= "T2" />
<template-varargs/>
<template-type-parameter name= "TN" />
<template-type-parameter name= "Allocator1" />
<template-type-parameter name= "U1" />
<template-type-parameter name= "U2" />
<template-varargs/>
<template-type-parameter name= "UN" />
<template-type-parameter name= "Allocator2" />
</template>
<type> void</type>
<parameter name= "f1" ><paramtype> const <classname> functionN</classname> < T1, T2, ..., TN, Allocator1>& </paramtype></parameter>
<parameter name= "f2" ><paramtype> const <classname> functionN</classname> < U1, U2, ..., UN, Allocator2>& </paramtype></parameter>
</signature>
2003-03-12 23:27:25 +00:00
2004-01-25 00:38:26 +00:00
<returns><simpara> True when <code> f</code> stores an object of
type <code> Functor</code> and one of the following conditions applies:
<itemizedlist>
<listitem><simpara><code> g</code> is of type
<code><classname> reference_wrapper</classname> < Functor> </code>
and <code> f.target< Functor> () == g.<methodname
alt= "reference_wrapper::get_pointer" > get_pointer</methodname> ()</code> .</simpara></listitem>
<listitem><simpara><code> g</code> is not of type
<code><classname> reference_wrapper</classname> < Functor> </code>
and <code> *(f.target< Functor> ()) ==
g</code> .</simpara></listitem>
</itemizedlist>
</simpara></returns>
<notes><simpara><code><classname> functionN</classname></code>
objects are not
<conceptname> EqualityComparable</conceptname> .</simpara></notes>
<rationale><simpara> The <code> safe_bool</code> conversion
opens a loophole whereby two <code> functionN</code>
instances can be compared via <code> ==</code> , although this
is not feasible to implement. The undefined <code> void
operator==</code> closes the loophole and ensures a
compile-time or link-time error.</simpara></rationale>
</overloaded-function>
<overloaded-function name= "operator!=" >
<signature>
<template>
<template-type-parameter name= "T1" />
<template-type-parameter name= "T2" />
<template-varargs/>
<template-type-parameter name= "TN" />
<template-type-parameter name= "Allocator" />
<template-type-parameter name= "Functor" />
</template>
<type> bool</type>
<parameter name= "f" ><paramtype> const <classname> functionN</classname> < T1, T2, ..., TN, Allocator>& </paramtype></parameter>
<parameter name= "g" ><paramtype> Functor</paramtype></parameter>
</signature>
<signature>
<template>
<template-type-parameter name= "T1" />
<template-type-parameter name= "T2" />
<template-varargs/>
<template-type-parameter name= "TN" />
<template-type-parameter name= "Allocator" />
<template-type-parameter name= "Functor" />
</template>
<type> bool</type>
<parameter name= "g" ><paramtype> Functor</paramtype></parameter>
<parameter name= "f" ><paramtype> const <classname> functionN</classname> < T1, T2, ..., TN, Allocator>& </paramtype></parameter>
</signature>
<signature>
<template>
<template-type-parameter name= "T1" />
<template-type-parameter name= "T2" />
<template-varargs/>
<template-type-parameter name= "TN" />
<template-type-parameter name= "Allocator" />
<template-type-parameter name= "Functor" />
</template>
<type> bool</type>
<parameter name= "f" ><paramtype> const <classname> functionN</classname> < T1, T2, ..., TN, Allocator>& </paramtype></parameter>
<parameter name= "g" ><paramtype><classname> reference_wrapper</classname> < Functor> </paramtype></parameter>
</signature>
<signature>
<template>
<template-type-parameter name= "T1" />
<template-type-parameter name= "T2" />
<template-varargs/>
<template-type-parameter name= "TN" />
<template-type-parameter name= "Allocator" />
<template-type-parameter name= "Functor" />
</template>
<type> bool</type>
<parameter name= "g" ><paramtype><classname> reference_wrapper</classname> < Functor> </paramtype></parameter>
<parameter name= "f" ><paramtype> const <classname> functionN</classname> < T1, T2, ..., TN, Allocator>& </paramtype></parameter>
</signature>
<signature>
<template>
<template-type-parameter name= "T1" />
<template-type-parameter name= "T2" />
<template-varargs/>
<template-type-parameter name= "TN" />
<template-type-parameter name= "Allocator1" />
<template-type-parameter name= "U1" />
<template-type-parameter name= "U2" />
<template-varargs/>
<template-type-parameter name= "UN" />
<template-type-parameter name= "Allocator2" />
</template>
<type> void</type>
<parameter name= "f1" ><paramtype> const <classname> functionN</classname> < T1, T2, ..., TN, Allocator1>& </paramtype></parameter>
<parameter name= "f2" ><paramtype> const <classname> functionN</classname> < U1, U2, ..., UN, Allocator2>& </paramtype></parameter>
</signature>
<returns><simpara> True when <code> f</code> does not store an
object of type <code> Functor</code> or it stores an object of
type <code> Functor</code> and one of the following conditions
applies:
<itemizedlist>
<listitem><simpara><code> g</code> is of type
<code><classname> reference_wrapper</classname> < Functor> </code>
and <code> f.target< Functor> () != g.<methodname
alt= "reference_wrapper::get_pointer" > get_pointer</methodname> ()</code> .</simpara></listitem>
<listitem><simpara><code> g</code> is not of type
<code><classname> reference_wrapper</classname> < Functor> </code>
and <code> *(f.target< Functor> ()) !=
g</code> .</simpara></listitem>
</itemizedlist>
</simpara></returns>
<notes><simpara><code><classname> functionN</classname></code>
objects are not
<conceptname> EqualityComparable</conceptname> .</simpara></notes>
<rationale><simpara> The <code> safe_bool</code> conversion
opens a loophole whereby two <code> functionN</code>
instances can be compared via <code> !=</code> , although this
is not feasible to implement. The undefined <code> void
operator!=</code> closes the loophole and ensures a
compile-time or link-time error.</simpara></rationale>
</overloaded-function>
2003-03-12 23:27:25 +00:00
</free-function-group>
</class>
<class name= "function" >
<template>
2003-03-15 23:12:35 +00:00
<template-type-parameter name= "Signature" >
<purpose> Function type R (T1, T2, ..., TN)</purpose>
</template-type-parameter>
2003-03-13 00:08:34 +00:00
<template-type-parameter name= "Allocator" >
<default><classname> std::allocator</classname> < void> </default>
</template-type-parameter>
2003-03-12 23:27:25 +00:00
</template>
<inherit access= "public" ><classname> functionN</classname> < R, T1, T2, ..., TN, Allocator> </inherit>
<purpose> A generalized function pointer that can be used for
callbacks or wrapping function objects.</purpose>
2003-03-13 00:08:34 +00:00
<description>
<para> Class template <classname> function</classname> is a thin
wrapper around the numbered class templates <classname
2003-03-12 23:27:25 +00:00
alt= "functionN" > function0</classname> , <classname
alt= "functionN" > function1</classname> , etc. It accepts a
function type with N arguments and will will derive from
2003-03-13 00:08:34 +00:00
<classname> functionN</classname> instantiated with the arguments
it receives.</para>
2003-03-12 23:27:25 +00:00
2003-03-13 00:08:34 +00:00
<para> The semantics of all operations in class template
<classname> function</classname> are equivalent to that of the
underlying <classname> functionN</classname> object, although
additional member functions are required to allow proper copy
construction and copy assignment of function objects.</para>
</description>
2003-03-12 23:27:25 +00:00
<typedef name= "result_type" ><type> R</type></typedef>
<typedef name= "allocator_type" ><type> Allocator</type></typedef>
<typedef name= "argument_type" >
<type> T1</type><purpose> If N == 1</purpose>
</typedef>
<typedef name= "first_argument_type" >
<type> T1</type>
<purpose> If N == 2</purpose>
</typedef>
<typedef name= "second_argument_type" >
<type> T2</type>
<purpose> If N == 2</purpose>
</typedef>
<typedef name= "arg1_type" ><type> T1</type></typedef>
<typedef name= "arg2_type" ><type> T2</type></typedef>
2003-03-15 23:12:35 +00:00
<typedef name= "..." ><type/></typedef>
2003-03-12 23:27:25 +00:00
<typedef name= "argN_type" ><type> TN</type></typedef>
2003-03-13 00:29:57 +00:00
<static-constant name= "arity" >
<type> int</type>
<default> N</default>
</static-constant>
2003-03-12 23:27:25 +00:00
2003-03-16 02:00:20 +00:00
<struct name= "sig" >
<template>
<template-type-parameter name= "Args" />
</template>
<purpose>
<simpara><libraryname> Lambda</libraryname> library support</simpara>
</purpose>
<typedef name= "type" ><type> result_type</type></typedef>
</struct>
2003-03-12 23:27:25 +00:00
<constructor>
<postconditions><simpara><code> this-><methodname> empty</methodname> ()</code></simpara></postconditions>
<throws><simpara> Will not throw.</simpara></throws>
</constructor>
<constructor>
<parameter name= "f" >
<paramtype> const <classname> functionN</classname> & </paramtype>
</parameter>
<postconditions><simpara> Contains a copy of the <code> f</code> 's target, if it has one, or is empty if <code> f.<methodname> empty</methodname> ()</code> .</simpara></postconditions>
<throws><simpara> Will not throw unless copying the target of <code> f</code> throws.</simpara></throws>
</constructor>
<constructor>
<parameter name= "f" >
<paramtype> const <classname> function</classname> & </paramtype>
</parameter>
<postconditions><simpara> Contains a copy of the <code> f</code> 's target, if it has one, or is empty if <code> f.<methodname> empty</methodname> ()</code> .</simpara></postconditions>
<throws><simpara> Will not throw unless copying the target of <code> f</code> throws.</simpara></throws>
</constructor>
<constructor>
<template>
<template-type-parameter name= "F" />
</template>
<parameter name= "f" ><paramtype> F</paramtype></parameter>
<requires><simpara> F is a function object Callable from <code> this</code> .</simpara></requires>
<postconditions><simpara><code> *this</code> targets a copy of <code> f</code> if <code> f</code> is nonempty, or <code> this-> <methodname> empty</methodname> ()</code> if <code> f</code> is empty.</simpara></postconditions>
<throws><simpara> Will not throw when <code> f</code> is a stateless function object.</simpara></throws>
</constructor>
<destructor>
<effects><simpara> If <code> !this-><methodname> empty</methodname> ()</code> , destroys the target of <code> this</code> .</simpara></effects>
</destructor>
<copy-assignment>
<parameter name= "f" >
<paramtype> const <classname> functionN</classname> & </paramtype>
</parameter>
<postconditions><simpara><code> *this</code> targets a copy of <code> f</code> 's target, if it has one, or is empty if <code> f.<methodname> empty</methodname> ()</code></simpara></postconditions>
<throws><simpara> Will not throw when the target of <code> f</code> is a stateless function object or a reference to the function object.</simpara></throws>
</copy-assignment>
<copy-assignment>
<parameter name= "f" >
<paramtype> const <classname> function</classname> & </paramtype>
</parameter>
<postconditions><simpara><code> *this</code> targets a copy of <code> f</code> 's target, if it has one, or is empty if <code> f.<methodname> empty</methodname> ()</code></simpara></postconditions>
<throws><simpara> Will not throw when the target of <code> f</code> is a stateless function object or a reference to the function object.</simpara></throws>
</copy-assignment>
2003-03-15 23:12:35 +00:00
<method-group name= "modifiers" >
<method name= "swap" >
<type> void</type>
2003-03-12 23:27:25 +00:00
<parameter name= "f" ><paramtype> const <classname> function</classname> & </paramtype></parameter>
<effects><simpara> Interchanges the targets of <code> *this</code> and <code> f</code> .</simpara></effects>
<throws><simpara> Will not throw.</simpara></throws>
</method>
2003-03-15 23:12:35 +00:00
<method name= "clear" >
<type> void</type>
2003-03-12 23:27:25 +00:00
<postconditions><simpara><code> this-> <methodname> empty</methodname> ()</code></simpara></postconditions>
<throws><simpara> Will not throw.</simpara></throws>
</method>
2003-03-15 23:12:35 +00:00
</method-group>
2003-03-12 23:27:25 +00:00
2003-03-15 23:12:35 +00:00
<method-group name= "capacity" >
<method name= "empty" cv= "const" >
<type> bool</type>
2003-03-12 23:27:25 +00:00
<returns><simpara><code> true</code> if <code> this</code> has a target, and <code> false</code> otherwise.</simpara></returns>
<throws><simpara> Will not throw.</simpara></throws>
</method>
2003-03-15 23:12:35 +00:00
<method name= "conversion-operator" cv= "const" >
<type> safe_bool</type>
2003-03-12 23:27:25 +00:00
<returns><simpara> A <code> safe_bool</code> that evaluates <code> false</code> in a boolean context when <code> this-> <methodname> empty</methodname> ()</code> , and <code> true</code> otherwise.</simpara></returns>
<throws><simpara> Will not throw.</simpara></throws>
</method>
2003-03-15 23:12:35 +00:00
<method name= "operator!" cv= "const" >
<type> bool</type>
2003-03-12 23:27:25 +00:00
<returns><simpara><code> this-> <methodname> empty</methodname> ()</code></simpara></returns>
<throws><simpara> Will not throw.</simpara></throws>
</method>
2003-03-15 23:12:35 +00:00
</method-group>
2003-03-12 23:27:25 +00:00
2004-01-25 00:38:26 +00:00
<method-group name= "target access" >
<overloaded-method name= "target" >
<signature>
<template>
<template-type-parameter name= "Functor" />
</template>
<type> Functor*</type>
</signature>
<signature cv= "const" >
<template>
<template-type-parameter name= "Functor" />
</template>
<type> const Functor*</type>
</signature>
<returns><simpara> If <code> this</code> stores a target of type
<code> Functor</code> , returns the address of the
target. Otherwise, returns the NULL
pointer.</simpara></returns>
<throws><simpara> Will not throw.</simpara></throws>
</overloaded-method>
</method-group>
2003-03-15 23:12:35 +00:00
<method-group name= "invocation" >
<method name= "operator()" cv= "const" >
<type> result_type</type>
2003-03-12 23:27:25 +00:00
<parameter name= "a1" ><paramtype> arg1_type</paramtype></parameter>
<parameter name= "a2" ><paramtype> arg2_type</paramtype></parameter>
<parameter><paramtype> ...</paramtype></parameter>
<parameter name= "aN" ><paramtype> argN_type</paramtype></parameter>
<effects><simpara><code> f(a1, a2, ..., aN)</code> , where <code> f</code> is the target of <code> *this</code> .</simpara></effects>
<returns><simpara> if <code> R</code> is <code> void</code> , nothing is returned; otherwise, the return value of the call to <code> f</code> is returned.</simpara></returns>
<throws><simpara><code><classname> bad_function_call</classname></code> if <code> !this-> <methodname> empty</methodname> ()</code> . Otherwise, may through any exception thrown by the target function <code> f</code> .</simpara></throws>
</method>
2003-03-15 23:12:35 +00:00
</method-group>
2003-03-12 23:27:25 +00:00
<free-function-group name= "specialized algorithms" >
2003-03-15 23:12:35 +00:00
<function name= "swap" >
2003-03-12 23:27:25 +00:00
<template>
<template-type-parameter name= "Signature" />
<template-type-parameter name= "Allocator" />
</template>
2003-03-15 23:12:35 +00:00
<type> void</type>
2003-03-12 23:27:25 +00:00
<parameter name= "f1" ><paramtype><classname> function</classname> < Signature, Allocator>& </paramtype></parameter>
<parameter name= "f2" ><paramtype><classname> function</classname> < Signature, Allocator>& </paramtype></parameter>
<effects><simpara><code> f1.<methodname> swap</methodname> (f2)</code></simpara></effects>
<throws><simpara> Will not throw.</simpara></throws>
</function>
</free-function-group>
2004-01-25 00:38:26 +00:00
<free-function-group name= "comparison operators" >
<overloaded-function name= "operator==" >
<signature>
<template>
<template-type-parameter name= "Signature" />
<template-type-parameter name= "Allocator" />
<template-type-parameter name= "Functor" />
</template>
<type> bool</type>
<parameter name= "f" ><paramtype> const <classname> function</classname> < Signature, Allocator>& </paramtype></parameter>
<parameter name= "g" ><paramtype> Functor</paramtype></parameter>
</signature>
<signature>
<template>
<template-type-parameter name= "Signature" />
<template-type-parameter name= "Allocator" />
<template-type-parameter name= "Functor" />
</template>
<type> bool</type>
<parameter name= "g" ><paramtype> Functor</paramtype></parameter>
<parameter name= "f" ><paramtype> const <classname> function</classname> < Signature, Allocator>& </paramtype></parameter>
</signature>
<signature>
<template>
<template-type-parameter name= "Signature" />
<template-type-parameter name= "Allocator" />
<template-type-parameter name= "Functor" />
</template>
<type> bool</type>
<parameter name= "f" ><paramtype> const <classname> function</classname> < Signature, Allocator>& </paramtype></parameter>
<parameter name= "g" ><paramtype><classname> reference_wrapper</classname> < Functor> </paramtype></parameter>
</signature>
<signature>
<template>
<template-type-parameter name= "Signature" />
<template-type-parameter name= "Allocator" />
<template-type-parameter name= "Functor" />
</template>
<type> bool</type>
<parameter name= "g" ><paramtype><classname> reference_wrapper</classname> < Functor> </paramtype></parameter>
<parameter name= "f" ><paramtype> const <classname> function</classname> < Signature, Allocator>& </paramtype></parameter>
</signature>
<signature>
<template>
<template-type-parameter name= "Signature1" />
<template-type-parameter name= "Allocator1" />
<template-type-parameter name= "Signature2" />
<template-type-parameter name= "Allocator2" />
</template>
<type> void</type>
<parameter name= "f1" ><paramtype> const <classname> function</classname> < Signature1, Allocator1>& </paramtype></parameter>
<parameter name= "f2" ><paramtype> const <classname> function</classname> < Signature2, Allocator2>& </paramtype></parameter>
</signature>
2003-03-12 23:27:25 +00:00
2004-01-25 00:38:26 +00:00
<returns><simpara> True when <code> f</code> stores an object of
type <code> Functor</code> and one of the following conditions applies:
<itemizedlist>
<listitem><simpara><code> g</code> is of type
<code><classname> reference_wrapper</classname> < Functor> </code>
and <code> f.target< Functor> () == g.<methodname
alt= "reference_wrapper::get_pointer" > get_pointer</methodname> ()</code> .</simpara></listitem>
<listitem><simpara><code> g</code> is not of type
<code><classname> reference_wrapper</classname> < Functor> </code>
and <code> *(f.target< Functor> ()) ==
g</code> .</simpara></listitem>
</itemizedlist>
</simpara></returns>
<notes><simpara><code><classname> function</classname></code>
objects are not
<conceptname> EqualityComparable</conceptname> .</simpara></notes>
<rationale><simpara> The <code> safe_bool</code> conversion
opens a loophole whereby two <code> function</code>
instances can be compared via <code> ==</code> , although this
is not feasible to implement. The undefined <code> void
operator==</code> closes the loophole and ensures a
compile-time or link-time error.</simpara></rationale>
</overloaded-function>
<overloaded-function name= "operator!=" >
<signature>
<template>
<template-type-parameter name= "Signature" />
<template-type-parameter name= "Allocator" />
<template-type-parameter name= "Functor" />
</template>
<type> bool</type>
<parameter name= "f" ><paramtype> const <classname> function</classname> < Signature, Allocator>& </paramtype></parameter>
<parameter name= "g" ><paramtype> Functor</paramtype></parameter>
</signature>
<signature>
<template>
<template-type-parameter name= "Signature" />
<template-type-parameter name= "Allocator" />
<template-type-parameter name= "Functor" />
</template>
<type> bool</type>
<parameter name= "g" ><paramtype> Functor</paramtype></parameter>
<parameter name= "f" ><paramtype> const <classname> function</classname> < Signature, Allocator>& </paramtype></parameter>
</signature>
<signature>
<template>
<template-type-parameter name= "Signature" />
<template-type-parameter name= "Allocator" />
<template-type-parameter name= "Functor" />
</template>
<type> bool</type>
<parameter name= "f" ><paramtype> const <classname> function</classname> < Signature, Allocator>& </paramtype></parameter>
<parameter name= "g" ><paramtype><classname> reference_wrapper</classname> < Functor> </paramtype></parameter>
</signature>
<signature>
<template>
<template-type-parameter name= "Signature" />
<template-type-parameter name= "Allocator" />
<template-type-parameter name= "Functor" />
</template>
<type> bool</type>
<parameter name= "g" ><paramtype><classname> reference_wrapper</classname> < Functor> </paramtype></parameter>
<parameter name= "f" ><paramtype> const <classname> function</classname> < Signature, Allocator>& </paramtype></parameter>
</signature>
<signature>
<template>
<template-type-parameter name= "Signature1" />
<template-type-parameter name= "Allocator1" />
<template-type-parameter name= "Signature2" />
<template-type-parameter name= "Allocator2" />
</template>
<type> void</type>
<parameter name= "f1" ><paramtype> const <classname> function</classname> < Signature1, Allocator1>& </paramtype></parameter>
<parameter name= "f2" ><paramtype> const <classname> function</classname> < Signature2, Allocator2>& </paramtype></parameter>
</signature>
<returns><simpara> True when <code> f</code> does not store an
object of type <code> Functor</code> or it stores an object of
type <code> Functor</code> and one of the following conditions
applies:
<itemizedlist>
<listitem><simpara><code> g</code> is of type
<code><classname> reference_wrapper</classname> < Functor> </code>
and <code> f.target< Functor> () != g.<methodname
alt= "reference_wrapper::get_pointer" > get_pointer</methodname> ()</code> .</simpara></listitem>
<listitem><simpara><code> g</code> is not of type
<code><classname> reference_wrapper</classname> < Functor> </code>
and <code> *(f.target< Functor> ()) !=
g</code> .</simpara></listitem>
</itemizedlist>
</simpara></returns>
<notes><simpara><code><classname> function</classname></code>
objects are not
<conceptname> EqualityComparable</conceptname> .</simpara></notes>
<rationale><simpara> The <code> safe_bool</code> conversion
opens a loophole whereby two <code> function</code>
instances can be compared via <code> !=</code> , although this
is not feasible to implement. The undefined <code> void
operator!=</code> closes the loophole and ensures a
compile-time or link-time error.</simpara></rationale>
</overloaded-function>
2003-03-12 23:27:25 +00:00
</free-function-group>
</class>
</namespace>
</header>
</library-reference>
