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
  {
    typedef implementation-defined safe_bool;
    bool empty() const;
    operator safe_bool() const;
    safe_bool operator!() const;
  };

  // For N in [0, MAX_ARGS]
  template<typename Signature,
           typename Arg1,
	   typename Arg2,
           ...
           typename ArgN,
	   typename Policy    = empty_function_policy, // Deprecated
	   typename Mixin     = empty_function_mixin, // Deprecated
	   typename Allocator = std::allocator<function_base> >
  class functionN : public function_base, public Mixin
  {
    typedef ResultType result_type; // [1]
    typedef Policy     policy_type; // Deprecated
    typedef Mixin      mixin_type; // Deprecated
    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(F, const Mixin& = Mixin());
    template<typename F> functionN(reference_wrapper<F>);
    
    // Assignment
    functionN& operator=(const functionN&);
    template<typename F> functionN& operator=(F);
    template<typename F> functionN& operator=(reference_wrapper<F>);
    void set(const functionN&); // Deprecated
    template<typename F> void set(F); // Deprecated
    void swap(functionN&);
    void clear();

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

  template<typename ResultType,
           typename Arg1,
	   typename Arg2,
           ...
	   typename ArgN,
           typename Policy, // Deprecated
           typename Mixin, // Deprecated
           typename Allocator>
  void swap(functionN<ResultType, Arg1, Arg2, ..., ArgN, Policy, Mixin, Allocator>&,
            functionN<ResultType, Arg1, Arg2, ..., ArgN, Policy, Mixin, Allocator>&);

  // For any N in [0, MAX_ARGS]
  template<typename Signature, // Function type: ResultType (Arg1, Arg2, ..., ArgN)
	   typename Policy    = empty_function_policy, // Deprecated
	   typename Mixin     = empty_function_mixin, // Deprecated
	   typename Allocator = std::allocator<function_base> >
  class function : public functionN<ResultType, Arg1, Arg2, ..., ArgN>
  {
    // Construction
    function();
    function(const function&);
    function(const functionN<ResultType, Arg1, Arg2, ..., ArgN>&);
    template<typename F> functionN(F);
    
    // Assignment
    function& operator=(const function&);
    function& operator=(const functionN<ResultType, Arg1, Arg2, ..., ArgN>&);
    template<typename F> function& operator=(F);
    void set(const function&); // Deprecated
    void set(const functionN<ResultType, Arg1, Arg2, ..., ArgN>&); // Deprecated
    template<typename F> void set(F); // Deprecated
  };

  template<typename Signature, typename Policy, typename Mixin, typename Allocator>
  void swap(function<Signature, Policy, Mixin, Allocator>&,
            function<Signature, Policy, Mixin, Allocator>&);
}	   

Definitions

• A function object f is compatible if for the given set of argument types Arg1, Arg2, ..., ArgN and a return type ResultType, the appropriate following function is well-formed:

    // if ResultType is not void
    ResultType foo(Arg1 arg1, Arg2 arg2, ..., ArgN argN)
    {
      return f(arg1, arg2, ..., argN);
    }
  
    // if ResultType is void
    ResultType foo(Arg1 arg1, Arg2 arg2, ..., ArgN argN)
    {
      f(arg1, arg2, ..., argN);
    }
  

  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 R (X::*mf)(Arg1, Arg2, ..., ArgN) cv-quals be adapted to a function object with the following function call operator overloads:

    template<typename P>
    R operator()(cv-quals P& x, Arg1 arg1, Arg2 arg2, ..., ArgN argN) const
    {
      return (*x).*mf(arg1, arg2, ..., argN);
    }
  

• A function object f of type F is stateless if it is a function pointer or if boost::is_stateless<T> 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.

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 safe_bool() const

• Returns: safe_bool equivalent of !empty()
• Throws: will not throw.
• Notes: The safe_bool type can be used in contexts where a bool is expected (e.g., an if condition); however, implicit conversions (e.g., to int) that can occur with bool are not allowed, eliminating some sources of user error.

safe_bool operator!() const

• Returns: safe_bool equivalent of empty()
• Throws: will not throw.
• Notes: See safe_bool conversion

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 unless construction of the Mixin subobject throws.

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.
• Throws: will not throw unless copying the target of g or construction of the Mixin subobject throws.

template<typename F> functionN(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.
• Throws: will not throw when g is a stateless function object unless construction of the Mixin subobject throws.

template<typename F> functionN(reference_wrapper<F> g);

• Requires: g.get() is a compatible function object.
• Effects: Constructs the Mixin subobject from the given mixin.
• Postconditions: this object targets g (not a copy of g.get()) if g.get() is nonempty, or this->empty() if g.get() is empty.
• Throws: will not throw unless the construction of the Mixin subobject throws.

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.
• Throws: will not throw when the target of g is a stateless function object or a reference to the function object, unless the copy of the Mixin subobject throws.

template<typename F> functionN& operator=(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.
• Throws: will not throw when g is a stateless function object.

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

• Requires: g.get() is a compatible function object.
• Postconditions: f targets g.get() (not a copy of g.get()) if g.get() is nonempty, or f.empty() if g.get() is empty.
• Returns: *this.
• Throws: will throw only if the destruction or deallocation of the target of this throws.

void set(const functionN& g);

• Effects: *this = g.
• Note: This function is deprecated and will be removed in future versions of Boost.Function. Please use the assignment operator instead.

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

• Effects: *this = g.
• Note: This function is deprecated and will be removed in future versions of Boost.Function. Please use the assignment operator instead.

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) const;

• 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.
• Note: invocation policies have been deprecated and will be removed in a later release.

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, // Deprecated
         typename Mixin, // Deprecated
         typename Allocator>
void swap(functionN<ResultType, Arg1, Arg2, ..., ArgN, Policy, Mixin, Allocator>& f,
          functionN<ResultType, Arg1, Arg2, ..., ArgN, Policy, Mixin, Allocator>& g);

• Effects: f.swap(g);

template<typename Signature, typename Policy, typename Mixin, typename Allocator>
void swap(function<Signature, Policy, Mixin, Allocator>& f,
          function<Signature, Policy, Mixin, Allocator>& g);

• Effects: f.swap(g);

[1] On compilers not supporting void returns, when the ReturnType is void, the result_type of a Boost.Function object is implementation-defined.