...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
boost::function — A generalized function pointer that can be used for callbacks or wrapping function objects.
// In header: <boost/function.hpp> template<typename Signature> class function : public functionN<R, T1, T2, ..., TN> { public: // types typedef R result_type; typedef T1 argument_type; // If N == 1 typedef T1 first_argument_type; // If N == 2 typedef T2 second_argument_type; // If N == 2 typedef T1 arg1_type; typedef T2 arg2_type; . . . typedef TN argN_type; // static constants static const int arity = N; // member classes/structs/unions // Lambda library support template<typename Args> struct sig { // types typedef result_type type; }; // construct/copy/destruct function(); function(const functionN&); function(functionN&&); function(const function&); function(function&&); template<typename F> function(F); template<typename F, typename Allocator> function(F, Allocator); function& operator=(const functionN&); function& operator=(functionN&&); function& operator=(const function&); function& operator=(function&&); ~function(); // modifiers void swap(const function&); void clear(); // capacity bool empty() const; operator safe_bool() const; bool operator!() const; // target access template<typename Functor> Functor* target(); template<typename Functor> const Functor* target() const; template<typename Functor> bool contains(const Functor&) const; const std::type_info& target_type() const; // invocation result_type operator()(arg1_type, arg2_type, ..., argN_type) const; }; // specialized algorithms template<typename Signature> void swap(function<Signature>&, function<Signature>&); // comparison operators template<typename Signature, typename Functor> bool operator==(const function<Signature>&, Functor); template<typename Signature, typename Functor> bool operator==(Functor, const function<Signature>&); template<typename Signature, typename Functor> bool operator==(const function<Signature>&, reference_wrapper<Functor>); template<typename Signature, typename Functor> bool operator==(reference_wrapper<Functor>, const function<Signature>&); template<typename Signature1, typename Signature2> void operator==(const function<Signature1>&, const function<Signature2>&); template<typename Signature, typename Functor> bool operator!=(const function<Signature>&, Functor); template<typename Signature, typename Functor> bool operator!=(Functor, const function<Signature>&); template<typename Signature, typename Functor> bool operator!=(const function<Signature>&, reference_wrapper<Functor>); template<typename Signature, typename Functor> bool operator!=(reference_wrapper<Functor>, const function<Signature>&); template<typename Signature1, typename Signature2> void operator!=(const function<Signature1>&, const function<Signature2>&);
Class template function is a thin wrapper around the numbered class templates function0, function1, etc. It accepts a function type with N arguments and will will derive from functionN instantiated with the arguments it receives.
The semantics of all operations in class template function are equivalent to that of the underlying functionN object, although additional member functions are required to allow proper copy construction and copy assignment of function objects.
function
public
construct/copy/destructfunction();
Postconditions: |
this->empty() |
Throws: |
Will not throw. |
function(const functionN& f);
Postconditions: |
Contains a copy of the f 's target, if it has one, or is empty if f.empty() . |
Throws: |
Will not throw unless copying the target of f throws. |
function(functionN&& f);
Requires: |
C++11 compatible compiler. |
Postconditions: |
Moves the value from f to *this . If the argument has its function object allocated on the heap, its buffer will be assigned to *this leaving argument empty. |
Throws: |
Will not throw unless argument has its function object allocated not on the heap and copying the target of f throws. |
function(const function& f);
Postconditions: |
Contains a copy of the f 's target, if it has one, or is empty if f.empty() . |
Throws: |
Will not throw unless copying the target of f throws. |
function(function&& f);
Requires: |
C++11 compatible compiler. |
Postconditions: |
Moves the value from f to *this . If the argument has its function object allocated on the heap, its buffer will be assigned to *this leaving argument empty. |
Throws: |
Will not throw unless argument has its function object allocated not on the heap and copying the target of f throws. |
template<typename F> function(F f);
Requires: |
F is a function object Callable from this . |
Postconditions: |
*this targets a copy of f if f is nonempty, or this->empty() if f is empty. |
template<typename F, typename Allocator> function(F f, Allocator alloc);
Requires: |
F is a function object Callable from this , Allocator is an allocator. The copy constructor and destructor of Allocator shall not throw. |
Postconditions: |
*this targets a copy of f if f is nonempty, or this->empty() if f is empty. |
Effects: |
If memory allocation is required, the given allocator (or a copy of it) will be used to allocate that memory. |
function& operator=(const functionN& f);
function& operator=(functionN&& f);
Requires: |
C++11 compatible compiler. |
Postconditions: |
Moves the value from f to *this . If the argument has its function object allocated on the heap, its buffer will be assigned to *this leaving argument empty. |
Throws: |
Will not throw unless argument has its function object allocated not on the heap and copying the target of f throws. |
function& operator=(const function& f);
Postconditions: |
If copy construction of the target of f does not throw, *this targets a copy of f 's target, if it has one, or is empty if f.empty() . |
Throws: |
Will not throw when the target of f is a stateless function object or a reference to the function object. If copy construction does throw, this->empty() . |
function& operator=(function&& f);
Requires: |
C++11 compatible compiler. |
Postconditions: |
Moves the value from f to *this . If the argument has its function object allocated on the heap, its buffer will be assigned to *this leaving argument empty. |
Throws: |
Will not throw unless argument has its function object allocated not on the heap and copying the target of f throws. |
~function();
Effects: |
If !this->empty() , destroys the target of this . |
function
capacitybool empty() const;
Returns: |
false if this has a target, and true otherwise. |
Throws: |
Will not throw. |
operator safe_bool() const;
Returns: |
A safe_bool that evaluates false in a boolean context when this->empty() , and true otherwise. |
Throws: |
Will not throw. |
bool operator!() const;
Returns: |
this->empty() |
Throws: |
Will not throw. |
function
target accesstemplate<typename Functor> Functor* target(); template<typename Functor> const Functor* target() const;
Returns: |
If this stores a target of type
Functor , returns the address of the
target. Otherwise, returns the NULL
pointer. |
Throws: |
Will not throw. |
template<typename Functor> bool contains(const Functor& f) const;
Returns: |
true if this->target<Functor>() is non-NULL and function_equal(*(this->target<Functor>()), f)
|
const std::type_info& target_type() const;
Returns: |
typeid of the target function object, or typeid(void) if this->empty() . |
Throws: |
Will not throw. |
function
invocationresult_type operator()(arg1_type a1, arg2_type a2, ..., argN_type aN) const;
Effects: |
f(a1, a2, ..., aN) , where f is the target of *this . |
Returns: |
if R is void , nothing is returned; otherwise, the return value of the call to f is returned. |
Throws: |
bad_function_call if this->empty() . Otherwise, may through any exception thrown by the target function f . |
function
comparison operatorstemplate<typename Signature, typename Functor> bool operator==(const function<Signature>& f, Functor g); template<typename Signature, typename Functor> bool operator==(Functor g, const function<Signature>& f); template<typename Signature, typename Functor> bool operator==(const function<Signature>& f, reference_wrapper<Functor> g); template<typename Signature, typename Functor> bool operator==(reference_wrapper<Functor> g, const function<Signature>& f); template<typename Signature1, typename Signature2> void operator==(const function<Signature1>& f1, const function<Signature2>& f2);
Returns: |
True when f stores an object of
type Functor and one of the following conditions applies:
|
Notes: |
function
objects are not
EqualityComparable. |
Rationale: |
The safe_bool conversion
opens a loophole whereby two function
instances can be compared via == , although this
is not feasible to implement. The undefined void
operator== closes the loophole and ensures a
compile-time or link-time error. |
template<typename Signature, typename Functor> bool operator!=(const function<Signature>& f, Functor g); template<typename Signature, typename Functor> bool operator!=(Functor g, const function<Signature>& f); template<typename Signature, typename Functor> bool operator!=(const function<Signature>& f, reference_wrapper<Functor> g); template<typename Signature, typename Functor> bool operator!=(reference_wrapper<Functor> g, const function<Signature>& f); template<typename Signature1, typename Signature2> void operator!=(const function<Signature1>& f1, const function<Signature2>& f2);
Returns: |
True when f does not store an
object of type Functor or it stores an object of
type Functor and one of the following conditions
applies:
|
Notes: |
function
objects are not
EqualityComparable. |
Rationale: |
The safe_bool conversion
opens a loophole whereby two function
instances can be compared via != , although this
is not feasible to implement. The undefined void
operator!= closes the loophole and ensures a
compile-time or link-time error. |