Class template function

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

Synopsis

template<typename Signature,   // Function type R (T1, T2, ..., TN)
         typename Allocator = std::allocator<void> > 
class function : public functionN<R, T1, T2, ..., TN, Allocator> {
public:
  // types
  typedef R         result_type;         
  typedef Allocator allocator_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;

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

  // construct/copy/destruct
  function();
  function(const functionN&);
  function(const function&);
  template<typename F> function(F);
  function& operator=(const function&);
  function& operator=(const 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, typename Allocator> 
  void swap(function<Signature, Allocator>&, function<Signature, Allocator>&);

// comparison operators
template<typename Signature, typename Allocator, typename Functor> 
  bool operator==(const function<Signature, Allocator>&, Functor);
template<typename Signature, typename Allocator, typename Functor> 
  bool operator==(Functor, const function<Signature, Allocator>&);
template<typename Signature, typename Allocator, typename Functor> 
  bool operator==(const function<Signature, Allocator>&, 
                  reference_wrapper<Functor>);
template<typename Signature, typename Allocator, typename Functor> 
  bool operator==(reference_wrapper<Functor>, 
                  const function<Signature, Allocator>&);
template<typename Signature1, typename Allocator1, typename Signature2, 
         typename Allocator2> 
  void operator==(const function<Signature1, Allocator1>&, 
                  const function<Signature2, Allocator2>&);
template<typename Signature, typename Allocator, typename Functor> 
  bool operator!=(const function<Signature, Allocator>&, Functor);
template<typename Signature, typename Allocator, typename Functor> 
  bool operator!=(Functor, const function<Signature, Allocator>&);
template<typename Signature, typename Allocator, typename Functor> 
  bool operator!=(const function<Signature, Allocator>&, 
                  reference_wrapper<Functor>);
template<typename Signature, typename Allocator, typename Functor> 
  bool operator!=(reference_wrapper<Functor>, 
                  const function<Signature, Allocator>&);
template<typename Signature1, typename Allocator1, typename Signature2, 
         typename Allocator2> 
  void operator!=(const function<Signature1, Allocator1>&, 
                  const function<Signature2, Allocator2>&);

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.

function construct/copy/destruct

  1. function();
    Postconditions: this->empty()
    Throws: Will not throw. 
  2. 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. 
  3. 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. 
  4. 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. 
  5. function& operator=(const function& 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().

    		 
  6. 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(). 
  7. ~function();
    Effects: If !this->empty(), destroys the target of this.

function modifiers

  1. void swap(const function& f);
    Effects: Interchanges the targets of *this and f. 
  2. void clear();
    Postconditions: this->empty()
    Throws: Will not throw.

function capacity

  1. bool empty() const;
    Returns: false if this has a target, and true otherwise.
    Throws: Will not throw. 
  2. 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. 
  3. bool operator!() const;
    Returns: this->empty()
    Throws: Will not throw.

function target access

  1. template<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. 
  2. 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) 
  3. 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 invocation

  1. result_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 specialized algorithms

  1. template<typename Signature, typename Allocator> 
  void swap(function<Signature, Allocator>& f1, 
            function<Signature, Allocator>& f2);
    Effects: f1.swap(f2)

function comparison operators

  1. template<typename Signature, typename Allocator, typename Functor> 
  bool operator==(const function<Signature, Allocator>& f, Functor g);
template<typename Signature, typename Allocator, typename Functor> 
  bool operator==(Functor g, const function<Signature, Allocator>& f);
template<typename Signature, typename Allocator, typename Functor> 
  bool operator==(const function<Signature, Allocator>& f, 
                  reference_wrapper<Functor> g);
template<typename Signature, typename Allocator, typename Functor> 
  bool operator==(reference_wrapper<Functor> g, 
                  const function<Signature, Allocator>& f);
template<typename Signature1, typename Allocator1, typename Signature2, 
         typename Allocator2> 
  void operator==(const function<Signature1, Allocator1>& f1, 
                  const function<Signature2, Allocator2>& 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. 

  2. template<typename Signature, typename Allocator, typename Functor> 
  bool operator!=(const function<Signature, Allocator>& f, Functor g);
template<typename Signature, typename Allocator, typename Functor> 
  bool operator!=(Functor g, const function<Signature, Allocator>& f);
template<typename Signature, typename Allocator, typename Functor> 
  bool operator!=(const function<Signature, Allocator>& f, 
                  reference_wrapper<Functor> g);
template<typename Signature, typename Allocator, typename Functor> 
  bool operator!=(reference_wrapper<Functor> g, 
                  const function<Signature, Allocator>& f);
template<typename Signature1, typename Allocator1, typename Signature2, 
         typename Allocator2> 
  void operator!=(const function<Signature1, Allocator1>& f1, 
                  const function<Signature2, Allocator2>& 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.
Copyright © 2001-2004 Douglas Gregor

Top