2001-07-14 19:57:09 +00:00
<!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 >
2001-07-16 18:17:00 +00:00
< b > namespace< / b > boost {
< b > class< / b > < a href = "#function_base" > function_base< / a >
2001-07-14 19:57:09 +00:00
{
2001-10-28 04:52:37 +00:00
< b > typedef< / b > < em > implementation-defined< / em > safe_bool;
2001-07-16 18:17:00 +00:00
< a href = "#empty" > < b > bool< / b > empty() < b > const< / b > < / a > ;
2001-10-28 04:52:37 +00:00
< a href = "#bool" > < b > operator< / b > safe_bool() < b > const< / b > < / a > ;
< a href = "#not" > safe_bool < b > operator!< / b > () < b > const< / b > < / a > ;
2001-07-14 19:57:09 +00:00
};
// For < i > N< / i > in [0, < i > MAX_ARGS< / i > ]
2001-07-16 18:17:00 +00:00
< b > template< / b > < < b > typename< / b > ResultType,
< b > typename< / b > Arg1,
< b > typename< / b > Arg2,
2001-07-14 19:57:09 +00:00
< i > ...< / i >
2001-07-16 18:17:00 +00:00
< b > typename< / b > Arg< i > N< / i > ,
< b > typename< / b > Policy = empty_function_policy,
< b > typename< / b > Mixin = empty_function_mixin,
< 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
2001-07-14 19:57:09 +00:00
{
2001-07-16 18:17:00 +00:00
< b > typedef< / b > ResultType result_type;
< b > typedef< / b > Policy policy_type;
< b > typedef< / b > Mixin mixin_type;
< b > typedef< / b > Allocator allocator_type;
2001-07-14 19:57:09 +00:00
2001-07-16 18:17:00 +00:00
< b > typedef< / b > Arg1 argument_type; < i > // If N == 1< / i >
2001-07-14 19:57:09 +00:00
2001-07-16 18:17:00 +00:00
< b > typedef< / b > Arg1 first_argument_type; < i > // If N == 2< / i >
< b > typedef< / b > Arg2 second_argument_type; < i > // If N == 2< / i >
2001-07-14 19:57:09 +00:00
< i > // Construction< / i >
2001-07-16 18:17:00 +00:00
< 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 > (< b > const< / b > F< b > & < / b > , < b > const< / b > Mixin< b > & < / b > = Mixin())< / a > ;
2001-07-14 19:57:09 +00:00
< i > // Assignment< / i >
2001-07-16 18:17:00 +00:00
< 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 > =(< b > const< / b > F< b > & < / b > )< / a > ;
< a href = "#functionN_copy_set" > < b > void< / b > set(< b > const< / b > function< i > N< / i > < b > & < / b > )< / a > ;
< a href = "#functionN_target_set" > < b > template< / b > < < b > typename< / b > F> < b > void< / b > set(< b > const< / b > F< b > & < / b > )< / a > ;
< a href = "#functionN_swap" > < b > void< / b > swap(function< i > N< / i > < b > & < / b > )< / a > ;
< a href = "#functionN_clear" > < b > void< / b > clear()< / a > ;
2001-07-14 19:57:09 +00:00
< i > // Invocation< / i >
2001-07-16 18:17:00 +00:00
< 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 > ;
2001-07-14 19:57:09 +00:00
};
2001-07-16 18:17:00 +00:00
< b > template< / b > < < b > typename< / b > ResultType,
< b > typename< / b > Arg1,
< b > typename< / b > Arg2,
2001-07-14 19:57:09 +00:00
< i > ...< / i >
2001-07-16 18:17:00 +00:00
< b > typename< / b > Arg< i > N< / i > ,
< b > typename< / b > Policy,
< b > typename< / b > Mixin,
< b > typename< / b > Allocator>
2001-10-28 04:52:37 +00:00
< b > void< / b > < a href = "#swap_functionN" > swap< / a > (< b > const< / b > function< em > N< / em > < Arg1, Arg2, < i > ...< / i > , Arg< i > N< / i > , Policy, Mixin, Allocator> < b > & < / b > ,
< b > const< / b > function< em > N< / em > < Arg1, Arg2, < i > ...< / i > , Arg< i > N< / i > , Policy, Mixin, Allocator> < b > & < / b > );
2001-07-14 19:57:09 +00:00
// For any < i > N< / i > in [0, < i > MAX_ARGS< / i > ]
2001-07-16 18:17:00 +00:00
< b > template< / b > < < b > typename< / b > ResultType,
< b > typename< / b > Arg1,
< b > typename< / b > Arg2,
2001-07-14 19:57:09 +00:00
< i > ...< / i >
2001-07-16 18:17:00 +00:00
< b > typename< / b > Arg< i > N< / i > ,
< b > typename< / b > Arg< i > N+1< / i > = < i > implementation-defined< / i > ,
< b > typename< / b > Arg< i > N+2< / i > = < i > implementation-defined< / i > ,
2001-07-14 19:57:09 +00:00
< i > ...< / i >
2001-07-16 18:17:00 +00:00
< b > typename< / b > Arg< i > MAX_ARGS< / i > = < i > implementation-defined< / i > >
< b > class< / b > < a href = "#function" > function< / a > : < b > public< / b > < a href = "#functionN" > function< i > N< / i > < / a > < Arg1, Arg2, < i > ...< / i > , Arg< i > N< / i > >
2001-07-14 19:57:09 +00:00
{
< i > // Construction< / i >
function();
2001-07-16 18:17:00 +00:00
function(< b > const< / b > function< b > & < / b > );
function< i > N< / i > (< b > const< / b > function< i > N< / i > < b > & < / b > );
< b > template< / b > < < b > typename< / b > F> function< i > N< / i > (< b > const< / b > F< b > & < / b > );
2001-07-14 19:57:09 +00:00
< i > // Assignment< / i >
2001-07-16 18:17:00 +00:00
function< b > & < / b > < b > operator< / b > =(< b > const< / b > function< b > & < / b > );
function< i > N< / i > < b > & < / b > < b > operator< / b > =(< b > const< / b > function< i > N< / i > < b > & < / b > );
< b > template< / b > < < b > typename< / b > F> function< b > & < / b > < b > operator< / b > =(< b > const< / b > F< b > & < / b > );
< b > void< / b > set(< b > const< / b > function< b > & < / b > );
< b > void< / b > set(< b > const< / b > function< i > N< / i > < b > & < / b > );
< b > template< / b > < < b > typename< / b > F> < b > void< / b > set(< b > const< / b > F< b > & < / b > );
2001-07-14 19:57:09 +00:00
};
2001-07-16 18:17:00 +00:00
< b > template< / b > < < b > typename< / b > ResultType,
< b > typename< / b > Arg1,
< b > typename< / b > Arg2,
2001-07-14 19:57:09 +00:00
< i > ...< / i >
2001-07-16 18:17:00 +00:00
< b > typename< / b > Arg< i > MAX_ARGS< / i > >
< b > void< / b > < a href = "#swap_function" > swap< / a > (< b > const< / b > function< Arg1, Arg2, < i > ...< / i > , Arg< i > MAX_ARGS< / i > > < b > & < / b > ,
< b > const< / b > function< Arg1, Arg2, < i > ...< / i > , Arg< i > MAX_ARGS< / i > > < b > & < / b > );
2001-07-14 19:57:09 +00:00
}
< / pre >
2001-10-28 04:52:37 +00:00
< 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 >
R < b > operator< / b > ()(< em > cv-quals< / em > X& 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 > );
}
R < b > operator< / b > ()(< em > cv-quals< / em > X* 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 > );
}
< 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 >
< / ul >
2001-07-14 19:57:09 +00:00
< 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.
2001-07-16 18:17:00 +00:00
< p > < a name = "empty" > < code > < b > bool< / b > empty() < b > const< / b > < / code > < / a >
2001-07-14 19:57:09 +00:00
< 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 >
2001-10-28 04:52:37 +00:00
< 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 >
2001-07-14 19:57:09 +00:00
< ul >
2001-10-28 04:52:37 +00:00
< li > < b > Returns< / b > : < code > safe_bool< / code > equivalent of < code > < a href = "#empty" > empty< / a > ()< / code > < / li >
2001-07-14 19:57:09 +00:00
< li > < b > Throws< / b > : will not throw.< / li >
2001-10-28 04:52:37 +00:00
< li > < b > Notes< / b > : See < a href = "#bool" > < code > safe_bool< / code > conversion< / a >
2001-07-14 19:57:09 +00:00
< / 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.
2001-07-16 18:17:00 +00:00
< p > < a name = "functionN_default" > < code > < b > explicit< / b > function< i > N< / i > (< b > const< / b > Mixin< b > & < / b > = Mixin());< / code > < / a >
2001-07-14 19:57:09 +00:00
< 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.< / li >
< / ul >
2001-07-16 18:17:00 +00:00
< p > < a name = "functionN_copy" > < code > function< i > N< / i > (< b > const< / b > function< i > N< / i > < b > & < / b > g);< / code > < / a >
2001-07-14 19:57:09 +00:00
< 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 >
< / ul >
2001-07-16 18:17:00 +00:00
< p > < a name = "functionN_target" > < code > < b > template< / b > < < b > typename< / b > F> function< i > N< / i > (< b > const< / b > F< b > & < / b > g, < b > const< / b > Mixin< b > & < / b > = Mixin());< / code > < / a >
2001-07-14 19:57:09 +00:00
< ul >
2001-10-28 04:52:37 +00:00
< li > < b > Requires< / b > : < code > g< / code > is a < a href = "#compatible" > compatible< / a > function object.< / li >
2001-07-14 19:57:09 +00:00
< 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 >
2001-07-16 18:17:00 +00:00
< li > < b > Rationale< / b > : < code > g< / code > is a reference-to-< code > < b > const< / b > < / code > because it is a portable, efficient, and concise way to accept any function object or function pointer. In the case of a function pointer, the type of < code > g< / code > is reference-to-< code > < b > const< / b > < / code > pointer-to-function.< / li >
2001-07-14 19:57:09 +00:00
< / ul >
2001-07-16 18:17:00 +00:00
< 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 >
2001-07-14 19:57:09 +00:00
< 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 >
< / ul >
2001-07-16 18:17:00 +00:00
< p > < a name = "functionN_target_assn" > < code > < b > template< / b > < < b > typename< / b > F> function< i > N< / i > < b > & < / b > < b > operator< / b > =(< b > const< / b > F< b > & < / b > g);< / code > < / a >
2001-07-14 19:57:09 +00:00
< ul >
2001-10-28 04:52:37 +00:00
< li > < b > Requires< / b > : < code > g< / code > is a < a href = "#compatible" > compatible< / a > function object.< / li >
2001-07-14 19:57:09 +00:00
< 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 >
2001-07-16 18:17:00 +00:00
< li > < b > Rationale< / b > : < code > g< / code > is a reference-to-< code > < b > const< / b > < / code > because it is a portable, efficient, and concise way to accept any function object or function pointer. In the case of a function pointer, the type of < code > g< / code > is reference-to-< code > < b > const< / b > < / code > pointer-to-function.< / li >
2001-07-14 19:57:09 +00:00
< / ul >
2001-07-16 18:17:00 +00:00
< p > < a name = "functionN_copy_set" > < code > < b > void< / b > set(< b > const< / b > function< i > N< / i > < b > & < / b > g);< / code > < / a >
2001-07-14 19:57:09 +00:00
< ul >
< li > < b > Effects< / b > : < code > < a href = "#functionN_copy_assn" > *this = g< / a > < / code > .< / li >
< / ul >
2001-07-16 18:17:00 +00:00
< p > < a name = "functionN_target_set" > < code > < b > template< / b > < < b > typename< / b > F> < b > void< / b > set(< b > const< / b > F< b > & < / b > g);< / code > < / a >
2001-07-14 19:57:09 +00:00
< ul >
< li > < b > Effects< / b > : < code > < a href = "#functionN_target_assn" > *this = g< / a > < / code > .< / li >
< / ul >
2001-07-16 18:17:00 +00:00
< p > < a name = "functionN_swap" > < code > < b > void< / b > swap(function< i > N< / i > < b > & < / b > g);< / code > < / a >
2001-07-14 19:57:09 +00:00
< ul >
2001-07-14 20:02:39 +00:00
< 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 >
2001-07-14 19:57:09 +00:00
< li > < b > Throws< / b > : will not throw.< / li >
< / ul >
2001-07-16 18:17:00 +00:00
< p > < a name = "functionN_clear" > < code > < b > void< / b > clear(); < / code > < / a >
2001-07-14 19:57:09 +00:00
< 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 >
2001-07-22 05:30:15 +00:00
< 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 >
2001-07-14 19:57:09 +00:00
< ul >
< li > < b > Requires< / b > : < code > !< a href = "#empty" > empty< / a > ()< / code > .< / li >
2001-07-22 05:30:15 +00:00
< 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.
2001-07-14 19:57:09 +00:00
< 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 >
< / 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 >
2001-07-16 18:17:00 +00:00
< b > template< / b > < < b > typename< / b > ResultType,
< b > typename< / b > Arg1,
< b > typename< / b > Arg2,
2001-07-14 19:57:09 +00:00
< i > ...< / i >
2001-07-16 18:17:00 +00:00
< b > typename< / b > Arg< i > N< / i > ,
< b > typename< / b > Policy,
< b > typename< / b > Mixin,
< b > typename< / b > Allocator>
< b > void< / b > < a name = "swap_functionN" > swap< / a > (< b > const< / b > function< i > N< / i > < Arg1, Arg2, < i > ...< / i > , Arg< i > N< / i > , Policy, Mixin, Allocator> < b > & < / b > f,
< b > const< / b > function< i > N< / i > < Arg1, Arg2, < i > ...< / i > , Arg< i > N< / i > , Policy, Mixin, Allocator> < b > & < / b > g);
2001-07-14 19:57:09 +00:00
< / pre >
< ul >
< li > < b > Effects< / b > : < code > f.< a href = "#functionN_swap" > swap< / a > (g);< / code > < / li >
< / ul >
< p >
< pre >
2001-07-16 18:17:00 +00:00
< b > template< / b > < < b > typename< / b > ResultType,
< b > typename< / b > Arg1,
< b > typename< / b > Arg2,
2001-07-14 19:57:09 +00:00
< i > ...< / i >
2001-07-16 18:17:00 +00:00
< b > typename< / b > Arg< i > MAX_ARGS< / i > >
< b > void< / b > < a name = "swap_function" > swap< / a > (< b > const< / b > function< Arg1, Arg2, < i > ...< / i > , Arg< i > MAX_ARGS< / i > > < b > & < / b > f,
< b > const< / b > function< Arg1, Arg2, < i > ...< / i > , Arg< i > MAX_ARGS< / i > > < b > & < / b > g);
2001-07-14 19:57:09 +00:00
< / pre >
< ul >
< li > < b > Effects< / b > : < code > f.< a href = "#functionN_swap" > swap< / a > (g);< / code > < / li >
< / ul >
< hr >
< address > < a href = "mailto:gregod@cs.rpi.edu" > Douglas Gregor< / a > < / address >
<!-- Created: Fri Jul 13 10:57:20 EDT 2001 -->
<!-- hhmts start -->
2001-10-28 04:52:37 +00:00
Last modified: Sun Oct 28 00:40:55 EDT 2001
2001-07-14 19:57:09 +00:00
<!-- hhmts end -->
< / body >
< / html >
