Boost.Function Reference Manual

Header <boost/function.hpp> synopsis

Here MAX_ARGS is an implementation-defined constant that defines the maximum number of function arguments supported by Boost.Function and will be at least 10. The MAX_ARGS constant referred to in this document need not have any direct representation in the library.

namespace boost {
  class function_base
  {
    bool empty() const;
    operator bool() const;
  };

  // For N in [0, MAX_ARGS]
  template<typename ResultType,
           typename Arg1,
	   typename Arg2,
           ...
           typename ArgN,
	   typename Policy    = empty_function_policy,
	   typename Mixin     = empty_function_mixin,
	   typename Allocator = std::allocator<function_base> >
  class functionN : public function_base, public Mixin
  {
    typedef ResultType result_type;
    typedef Policy     policy_type;
    typedef Mixin      mixin_type;
    typedef Allocator  allocator_type;

    typedef Arg1 argument_type;        // If N == 1

    typedef Arg1 first_argument_type;  // If N == 2
    typedef Arg2 second_argument_type; // If N == 2

    // Construction
    explicit functionN(const Mixin& = Mixin());
    functionN(const functionN&);
    template<typename F> functionN(const F&, const Mixin& = Mixin());
    
    // Assignment
    functionN& operator=(const functionN&);
    template<typename F> functionN& operator=(const F&);
    void set(const functionN&);
    template<typename F> void set(const F&);
    void swap(functionN&);
    void clear();

    // Invocation
    result_type operator()(Arg1 a1, Arg2 a2, ..., ArgN aN);
    result_type operator()(Arg1 a1, Arg2 a2, ..., ArgN aN) const;
  };

  template<typename ResultType,
           typename Arg1,
	   typename Arg2,
           ...
	   typename ArgN,
           typename Policy,
           typename Mixin,
           typename Allocator>
  inline void swap(const function<Arg1, Arg2, ...ArgN, Policy, Mixin, Allocator>&,
                   const function<Arg1, Arg2, ...ArgN, Policy, Mixin, Allocator>&);

  // For any N in [0, MAX_ARGS]
  template<typename ResultType,
           typename Arg1,
	   typename Arg2,
           ...
           typename ArgN,
           typename ArgN+1 = implementation-defined,
           typename ArgN+2 = implementation-defined,
	   ...
	   typename ArgMAX_ARGS = implementation-defined>
  class function : public functionN<Arg1, Arg2, ..., ArgN>
  {
    // Construction
    function();
    function(const function&);
    functionN(const functionN&);
    template<typename F> functionN(const F&);
    
    // Assignment
    function& operator=(const function&);
    functionN& operator=(const functionN&);
    template<typename F> function& operator=(const F&);
    void set(const function&);
    void set(const functionN&);
    template<typename F> void set(const F&);
  };

  template<typename ResultType,
           typename Arg1,
	   typename Arg2,
           ...
	   typename ArgMAX_ARGS>
  inline void swap(const function<Arg1, Arg2, ...ArgMAX_ARGS>&,
                   const function<Arg1, Arg2, ...ArgMAX_ARGS>&);
}	   

Class function_base

Class function_base is the common base class for all Boost.Function objects. Objects of type function_base may not be created directly.

bool empty() const

• Returns: true if the function object has a target, false otherwise.
• Throws: will not throw.

operator bool() const

• Returns: !empty()
• Throws: will not throw.

Class template functionN

Class template functionN is actually a family of related classes function0, function1, etc., up to some implementation-defined maximum. In this context, N refers to the number of parameters and f refers to the implicit object parameter.

explicit functionN(const Mixin& = Mixin());

• Effects: Constructs the Mixin subobject with the given mixin.
• Postconditions: f.empty().
• Throws: will not throw.

functionN(const functionN& g);

• Postconditions: f contains a copy of the g's target, if it has one, or is empty if g.empty(). The mixin for the f is copy-constructed from the mixin of g.

template<typename F> functionN(const F& g, const Mixin& = Mixin());

• Requires: g is a compatible function object.
• Effects: Constructs the Mixin subobject from the given mixin.
• Postconditions: f targets a copy of g if g is nonempty, or f.empty() if g is empty.
• Rationale: g is a reference-to-const 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 g is reference-to-const pointer-to-function.

functionN& operator=(const functionN& g);

• Postconditions: f targets a copy of g's target, if it has one, or is empty if g.empty(). The mixin for f is assigned the value of the mixin for g.
• Returns: *this.

template<typename F> functionN& operator=(const F& g);

• Requires: g is a compatible function object.
• Postconditions: f targets a copy of g if g is nonempty, or f.empty() if g is empty.
• Returns: *this.
• Rationale: g is a reference-to-const 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 g is reference-to-const pointer-to-function.

void set(const functionN& g);

• Effects: *this = g.

template<typename F> void set(const F& g);

• Effects: *this = g.

void swap(functionN& g);

• Effects: interchanges the targets of f and g and swaps the mixins of f and g.
• Throws: will not throw.

void clear();

• Effects: If !empty(), deallocates current target.
• Postconditions: empty().

result_type operator()(Arg1 a1, Arg2 a2, ..., ArgN aN);

• Requires: !empty().
• Effects: target is the underlying function target. It is not const or volatile qualified.
  1. policy_type policy;
  2. policy.precall(this);
  3. target(a1, a2, ..., aN);
  4. policy.postcall(this);
• Returns: the value returned by target.

result_type operator()(Arg1 a1, Arg2 a2, ..., ArgN aN) const;

• Requires: !empty().
• Effects: const-target is the underlying function target. It is const qualified but not volatile qualified.
  1. policy_type policy;
  2. policy.precall(this);
  3. const-target(a1, a2, ..., aN);
  4. policy.postcall(this);
• Returns: the value returned by const-target.

Class template function

Class template function is a thin wrapper around the numbered class templates function0, function1, etc. It accepts up to MAX_ARGS arguments, but when passed N arguments it will derive from functionN specialized 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.

Operations

template<typename ResultType,
         typename Arg1,
	 typename Arg2,
         ...
	 typename ArgN,
         typename Policy,
         typename Mixin,
         typename Allocator>
inline void swap(const functionN<Arg1, Arg2, ...ArgN, Policy, Mixin, Allocator>& f,
                 const functionN<Arg1, Arg2, ...ArgN, Policy, Mixin, Allocator>& g);

• Effects: f.swap(g);

template<typename ResultType,
         typename Arg1,
	 typename Arg2,
         ...
	 typename ArgMAX_ARGS>
inline void swap(const function<Arg1, Arg2, ...ArgMAX_ARGS>& f,
                 const function<Arg1, Arg2, ...ArgMAX_ARGS>& g);

• Effects: f.swap(g);