| Home | Libraries | People | FAQ | More

## Class template functionN

boost::functionN — A set of generalized function pointers that can be used for callbacks or wrapping function objects.

## Synopsis

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

    template<typename R, typename T1, typename T2, ..., typename TN>
    class functionN : public function_base {
    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
      functionN();
      functionN(const functionN&);
      functionN(functionN&&);
      template<typename F> functionN(F);
      template<typename F, typename Allocator> functionN(F, Allocator);
      functionN& operator=(const functionN&);
      functionN& operator=(functionN&&);
      ~functionN();

      // modifiers
      void swap(const functionN&);
      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 T1, typename T2, ..., typename TN>
      void swap(functionN<T1, T2, ..., TN>&, functionN<T1, T2, ..., TN>&);

    // comparison operators
    template<typename T1, typename T2, ..., typename TN, typename Functor>
      bool operator==(const functionN<T1, T2, ..., TN>&, Functor);
    template<typename T1, typename T2, ..., typename TN, typename Functor>
      bool operator==(Functor, const functionN<T1, T2, ..., TN>&);
    template<typename T1, typename T2, ..., typename TN, typename Functor>
      bool operator==(const functionN<T1, T2, ..., TN>&,
                      reference_wrapper<Functor>);
    template<typename T1, typename T2, ..., typename TN, typename Functor>
      bool operator==(reference_wrapper<Functor>,
                      const functionN<T1, T2, ..., TN>&);
    template<typename T1, typename T2, ..., typename TN, typename U1, typename U2,
             ..., typename UN>
      void operator==(const functionN<T1, T2, ..., TN>&,
                      const functionN<U1, U2, ..., UN>&);
    template<typename T1, typename T2, ..., typename TN, typename Functor>
      bool operator!=(const functionN<T1, T2, ..., TN>&, Functor);
    template<typename T1, typename T2, ..., typename TN, typename Functor>
      bool operator!=(Functor, const functionN<T1, T2, ..., TN>&);
    template<typename T1, typename T2, ..., typename TN, typename Functor>
      bool operator!=(const functionN<T1, T2, ..., TN>&,
                      reference_wrapper<Functor>);
    template<typename T1, typename T2, ..., typename TN, typename Functor>
      bool operator!=(reference_wrapper<Functor>,
                      const functionN<T1, T2, ..., TN>&);
    template<typename T1, typename T2, ..., typename TN, typename U1, typename U2,
             ..., typename UN>
      void operator!=(const functionN<T1, T2, ..., TN>&,
                      const functionN<U1, U2, ..., UN>&);

## Description

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.

### `functionN` public construct/copy/destruct

1.     functionN();

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

2.     functionN(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.     functionN(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.     template<typename F> functionN(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> functionN(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.     functionN& operator=(const 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()`.

7.     functionN& operator=(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.

8.     ~functionN();

   Effects: | If `!this->empty()`, destroys the target of this.

### `functionN` modifiers

1.     void swap(const functionN& f);

   Effects: | Interchanges the targets of `*this` and `f`.

2.     void clear();

   Postconditions: | this->empty()

### `functionN` 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.

### `functionN` 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.

### `functionN` 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`.

### `functionN` specialized algorithms

1.     template<typename T1, typename T2, ..., typename TN>
         void swap(functionN<T1, T2, ..., TN>& f1, functionN<T1, T2, ..., TN>& f2);

   Effects: | `f1.swap(f2)`

### `functionN` comparison operators

1.     template<typename T1, typename T2, ..., typename TN, typename Functor>
         bool operator==(const functionN<T1, T2, ..., TN>& f, Functor g);
       template<typename T1, typename T2, ..., typename TN, typename Functor>
         bool operator==(Functor g, const functionN<T1, T2, ..., TN>& f);
       template<typename T1, typename T2, ..., typename TN, typename Functor>
         bool operator==(const functionN<T1, T2, ..., TN>& f,
                         reference_wrapper<Functor> g);
       template<typename T1, typename T2, ..., typename TN, typename Functor>
         bool operator==(reference_wrapper<Functor> g,
                         const functionN<T1, T2, ..., TN>& f);
       template<typename T1, typename T2, ..., typename TN, typename U1, typename U2,
                ..., typename UN>
         void operator==(const functionN<T1, T2, ..., TN>& f1,
                         const functionN<U1, U2, ..., UN>& 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_equal(*(f.target<Functor>()), g)`.
   Notes: | `functionN` objects are not EqualityComparable.
   Rationale: | The `safe_bool` conversion opens a loophole whereby two `functionN` 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 T1, typename T2, ..., typename TN, typename Functor>
         bool operator!=(const functionN<T1, T2, ..., TN>& f, Functor g);
       template<typename T1, typename T2, ..., typename TN, typename Functor>
         bool operator!=(Functor g, const functionN<T1, T2, ..., TN>& f);
       template<typename T1, typename T2, ..., typename TN, typename Functor>
         bool operator!=(const functionN<T1, T2, ..., TN>& f,
                         reference_wrapper<Functor> g);
       template<typename T1, typename T2, ..., typename TN, typename Functor>
         bool operator!=(reference_wrapper<Functor> g,
                         const functionN<T1, T2, ..., TN>& f);
       template<typename T1, typename T2, ..., typename TN, typename U1, typename U2,
                ..., typename UN>
         void operator!=(const functionN<T1, T2, ..., TN>& f1,
                         const functionN<U1, U2, ..., UN>& 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_equal(*(f.target<Functor>()), g)`.
   Notes: | `functionN` objects are not EqualityComparable.
   Rationale: | The `safe_bool` conversion opens a loophole whereby two `functionN` 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.