# Boost.Function Reference Manual

## Header `<boost/function.hpp>` synopsis

Here `MAX_ARGS` is an implementation-defined constant that defines the maximum number of function arguments supported by Boost.Function and will be at least 10. The `MAX_ARGS` constant referred to in this document need not have any direct representation in the library.

    namespace boost {
      class function_base
      {
        typedef implementation-defined safe_bool;
        bool empty() const;
        operator safe_bool() const;
        safe_bool operator!() const;
      };

      // For N in [0, MAX_ARGS]
      template<typename ResultType,
               typename Arg1,
    	   typename Arg2,
               ...
               typename ArgN,
    	   typename Policy    = empty_function_policy,
    	   typename Mixin     = empty_function_mixin,
    	   typename Allocator = std::allocator<function_base> >
      class functionN : public function_base, public Mixin
      {
        typedef ResultType result_type; // [1]
        typedef Policy     policy_type;
        typedef Mixin      mixin_type;
        typedef Allocator  allocator_type;

        typedef Arg1 argument_type;        // If N == 1

        typedef Arg1 first_argument_type;  // If N == 2
        typedef Arg2 second_argument_type; // If N == 2

        // Construction
        explicit functionN(const Mixin& = Mixin());
        functionN(const functionN&);
        template<typename F> functionN(F, const Mixin& = Mixin());
        template<typename F> functionN(reference_wrapper<F>);

        // Assignment
        functionN& operator=(const functionN&);
        template<typename F> functionN& operator=(F);
        template<typename F> functionN& operator=(reference_wrapper<F>);
        void set(const functionN&);
        template<typename F> void set(F);
        void swap(functionN&);
        void clear();

        // Invocation
        result_type operator()(Arg1 a1, Arg2 a2, ..., ArgN aN) const;
      };

      template<typename ResultType,
               typename Arg1,
    	   typename Arg2,
               ...
    	   typename ArgN,
               typename Policy,
               typename Mixin,
               typename Allocator>
      void swap(functionN<ResultType, Arg1, Arg2, ..., ArgN, Policy, Mixin, Allocator>&,
                functionN<ResultType, Arg1, Arg2, ..., ArgN, Policy, Mixin, Allocator>&);

      // For any N in [0, MAX_ARGS]
      template<typename ResultType,
               typename Arg1,
    	   typename Arg2,
               ...
               typename ArgN,
               typename ArgN+1 = implementation-defined,
               typename ArgN+2 = implementation-defined,
    	   ...
    	   typename ArgMAX_ARGS = implementation-defined>
      class function : public functionN<ResultType, Arg1, Arg2, ..., ArgN>
      {
        // Construction
        function();
        function(const function&);
        function(const functionN<ResultType, Arg1, Arg2, ..., ArgN>&);
        template<typename F> functionN(F);

        // Assignment
        function& operator=(const function&);
        function& operator=(const functionN<ResultType, Arg1, Arg2, ..., ArgN>&);
        template<typename F> function& operator=(F);
        void set(const function&);
        void set(const functionN<ResultType, Arg1, Arg2, ..., ArgN>&);
        template<typename F> void set(F);
      };

      template<typename ResultType,
               typename Arg1,
    	   typename Arg2,
               ...
    	   typename ArgMAX_ARGS>
      void swap(function<ResultType, Arg1, Arg2, ..., ArgMAX_ARGS>&,
                function<ResultType, Arg1, Arg2, ..., ArgMAX_ARGS>&);
    }

## Definitions

- A function object `f` is compatible if for the given set of argument types `Arg1`, `Arg2`, ..., `ArgN` and a return type `ResultType`, the appropriate following function is well-formed:

        // if ResultType is not void
        ResultType foo(Arg1 arg1, Arg2 arg2, ..., ArgN argN)
        {
          return f(arg1, arg2, ..., argN);
        }

        // if ResultType is void
        ResultType foo(Arg1 arg1, Arg2 arg2, ..., ArgN argN)
        {
          f(arg1, arg2, ..., argN);
        }

  A special provision is made for pointers to member functions. Though they are not function objects, Boost.Function will adapt them internally to function objects. This requires that a pointer to member function of the form `R (X::*mf)(Arg1, Arg2, ..., ArgN) cv-quals` be adapted to a function object with the following function call operator overloads:

        template<typename P>
        R operator()(cv-quals P& x, Arg1 arg1, Arg2 arg2, ..., ArgN argN) const
        {
          return (*x).*mf(arg1, arg2, ..., argN);
        }

- A function object `f` of type `F` is stateless if it is a function pointer or if `boost::is_stateless<T>` is true. The construction of or copy to a Boost.Function object from a stateless function object will not cause exceptions to be thrown and will not allocate any storage.

## Class `function_base`

Class `function_base` is the common base class for all Boost.Function objects. Objects of type `function_base` may not be created directly.

`bool empty() const`

- Returns: `true` if the function object has a target, `false` otherwise.
- Throws: will not throw.

`operator safe_bool() const`

- Returns: `safe_bool` equivalent of `!empty()`
- Throws: will not throw.
- Notes: The `safe_bool` type can be used in contexts where a bool is expected (e.g., an if condition); however, implicit conversions (e.g., to int) that can occur with bool are not allowed, eliminating some sources of user error.

`safe_bool operator!() const`

- Returns: `safe_bool` equivalent of `empty()`
- Throws: will not throw.
- Notes: See `safe_bool` conversion

## Class template `functionN`

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 and `f` refers to the implicit object parameter.

`explicit functionN(const Mixin& = Mixin());`

- Effects: Constructs the `Mixin` subobject with the given mixin.
- Postconditions: `f.empty()`.
- Throws: will not throw unless construction of the `Mixin` subobject throws.

`functionN(const functionN& g);`

- Postconditions: `f` contains a copy of the `g`'s target, if it has one, or is empty if `g.empty()`. The mixin for the `f` is copy-constructed from the mixin of `g`.
- Throws: will not throw unless copying the target of `g` or construction of the `Mixin` subobject throws.

`template<typename F> functionN(F g, const Mixin& = Mixin());`

- Requires: `g` is a compatible function object.
- Effects: Constructs the `Mixin` subobject from the given mixin.
- Postconditions: `f` targets a copy of `g` if `g` is nonempty, or `f.empty()` if `g` is empty.
- Throws: will not throw when `g` is a stateless function object unless construction of the `Mixin` subobject throws.

`template<typename F> functionN(reference_wrapper<F> g);`

- Requires: `g.get()` is a compatible function object.
- Effects: Constructs the `Mixin` subobject from the given mixin.
- Postconditions: `this` object targets `g` (not a copy of `g.get()`) if `g.get()` is nonempty, or `this->empty()` if `g.get()` is empty.
- Throws: will not throw unless the construction of the `Mixin` subobject throws.

`functionN& operator=(const functionN& g);`

- Postconditions: `f` targets a copy of `g`'s target, if it has one, or is empty if `g.empty()`. The mixin for `f` is assigned the value of the mixin for `g`.
- Returns: `*this`.
- Throws: will not throw when the target of `g` is a stateless function object or a reference to the function object, unless the copy of the `Mixin` subobject throws.

`template<typename F> functionN& operator=(F g);`

- Requires: `g` is a compatible function object.
- Postconditions: `f` targets a copy of `g` if `g` is nonempty, or `f.empty()` if `g` is empty.
- Returns: `*this`.
- Throws: will not throw when `g` is a stateless function object.

`template<typename F> functionN& operator=(reference_wrapper<F> g);`

- Requires: `g.get()` is a compatible function object.
- Postconditions: `f` targets `g.get()` (not a copy of `g.get()`) if `g.get()` is nonempty, or `f.empty()` if `g.get()` is empty.
- Returns: `*this`.
- Throws: will throw only if the destruction or deallocation of the target of `this` throws.

`void set(const functionN& g);`

- Effects: `*this = g`.

`template<typename F> void set(F g);`

- Effects: `*this = g`.

`void swap(functionN& g);`

- Effects: interchanges the targets of `f` and `g` and swaps the mixins of `f` and `g`.
- Throws: will not throw.

`void clear();`

- Effects: If `!empty()`, deallocates current target.
- Postconditions: `empty()`.

`result_type operator()(Arg1 a1, Arg2 a2, ..., ArgN aN) const;`

- Requires: `!empty()`.
- Effects: target is the underlying function target. It is not `const` or `volatile` qualified.
  1. `policy_type policy;`
  2. `policy.precall(this);`
  3. `target(a1, a2, ..., aN);`
  4. `policy.postcall(this);`
- Returns: the value returned by target.

## Class template `function`

Class template `function` is a thin wrapper around the numbered class templates `function0`, `function1`, etc. It accepts up to MAX_ARGS arguments, but when passed N arguments it will derive from `functionN` specialized 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.

## Operations

    template<typename ResultType,
             typename Arg1,
    	 typename Arg2,
             ...
    	 typename ArgN,
             typename Policy,
             typename Mixin,
             typename Allocator>
    void swap(functionN<ResultType, Arg1, Arg2, ..., ArgN, Policy, Mixin, Allocator>& f,
              functionN<ResultType, Arg1, Arg2, ..., ArgN, Policy, Mixin, Allocator>& g);

- Effects: `f.swap(g);`

    template<typename ResultType,
             typename Arg1,
    	 typename Arg2,
             ...
    	 typename ArgMAX_ARGS>
    void swap(function<ResultType, Arg1, Arg2, ..., ArgMAX_ARGS>& f,
              function<ResultType, Arg1, Arg2, ..., ArgMAX_ARGS>& g);

- Effects: `f.swap(g);`

[1] On compilers not supporting void returns, when the `ReturnType` is void, the `result_type` of a Boost.Function object is implementation-defined.

Last modified: Thu Jan 31 21:55:35 EST 2002