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 >
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 > : The < code > safe_bool</ code > type can be used in contexts where a < b > bool</ b > is expected (e.g., an < b > if</ b > condition); however, implicit conversions (e.g., to < b > int</ b > ) that can occur with < b > bool</ b > are not allowed, eliminating some sources of user error.
</ ul >
< p > < a name = "not" >< code > safe_bool < b > operator!</ b > () < b > const</ b ></ code ></ a >
< ul >
< li >< b > Returns</ b > : < code > safe_bool</ code > equivalent of < code >< a href = "#empty" > empty</ a > ()</ code ></ li >
< li >< b > Throws</ b > : will not throw.</ li >
< li >< b > Notes</ b > : See < a href = "#bool" >< code > safe_bool</ code > conversion</ a >
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 >
