Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

Class template function

boost::function — A generalized function pointer that can be used for callbacks or wrapping function objects.

Synopsis

// In header: <boost/function.hpp>

template<typename Signature> 
class function : public functionN< {
public:
  // types
  typedef   ;         
  typedef  ;         // If N == 1
  typedef  ;   // If N == 2
  typedef  ;  // If N == 2
  typedef  ;           
  typedef  ;           
     .
     .
     .
  typedef  ;           

  // static constants
    = ;

  // member classes/structs/unions

  // Lambda library support
  template<typename Args> 
  struct sig {
    // types
    typedef  ;
  };

  // construct/copy/destruct
  ();
  (functionN&);
  (functionN&&);
  (function&);
  (function&&);
  template<typename F> ();
  template<typename F, typename Allocator> (, );
  function& (functionN&);
  function& (functionN&&);
  function& (function&);
  function& (function&&);
  ~();

  // modifiers
   (function&);
   ();

  // capacity
   () ;
  () ;
   () ;

  // target access
  template<typename Functor>  ();
  template<typename Functor>  () ;
  template<typename Functor>  () ;
   () ;

  // invocation
   (, , ..., ) ;
};

// specialized algorithms
template<typename Signature> 
   (function<, function<);

// comparison operators
template<typename Signature, typename Functor> 
   (function<, );
template<typename Signature, typename Functor> 
   (, function<);
template<typename Signature, typename Functor> 
   (function<, reference_wrapper<);
template<typename Signature, typename Functor> 
   (reference_wrapper<, function<);
template<typename Signature1, typename Signature2> 
   (function<, function<);
template<typename Signature, typename Functor> 
   (function<, );
template<typename Signature, typename Functor> 
   (, function<);
template<typename Signature, typename Functor> 
   (function<, reference_wrapper<);
template<typename Signature, typename Functor> 
   (reference_wrapper<, function<);
template<typename Signature1, typename Signature2> 
   (function<, function<);

Description

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.

Template Parameters

  1. typename Signature

function public construct/copy/destruct

  1. ();

    Postconditions:

    this->empty()

    Throws:

    Will not throw.
  2. (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.
  3. (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.
  4. (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.
  5. (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.
  6. template<typename 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.
  7. template<typename F, typename Allocator> ( f,  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.
  8. function& (functionN& f);

    Postconditions:

    If copy construction does not throw, *this targets a copy of f's target, if it has one, or is empty if f.empty(). If copy construction does throw, this->empty().
  9. 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.
  10. function& (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().
  11. 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.
  12. ~();

    Effects:

    If !this->empty(), destroys the target of this.

function modifiers

  1.  (function& f);

    Effects:

    Interchanges the targets of *this and f.
  2.  ();

    Postconditions:

    this->empty()

    Throws:

    Will not throw.

function capacity

  1.  () ;

    Returns:

    false if this has a target, and true otherwise.

    Throws:

    Will not throw.
  2. () ;

    Returns:

    A safe_bool that evaluates false in a boolean context when this->empty(), and true otherwise.

    Throws:

    Will not throw.
  3.  () ;

    Returns:

    this->empty()

    Throws:

    Will not throw.

function target access

  1. template<typename Functor>  ();
    template<typename Functor>  () ;

    Returns:

    If this stores a target of type Functor, returns the address of the target. Otherwise, returns the NULL pointer.

    Throws:

    Will not throw.
  2. template<typename Functor>  ( f) ;

    Returns:

    true if this->target<Functor>() is non-NULL and function_equal(*(this->target<Functor>()), f)
  3.  () ;

    Returns:

    typeid of the target function object, or typeid(void) if this->empty().

    Throws:

    Will not throw.

function invocation

  1.  ( a1,  a2, ...,  aN) ;

    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 specialized algorithms

  1. template<typename Signature> 
       (function< f1, function< f2);

    Effects:

    f1.swap(f2)

function comparison operators

  1. template<typename Signature, typename Functor> 
       (function< f,  g);
    template<typename Signature, typename Functor> 
       ( g, function< f);
    template<typename Signature, typename Functor> 
       (function< f, reference_wrapper< g);
    template<typename Signature, typename Functor> 
       (reference_wrapper< g, function< f);
    template<typename Signature1, typename Signature2> 
       (function< f1, 
                      function< f2);

    Returns:

    True when f stores an object of type Functor and one of the following conditions applies:
    • g is of type reference_wrapper<Functor> and f.target<Functor>() == g.get_pointer().
    • g is not of type reference_wrapper<Functor> and function_equals(*(f.target<Functor>()), g).

    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.
  2. template<typename Signature, typename Functor> 
       (function< f,  g);
    template<typename Signature, typename Functor> 
       ( g, function< f);
    template<typename Signature, typename Functor> 
       (function< f, reference_wrapper< g);
    template<typename Signature, typename Functor> 
       (reference_wrapper< g, function< f);
    template<typename Signature1, typename Signature2> 
       (function< f1, 
                      function< 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:
    • g is of type reference_wrapper<Functor> and f.target<Functor>() != g.get_pointer().
    • g is not of type reference_wrapper<Functor> and !function_equals(*(f.target<Functor>()), g).

    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.

PrevUpHomeNext