2003-03-12 23:27:25 +00:00
<?xml version="1.0" encoding="utf-8"?>
2007-11-05 21:22:29 +00:00
<!--
Copyright (c) 2002 Douglas Gregor <doug.gregor - a t - g m a i l . c o m >
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)
-->
2003-03-12 23:27:25 +00:00
< !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>
2004-02-08 00:11:22 +00:00
<returns > <simpara > <code > false</code> if <code > this</code> has a target, and <code > true</code> otherwise.</simpara> </returns>
2003-03-12 23:27:25 +00:00
<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>
2004-03-12 03:38:20 +00:00
<method name= "contains" cv= "const" >
<template >
<template-type-parameter name= "Functor" />
</template>
<type > bool</type>
<parameter name= "f" >
<paramtype > const Functor& </paramtype>
</parameter>
<returns > <simpara > <code > true</code> if <code > this-> <methodname > target</methodname> < Functor> ()</code> is non-NULL and <code > <functionname > function_equal</functionname> (*(this-> target< Functor> ()), f)</code> </simpara> </returns>
</method>
2006-01-10 23:52:35 +00:00
<method name= "target_type" cv= "const" >
<type > const std::type_info& </type>
<returns > <simpara > <code > typeid</code> of the target function object, or <code > typeid(void)</code> if <code > this-> <methodname > empty</methodname> ()</code> .</simpara> </returns>
<throws > <simpara > Will not throw.</simpara> </throws>
</method>
2004-01-25 00:38:26 +00:00
</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>
<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= "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 >
2006-01-10 23:52:35 +00:00
<postconditions > <simpara > <code > this-> <methodname > empty</methodname> ()</code> </simpara> </postconditions>
2003-03-12 23:27:25 +00:00
<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>
</constructor>
2008-03-27 19:44:37 +00:00
<constructor >
<template >
<template-type-parameter name= "F" />
<template-type-parameter name= "Allocator" />
</template>
<parameter name= "f" > <paramtype > F</paramtype> </parameter>
<parameter name= "alloc" > <paramtype > Allocator</paramtype> </parameter>
<requires > <simpara > F is a function object Callable from <code > this</code> , Allocator is an allocator. The copy constructor and destructor of Allocator shall not throw.</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>
<effects > <simpara > If memory allocation is required, the given allocator (or a copy of it) will be used to allocate that memory.</simpara> </effects>
</constructor>
2003-03-12 23:27:25 +00:00
<destructor >
2006-01-10 23:52:35 +00:00
<effects > <simpara > If <code > !this-> <methodname > empty</methodname> ()</code> , destroys the target of this.</simpara> </effects>
2003-03-12 23:27:25 +00:00
</destructor>
<copy-assignment >
<parameter name= "f" >
<paramtype > const <classname > functionN</classname> & </paramtype>
</parameter>
2006-01-10 23:52:35 +00:00
<postconditions > <simpara > If copy construction does not throw, <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> . If copy construction does throw, <code > this-> <methodname > empty</methodname> ()</code> .</simpara> </postconditions>
2003-03-12 23:27:25 +00:00
</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>
</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>
</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>
2004-02-08 00:11:22 +00:00
<returns > <simpara > <code > false</code> if <code > this</code> has a target, and <code > true</code> otherwise.</simpara> </returns>
2003-03-12 23:27:25 +00:00
<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>
2004-03-12 03:38:20 +00:00
<method name= "contains" cv= "const" >
<template >
<template-type-parameter name= "Functor" />
</template>
<type > bool</type>
<parameter name= "f" >
<paramtype > const Functor& </paramtype>
</parameter>
<returns > <simpara > <code > true</code> if <code > this-> <methodname > target</methodname> < Functor> ()</code> is non-NULL and <code > <functionname > function_equal</functionname> (*(this-> target< Functor> ()), f)</code> </simpara> </returns>
</method>
2006-01-10 23:52:35 +00:00
<method name= "target_type" cv= "const" >
<type > const std::type_info& </type>
<returns > <simpara > <code > typeid</code> of the target function object, or <code > typeid(void)</code> if <code > this-> <methodname > empty</methodname> ()</code> .</simpara> </returns>
<throws > <simpara > Will not throw.</simpara> </throws>
</method>
2004-01-25 00:38:26 +00:00
</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>
2005-12-08 03:23:02 +00:00
<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>
2003-03-12 23:27:25 +00:00
</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>
2003-03-15 23:12:35 +00:00
<type > void</type>
2008-03-27 19:44:37 +00:00
<parameter name= "f1" > <paramtype > <classname > functionN</classname> < T1, T2, ..., TN> & </paramtype> </parameter>
<parameter name= "f2" > <paramtype > <classname > functionN</classname> < T1, T2, ..., TN> & </paramtype> </parameter>
2003-03-12 23:27:25 +00:00
<effects > <simpara > <code > f1.<methodname > swap</methodname> (f2)</code> </simpara> </effects>
</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= "Functor" />
</template>
<type > bool</type>
2008-03-27 19:44:37 +00:00
<parameter name= "f" > <paramtype > const <classname > functionN</classname> < T1, T2, ..., TN> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
<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= "Functor" />
</template>
<type > bool</type>
<parameter name= "g" > <paramtype > Functor</paramtype> </parameter>
2008-03-27 19:44:37 +00:00
<parameter name= "f" > <paramtype > const <classname > functionN</classname> < T1, T2, ..., TN> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
</signature>
<signature >
<template >
<template-type-parameter name= "T1" />
<template-type-parameter name= "T2" />
<template-varargs />
<template-type-parameter name= "TN" />
<template-type-parameter name= "Functor" />
</template>
<type > bool</type>
2008-03-27 19:44:37 +00:00
<parameter name= "f" > <paramtype > const <classname > functionN</classname> < T1, T2, ..., TN> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
<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= "Functor" />
</template>
<type > bool</type>
<parameter name= "g" > <paramtype > <classname > reference_wrapper</classname> < Functor> </paramtype> </parameter>
2008-03-27 19:44:37 +00:00
<parameter name= "f" > <paramtype > const <classname > functionN</classname> < T1, T2, ..., TN> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
</signature>
<signature >
<template >
<template-type-parameter name= "T1" />
<template-type-parameter name= "T2" />
<template-varargs />
<template-type-parameter name= "TN" />
<template-type-parameter name= "U1" />
<template-type-parameter name= "U2" />
<template-varargs />
<template-type-parameter name= "UN" />
</template>
<type > void</type>
2008-03-27 19:44:37 +00:00
<parameter name= "f1" > <paramtype > const <classname > functionN</classname> < T1, T2, ..., TN> & </paramtype> </parameter>
<parameter name= "f2" > <paramtype > const <classname > functionN</classname> < U1, U2, ..., UN> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
</signature>
<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>
2004-03-12 03:38:20 +00:00
and
<code > <functionname > function_equal</functionname> (*(f.target< Functor> ()),
g)</code> .</simpara> </listitem>
2004-01-25 00:38:26 +00:00
</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= "Functor" />
</template>
<type > bool</type>
2008-03-27 19:44:37 +00:00
<parameter name= "f" > <paramtype > const <classname > functionN</classname> < T1, T2, ..., TN> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
<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= "Functor" />
</template>
<type > bool</type>
<parameter name= "g" > <paramtype > Functor</paramtype> </parameter>
2008-03-27 19:44:37 +00:00
<parameter name= "f" > <paramtype > const <classname > functionN</classname> < T1, T2, ..., TN> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
</signature>
<signature >
<template >
<template-type-parameter name= "T1" />
<template-type-parameter name= "T2" />
<template-varargs />
<template-type-parameter name= "TN" />
<template-type-parameter name= "Functor" />
</template>
<type > bool</type>
2008-03-27 19:44:37 +00:00
<parameter name= "f" > <paramtype > const <classname > functionN</classname> < T1, T2, ..., TN> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
<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= "Functor" />
</template>
<type > bool</type>
<parameter name= "g" > <paramtype > <classname > reference_wrapper</classname> < Functor> </paramtype> </parameter>
2008-03-27 19:44:37 +00:00
<parameter name= "f" > <paramtype > const <classname > functionN</classname> < T1, T2, ..., TN> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
</signature>
<signature >
<template >
<template-type-parameter name= "T1" />
<template-type-parameter name= "T2" />
<template-varargs />
<template-type-parameter name= "TN" />
<template-type-parameter name= "U1" />
<template-type-parameter name= "U2" />
<template-varargs />
<template-type-parameter name= "UN" />
</template>
<type > void</type>
2008-03-27 19:44:37 +00:00
<parameter name= "f1" > <paramtype > const <classname > functionN</classname> < T1, T2, ..., TN> & </paramtype> </parameter>
<parameter name= "f2" > <paramtype > const <classname > functionN</classname> < U1, U2, ..., UN> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
</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>
2004-03-12 03:38:20 +00:00
and <code > !<functionname > function_equal</functionname> (*(f.target< Functor> ()), g)</code> .</simpara> </listitem>
2004-01-25 00:38:26 +00:00
</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-12 23:27:25 +00:00
</template>
2008-03-27 19:44:37 +00:00
<inherit access= "public" > <classname > functionN</classname> < R, T1, T2, ..., TN> </inherit>
2003-03-12 23:27:25 +00:00
<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>
<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= "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 >
2006-01-10 23:52:35 +00:00
<postconditions > <simpara > <code > this-> <methodname > empty</methodname> ()</code> </simpara> </postconditions>
2003-03-12 23:27:25 +00:00
<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>
</constructor>
2008-03-27 19:44:37 +00:00
<constructor >
<template >
<template-type-parameter name= "F" />
<template-type-parameter name= "Allocator" />
</template>
<parameter name= "f" > <paramtype > F</paramtype> </parameter>
<parameter name= "alloc" > <paramtype > Allocator</paramtype> </parameter>
<requires > <simpara > F is a function object Callable from <code > this</code> , Allocator is an allocator. The copy constructor and destructor of Allocator shall not throw.</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>
<effects > <simpara > If memory allocation is required, the given allocator (or a copy of it) will be used to allocate that memory.</simpara> </effects>
</constructor>
2003-03-12 23:27:25 +00:00
<destructor >
2006-01-10 23:52:35 +00:00
<effects > <simpara > If <code > !this-> <methodname > empty</methodname> ()</code> , destroys the target of <code > this</code> .</simpara> </effects>
2003-03-12 23:27:25 +00:00
</destructor>
<copy-assignment >
<parameter name= "f" >
2006-01-10 23:52:35 +00:00
<paramtype > const <classname > function</classname> & </paramtype>
2003-03-12 23:27:25 +00:00
</parameter>
2006-01-10 23:52:35 +00:00
<postconditions > <simpara > If copy construction does not throw, <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> . If copy construction does throw, <code > this-> <methodname > empty</methodname> ()</code> .</simpara> </postconditions>
2003-03-12 23:27:25 +00:00
</copy-assignment>
<copy-assignment >
<parameter name= "f" >
<paramtype > const <classname > function</classname> & </paramtype>
</parameter>
2006-01-10 23:52:35 +00:00
<postconditions > <simpara > If copy construction of the target of <code > f</code> does not throw, <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. If copy construction does throw, <code > this-> <methodname > empty</methodname> ()</code> .</simpara> </throws>
2003-03-12 23:27:25 +00:00
</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>
</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>
2004-02-08 00:11:22 +00:00
<returns > <simpara > <code > false</code> if <code > this</code> has a target, and <code > true</code> otherwise.</simpara> </returns>
2003-03-12 23:27:25 +00:00
<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>
2004-03-12 03:38:20 +00:00
<method name= "contains" cv= "const" >
<template >
<template-type-parameter name= "Functor" />
</template>
<type > bool</type>
<parameter name= "f" >
<paramtype > const Functor& </paramtype>
</parameter>
<returns > <simpara > <code > true</code> if <code > this-> <methodname > target</methodname> < Functor> ()</code> is non-NULL and <code > <functionname > function_equal</functionname> (*(this-> target< Functor> ()), f)</code> </simpara> </returns>
</method>
2006-01-10 23:52:35 +00:00
<method name= "target_type" cv= "const" >
<type > const std::type_info& </type>
<returns > <simpara > <code > typeid</code> of the target function object, or <code > typeid(void)</code> if <code > this-> <methodname > empty</methodname> ()</code> .</simpara> </returns>
<throws > <simpara > Will not throw.</simpara> </throws>
</method>
2004-01-25 00:38:26 +00:00
</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>
2005-12-08 03:23:02 +00:00
<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>
2003-03-12 23:27:25 +00:00
</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>
2003-03-15 23:12:35 +00:00
<type > void</type>
2008-03-27 19:44:37 +00:00
<parameter name= "f1" > <paramtype > <classname > function</classname> < Signature> & </paramtype> </parameter>
<parameter name= "f2" > <paramtype > <classname > function</classname> < Signature> & </paramtype> </parameter>
2003-03-12 23:27:25 +00:00
<effects > <simpara > <code > f1.<methodname > swap</methodname> (f2)</code> </simpara> </effects>
</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= "Functor" />
</template>
<type > bool</type>
2008-03-27 19:44:37 +00:00
<parameter name= "f" > <paramtype > const <classname > function</classname> < Signature> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
<parameter name= "g" > <paramtype > Functor</paramtype> </parameter>
</signature>
<signature >
<template >
<template-type-parameter name= "Signature" />
<template-type-parameter name= "Functor" />
</template>
<type > bool</type>
<parameter name= "g" > <paramtype > Functor</paramtype> </parameter>
2008-03-27 19:44:37 +00:00
<parameter name= "f" > <paramtype > const <classname > function</classname> < Signature> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
</signature>
<signature >
<template >
<template-type-parameter name= "Signature" />
<template-type-parameter name= "Functor" />
</template>
<type > bool</type>
2008-03-27 19:44:37 +00:00
<parameter name= "f" > <paramtype > const <classname > function</classname> < Signature> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
<parameter name= "g" > <paramtype > <classname > reference_wrapper</classname> < Functor> </paramtype> </parameter>
</signature>
<signature >
<template >
<template-type-parameter name= "Signature" />
<template-type-parameter name= "Functor" />
</template>
<type > bool</type>
<parameter name= "g" > <paramtype > <classname > reference_wrapper</classname> < Functor> </paramtype> </parameter>
2008-03-27 19:44:37 +00:00
<parameter name= "f" > <paramtype > const <classname > function</classname> < Signature> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
</signature>
<signature >
<template >
<template-type-parameter name= "Signature1" />
<template-type-parameter name= "Signature2" />
</template>
<type > void</type>
2008-03-27 19:44:37 +00:00
<parameter name= "f1" > <paramtype > const <classname > function</classname> < Signature1> & </paramtype> </parameter>
<parameter name= "f2" > <paramtype > const <classname > function</classname> < Signature2> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
</signature>
<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>
2004-03-12 03:38:20 +00:00
and <code > <functionname > function_equals</functionname> (*(f.target< Functor> ()), g)</code> .</simpara> </listitem>
2004-01-25 00:38:26 +00:00
</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= "Functor" />
</template>
<type > bool</type>
2008-03-27 19:44:37 +00:00
<parameter name= "f" > <paramtype > const <classname > function</classname> < Signature> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
<parameter name= "g" > <paramtype > Functor</paramtype> </parameter>
</signature>
<signature >
<template >
<template-type-parameter name= "Signature" />
<template-type-parameter name= "Functor" />
</template>
<type > bool</type>
<parameter name= "g" > <paramtype > Functor</paramtype> </parameter>
2008-03-27 19:44:37 +00:00
<parameter name= "f" > <paramtype > const <classname > function</classname> < Signature> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
</signature>
<signature >
<template >
<template-type-parameter name= "Signature" />
<template-type-parameter name= "Functor" />
</template>
<type > bool</type>
2008-03-27 19:44:37 +00:00
<parameter name= "f" > <paramtype > const <classname > function</classname> < Signature> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
<parameter name= "g" > <paramtype > <classname > reference_wrapper</classname> < Functor> </paramtype> </parameter>
</signature>
<signature >
<template >
<template-type-parameter name= "Signature" />
<template-type-parameter name= "Functor" />
</template>
<type > bool</type>
<parameter name= "g" > <paramtype > <classname > reference_wrapper</classname> < Functor> </paramtype> </parameter>
2008-03-27 19:44:37 +00:00
<parameter name= "f" > <paramtype > const <classname > function</classname> < Signature> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
</signature>
<signature >
<template >
<template-type-parameter name= "Signature1" />
<template-type-parameter name= "Signature2" />
</template>
<type > void</type>
2008-03-27 19:44:37 +00:00
<parameter name= "f1" > <paramtype > const <classname > function</classname> < Signature1> & </paramtype> </parameter>
<parameter name= "f2" > <paramtype > const <classname > function</classname> < Signature2> & </paramtype> </parameter>
2004-01-25 00:38:26 +00:00
</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>
2004-03-12 03:38:20 +00:00
and <code > !<functionname > function_equals</functionname> (*(f.target< Functor> ()), g)</code> .</simpara> </listitem>
2004-01-25 00:38:26 +00:00
</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>
2004-03-12 03:38:20 +00:00
<header name= "boost/function_equal.hpp" >
<namespace name= "boost" >
<function name= "function_equal" >
<template >
<template-type-parameter name= "F" />
<template-type-parameter name= "G" />
</template>
<type > bool</type>
<parameter name= "f" >
<paramtype > const F& </paramtype>
</parameter>
<parameter name= "g" >
<paramtype > const G& </paramtype>
</parameter>
<purpose > <simpara > Compare two function objects for equality.</simpara> </purpose>
<returns > <simpara > <code > f == g</code> .</simpara> </returns>
<throws > <simpara > Only if <code > f == g</code> throws.</simpara> </throws>
</function>
</namespace>
</header>
2003-03-12 23:27:25 +00:00
</library-reference>
