# 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
      {
        bool empty() const;
        operator bool() 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;
        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(const F&, const Mixin& = Mixin());

        // Assignment
        functionN& operator=(const functionN&);
        template<typename F> functionN& operator=(const F&);
        void set(const functionN&);
        template<typename F> void set(const 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(const function<Arg1, Arg2, ..., ArgN, Policy, Mixin, Allocator>&,
                const function<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<Arg1, Arg2, ..., ArgN>
      {
        // Construction
        function();
        function(const function&);
        functionN(const functionN&);
        template<typename F> functionN(const F&);

        // Assignment
        function& operator=(const function&);
        functionN& operator=(const functionN&);
        template<typename F> function& operator=(const F&);
        void set(const function&);
        void set(const functionN&);
        template<typename F> void set(const F&);
      };

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

## 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 bool() const`

- Returns: `!empty()`
- Throws: will not throw.

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

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

`template<typename F> functionN(const 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.
- Rationale: `g` is a reference-to-`const` because it is a portable, efficient, and concise way to accept any function object or function pointer. In the case of a function pointer, the type of `g` is reference-to-`const` pointer-to-function.

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

`template<typename F> functionN& operator=(const 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`.
- Rationale: `g` is a reference-to-`const` because it is a portable, efficient, and concise way to accept any function object or function pointer. In the case of a function pointer, the type of `g` is reference-to-`const` pointer-to-function.

`void set(const functionN& g);`

- Effects: `*this = g`.

`template<typename F> void set(const 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(const functionN<Arg1, Arg2, ..., ArgN, Policy, Mixin, Allocator>& f,
              const functionN<Arg1, Arg2, ..., ArgN, Policy, Mixin, Allocator>& g);

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

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

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

Last modified: Sun Jul 22 01:29:50 EDT 2001