| 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

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

    template<typename Signature  // Function type R (T1, T2, ..., TN)
             >
    class function : public functionN<R, T1, T2, ..., TN> {
    public:
      // types
      typedef R  result_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;

      // member classes/structs/unions

      // 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);
      template<typename F, typename Allocator> function(F, Allocator);
      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>
      void swap(function<Signature>&, function<Signature>&);

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

## 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` public 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.     template<typename F, typename Allocator> function(F f, Allocator 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.

6.     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()`.

7.     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()`.

8.     ~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>
         void swap(function<Signature>& f1, function<Signature>& f2);

   Effects: | `f1.swap(f2)`

### `function` comparison operators

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