Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. — Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

PrevUpHomeNext

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.
Copyright © 2001-2004 Douglas Gregor

Use, modification and distribution is subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

PrevUpHomeNext