| Home | Libraries | People | FAQ | More

## 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;

      // construct/copy/destruct
      function();
      function(const functionN&);
      function(const function&);
      template<typename F> function(F);
      function& operator=(const functionN&);
      function& operator=(const function&);
      ~function();

      // modifiers
      void swap(const function&);
      void clear();

      // capacity
      bool empty() const;
      operator safe_bool() const;
      bool operator!() 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>&);

    // undefined operators
    template<typename Signature1, typename Allocator1, typename Signature2,
             typename Allocator2>
      void operator==(const function<Signature1, Allocator1>&,
                      const function<Signature2, Allocator2>&);
    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.
   Throws: Will not throw when `f` is a stateless function object.

5.     function& operator=(const functionN& f);

   Postconditions: `*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.

6.     function& operator=(const function& f);

   Postconditions: `*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.

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`.
   Throws: Will not throw.

2.     void clear();

   Postconditions: `this->empty()`
   Throws: Will not throw.

### `function` capacity

1.     bool empty() const;

   Returns: `true` if `this` has a target, and `false` 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` 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)`
   Throws: Will not throw.

### `function` undefined operators

1.     template<typename Signature1, typename Allocator1, typename Signature2,
                typename Allocator2>
         void operator==(const function<Signature1, Allocator1>& f1,
                         const function<Signature2, Allocator2>& f2);

   Notes: This function must be left undefined.
   Rationale: The `safe_bool` conversion opens a loophole whereby two function instances can be compared via `==`. This undefined `void operator ==` closes the loophole and ensures a compile-time or link-time error.

2.     template<typename Signature1, typename Allocator1, typename Signature2,
                typename Allocator2>
         void operator!=(const function<Signature1, Allocator1>& f1,
                         const function<Signature2, Allocator2>& f2);

   Notes: This function must be left undefined.
   Rationale: The `safe_bool` conversion opens a loophole whereby two function instances can be compared via `!=`. This undefined `void operator !=` closes the loophole and ensures a compile-time or link-time error.

Last revised: February 19, 2003 at 22:46:09 GMT | Copyright © 2001-2003 Douglas Gregor

Class template functionN |  | Frequently Asked Questions