| 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

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

      // invocation
      result_type operator()(arg1_type, arg2_type, ..., argN_type) const;
    };

    // specialized algorithms
    template<typename T1, typename T2, ..., typename TN, typename Allocator>
      void swap(functionN<T1, T2, ..., TN, Allocator>&,
                functionN<T1, T2, ..., TN, Allocator>&);

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

## 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` 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.     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.
   Throws: Will not throw when `f` is a stateless function object.

4.     functionN& 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.

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

2.     void clear();

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

### `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)`

### `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, typename Allocator>
         void swap(functionN<T1, T2, ..., TN, Allocator>& f1,
                   functionN<T1, T2, ..., TN, Allocator>& f2);

   Effects: `f1.swap(f2)`
   Throws: Will not throw.

### `functionN` comparison operators

1.     template<typename T1, typename T2, ..., typename TN, typename Allocator,
                typename Functor>
         bool operator==(const functionN<T1, T2, ..., TN, Allocator>& f, Functor g);
       template<typename T1, typename T2, ..., typename TN, typename Allocator,
                typename Functor>
         bool operator==(Functor g, const functionN<T1, T2, ..., TN, Allocator>& f);
       template<typename T1, typename T2, ..., typename TN, typename Allocator,
                typename Functor>
         bool operator==(const functionN<T1, T2, ..., TN, Allocator>& f,
                         reference_wrapper<Functor> g);
       template<typename T1, typename T2, ..., typename TN, typename Allocator,
                typename Functor>
         bool operator==(reference_wrapper<Functor> g,
                         const functionN<T1, T2, ..., TN, Allocator>& f);
       template<typename T1, typename T2, ..., typename TN, typename Allocator1,
                typename U1, typename U2, ..., typename UN, typename Allocator2>
         void operator==(const functionN<T1, T2, ..., TN, Allocator1>& f1,
                         const functionN<U1, U2, ..., UN, Allocator2>& 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 Allocator,
                typename Functor>
         bool operator!=(const functionN<T1, T2, ..., TN, Allocator>& f, Functor g);
       template<typename T1, typename T2, ..., typename TN, typename Allocator,
                typename Functor>
         bool operator!=(Functor g, const functionN<T1, T2, ..., TN, Allocator>& f);
       template<typename T1, typename T2, ..., typename TN, typename Allocator,
                typename Functor>
         bool operator!=(const functionN<T1, T2, ..., TN, Allocator>& f,
                         reference_wrapper<Functor> g);
       template<typename T1, typename T2, ..., typename TN, typename Allocator,
                typename Functor>
         bool operator!=(reference_wrapper<Functor> g,
                         const functionN<T1, T2, ..., TN, Allocator>& f);
       template<typename T1, typename T2, ..., typename TN, typename Allocator1,
                typename U1, typename U2, ..., typename UN, typename Allocator2>
         void operator!=(const functionN<T1, T2, ..., TN, Allocator1>& f1,
                         const functionN<U1, U2, ..., UN, 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:

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

| Copyright © 2001-2004 Douglas Gregor