function/doc/reference.xml

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
  "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">

<library-reference id="function.reference" last-revision="$Date$">

<section id="function.definitions">
  <title>Definitions</title>
<para>
  <itemizedlist>
    <listitem>
      <para>A function object <computeroutput>f</computeroutput> is
      <emphasis>compatible</emphasis> if for the given set of argument
      types <computeroutput>Arg1</computeroutput>,
      <computeroutput>Arg2</computeroutput>, ...,
      <computeroutput>ArgN</computeroutput> and a
      return type <computeroutput>ResultType</computeroutput>, the
      appropriate following function is well-formed:
<programlisting>
  <emphasis>// if ResultType is not <emphasis role="bold">void</emphasis></emphasis>
  ResultType foo(Arg1 arg1, Arg2 arg2, ..., Arg<emphasis>N</emphasis> arg<emphasis>N</emphasis>)
  {
    <emphasis role="bold">return</emphasis> f(arg1, arg2, ..., arg<emphasis>N</emphasis>);
  }

  <emphasis>// if ResultType is <emphasis role="bold">void</emphasis></emphasis>
  ResultType foo(Arg1 arg1, Arg2 arg2, ..., Arg<emphasis>N</emphasis> arg<emphasis>N</emphasis>)
  {
    f(arg1, arg2, ..., arg<emphasis>N</emphasis>);
  }
</programlisting></para>

      <para> 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 <code>R
      (X::*mf)(Arg1, Arg2, ..., ArgN)
      cv-quals</code> be adapted to a
      function object with the following function call operator
      overloads:
<programlisting>
  <emphasis role="bold">template</emphasis>&lt;<emphasis role="bold">typename P</emphasis>&gt;
  R <emphasis role="bold">operator</emphasis>()(<emphasis>cv-quals</emphasis> P&amp; x, Arg1 arg1, Arg2 arg2, ..., Arg<emphasis>N</emphasis> arg<emphasis>N</emphasis>) <emphasis role="bold">const</emphasis>
  {
    <emphasis role="bold">return</emphasis> (*x).*mf(arg1, arg2, ..., arg<emphasis>N</emphasis>);
  }
</programlisting>
</para>
    </listitem>
    <listitem>
      <para>A function object <code>f</code> of
      type <code>F</code> is
      <emphasis>stateless</emphasis> if it is a function pointer or if
      <code><classname>boost::is_stateless</classname>&lt;T&gt;</code>
      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.
      </para>
    </listitem>
  </itemizedlist>
</para>
</section>

<header name="boost/function.hpp">
<namespace name="boost">
  <class name="bad_function_call">
    <inherit access="public"><classname>std::runtime_error</classname></inherit>
    <purpose>An exception type thrown when an instance of a <code>function</code> object is empty when invoked.</purpose>
    <constructor>
      <effects><simpara>Constructs a <code><classname>bad_function_call</classname></code> exception object.</simpara></effects>
    </constructor>
  </class>

  <class name="function_base">
    <purpose>The common base class for all Boost.Function
    objects. Objects of type function_base may not be created
    directly.</purpose>

    <member-function-group name="capacity">
      <method name="empty" return-type="bool" cv="const">
        <returns><simpara><code>true</code> if <code>this</code> has a target, and <code>false</code> otherwise.</simpara></returns>
        <throws><simpara>Will not throw.</simpara></throws>
      </method>
    </member-function-group>
  </class>

  <class name="functionN">
    <template>
      <template-type-parameter name="R"/>
      <template-type-parameter name="T1"/>
      <template-type-parameter name="T2"/>
      <template-varargs/>
      <template-type-parameter name="TN"/>
      <template-type-parameter name="Allocator">
        <default><classname>std::allocator</classname>&lt;void&gt;</default>
      </template-type-parameter>
    </template>

    <inherit access="public"><classname>function_base</classname></inherit>

    <purpose>A set of generalized function pointers that can be used for callbacks or wrapping function objects.</purpose>

    <description>
      <para>Class template <classname>functionN</classname> is
      actually a family of related classes <classname
      alt="functionN">function0</classname>, <classname
      alt="functionN">function1</classname>, etc., up to some
      implementation-defined maximum. In this context, <code>N</code>
      refers to the number of parameters.</para>
    </description>

    <typedef name="result_type"><type>R</type></typedef>
    <typedef name="allocator_type"><type>Allocator</type></typedef>
    <typedef name="argument_type">
      <type>T1</type><purpose>If N == 1</purpose>
    </typedef>
    <typedef name="first_argument_type">
      <type>T1</type>
      <purpose>If N == 2</purpose>
    </typedef>
    <typedef name="second_argument_type">
      <type>T2</type>
      <purpose>If N == 2</purpose>
    </typedef>
    <typedef name="arg1_type"><type>T1</type></typedef>
    <typedef name="arg2_type"><type>T2</type></typedef>
    <typedef name="..."/>
    <typedef name="argN_type"><type>TN</type></typedef>

    <static-constant name="arity">
      <type>int</type>
      <default>N</default>
    </static-constant>

    <constructor>
      <postconditions><simpara><code>this-><methodname>empty</methodname>()</code></simpara></postconditions>
      <throws><simpara>Will not throw.</simpara></throws>
    </constructor>

    <constructor>
      <parameter name="f">
        <paramtype>const <classname>functionN</classname>&amp;</paramtype>
      </parameter>
      <postconditions><simpara>Contains a copy of the <code>f</code>'s target, if it has one, or is empty if <code>f.<methodname>empty</methodname>()</code>.</simpara></postconditions>
      <throws><simpara>Will not throw unless copying the target of <code>f</code> throws.</simpara></throws>
    </constructor>

    <constructor>
      <template>
        <template-type-parameter name="F"/>
      </template>
      <parameter name="f"><paramtype>F</paramtype></parameter>
      <requires><simpara>F is a function object Callable from <code>this</code>.</simpara></requires>
      <postconditions><simpara><code>*this</code> targets a copy of <code>f</code> if <code>f</code> is nonempty, or <code>this-&gt;<methodname>empty</methodname>()</code> if <code>f</code> is empty.</simpara></postconditions>
      <throws><simpara>Will not throw when <code>f</code> is a stateless function object.</simpara></throws>
    </constructor>

    <destructor>
      <effects><simpara>If <code>!this-><methodname>empty</methodname>()</code>, destroys the target of this.</simpara></effects>

    </destructor>

    <copy-assignment>
      <parameter name="f">
        <paramtype>const <classname>functionN</classname>&amp;</paramtype>
      </parameter>
      <postconditions><simpara><code>*this</code> targets a copy of <code>f</code>'s target, if it has one, or is empty if <code>f.<methodname>empty</methodname>()</code>.</simpara></postconditions>
      <throws><simpara>Will not throw when the target of <code>f</code> is a stateless function object or a reference to the function object.</simpara></throws>
    </copy-assignment>

    <member-function-group name="modifiers">
      <method name="swap" return-type="void">
        <parameter name="f"><paramtype>const <classname>functionN</classname>&amp;</paramtype></parameter>
        <effects><simpara>Interchanges the targets of <code>*this</code> and <code>f</code>.</simpara></effects>
        <throws><simpara>Will not throw.</simpara></throws>
      </method>

      <method name="clear" return-type="void">
        <postconditions><simpara>this-&gt;<methodname>empty</methodname>()</simpara></postconditions>
        <throws><simpara>Will not throw.</simpara></throws>
      </method>
    </member-function-group>

    <member-function-group name="capacity">
      <method name="empty" cv="const">
        <type>bool</type>
        <returns><simpara><code>true</code> if <code>this</code> has a target, and <code>false</code> otherwise.</simpara></returns>
        <throws><simpara>Will not throw.</simpara></throws>
      </method>

      <method name="conversion-operator" return-type="safe_bool" cv="const">
        <returns><simpara>A <code>safe_bool</code> that evaluates <code>false</code> in a boolean context when <code>this-&gt;<methodname>empty</methodname>()</code>, and <code>true</code> otherwise.</simpara></returns>
        <throws><simpara>Will not throw.</simpara></throws>
      </method>

      <method name="operator!" return-type="bool" cv="const">
        <returns><simpara><code>this-&gt;<methodname>empty</methodname>()</code></simpara></returns>
        <throws><simpara>Will not throw.</simpara></throws>
      </method>
    </member-function-group>

    <member-function-group name="invocation">
      <method name="operator()" return-type="result_type" cv="const">
        <parameter name="a1"><paramtype>arg1_type</paramtype></parameter>
        <parameter name="a2"><paramtype>arg2_type</paramtype></parameter>
        <parameter><paramtype>...</paramtype></parameter>
        <parameter name="aN"><paramtype>argN_type</paramtype></parameter>
        <effects><simpara><code>f(a1, a2, ..., aN)</code>, where <code>f</code> is the target of <code>*this</code>.</simpara></effects>
        <returns><simpara>if <code>R</code> is <code>void</code>, nothing is returned; otherwise, the return value of the call to <code>f</code> is returned.</simpara></returns>
        <throws><simpara><code><classname>bad_function_call</classname></code> if <code>!this-&gt;<methodname>empty</methodname>()</code>. Otherwise, may through any exception thrown by the target function <code>f</code>.</simpara></throws>
      </method>
    </member-function-group>

    <free-function-group name="specialized algorithms">
      <function name="swap" return-type="void">
        <template>
          <template-type-parameter name="T1"/>
          <template-type-parameter name="T2"/>
          <template-varargs/>
          <template-type-parameter name="TN"/>
          <template-type-parameter name="Allocator"/>
        </template>
        <parameter name="f1"><paramtype><classname>functionN</classname>&lt;T1, T2, ..., TN, Allocator&gt;&amp;</paramtype></parameter>
        <parameter name="f2"><paramtype><classname>functionN</classname>&lt;T1, T2, ..., TN, Allocator&gt;&amp;</paramtype></parameter>
        <effects><simpara><code>f1.<methodname>swap</methodname>(f2)</code></simpara></effects>
        <throws><simpara>Will not throw.</simpara></throws>
      </function>
    </free-function-group>

    <free-function-group name="undefined operators">
      <function name="operator==" return-type="void">
        <template>
          <template-type-parameter name="T1"/>
          <template-type-parameter name="T2"/>
          <template-varargs/>
          <template-type-parameter name="TN"/>
          <template-type-parameter name="Allocator1"/>
          <template-type-parameter name="U1"/>
          <template-type-parameter name="U2"/>
          <template-varargs/>
          <template-type-parameter name="UN"/>
          <template-type-parameter name="Allocator2"/>
        </template>
        <parameter name="f1"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN, Allocator1&gt;&amp;</paramtype></parameter>
        <parameter name="f2"><paramtype>const <classname>functionN</classname>&lt;U1, U2, ..., UN, Allocator2&gt;&amp;</paramtype></parameter>
        <notes><simpara>This function must be left undefined.</simpara></notes>
        <rationale><simpara>The <code>safe_bool</code> conversion opens a loophole whereby two function instances can be compared via <code>==</code>. This undefined <code>void operator ==</code> closes the loophole and ensures a compile-time or link-time error.</simpara></rationale>
      </function>

      <function name="operator!=" return-type="void">
        <template>
          <template-type-parameter name="T1"/>
          <template-type-parameter name="T2"/>
          <template-varargs/>
          <template-type-parameter name="TN"/>
          <template-type-parameter name="Allocator1"/>
          <template-type-parameter name="U1"/>
          <template-type-parameter name="U2"/>
          <template-varargs/>
          <template-type-parameter name="UN"/>
          <template-type-parameter name="Allocator2"/>
        </template>
        <parameter name="f1"><paramtype>const <classname>functionN</classname>&lt;T1, T2, ..., TN, Allocator1&gt;&amp;</paramtype></parameter>
        <parameter name="f2"><paramtype>const <classname>functionN</classname>&lt;U1, U2, ..., UN, Allocator2&gt;&amp;</paramtype></parameter>
        <notes><simpara>This function must be left undefined.</simpara></notes>
        <rationale><simpara>The <code>safe_bool</code> conversion opens a loophole whereby two function instances can be compared via <code>!=</code>. This undefined <code>void operator !=</code> closes the loophole and ensures a compile-time or link-time error.</simpara></rationale>
      </function>
    </free-function-group>
  </class>

  <class name="function">
    <template>
      <template-type-parameter name="Signature" comment="Function type R (T1, T2, ..., TN)"/>
      <template-type-parameter name="Allocator">
        <default><classname>std::allocator</classname>&lt;void&gt;</default>
      </template-type-parameter>
    </template>
    <inherit access="public"><classname>functionN</classname>&lt;R, T1, T2, ..., TN, Allocator&gt;</inherit>

    <purpose>A generalized function pointer that can be used for
    callbacks or wrapping function objects.</purpose>

    <description>
      <para>Class template <classname>function</classname> is a thin
      wrapper around the numbered class templates <classname
      alt="functionN">function0</classname>, <classname
      alt="functionN">function1</classname>, etc. It accepts a
      function type with N arguments and will will derive from
      <classname>functionN</classname> instantiated with the arguments
      it receives.</para>

      <para>The semantics of all operations in class template
      <classname>function</classname> are equivalent to that of the
      underlying <classname>functionN</classname> object, although
      additional member functions are required to allow proper copy
      construction and copy assignment of function objects.</para>
    </description>

    <typedef name="result_type"><type>R</type></typedef>
    <typedef name="allocator_type"><type>Allocator</type></typedef>
    <typedef name="argument_type">
      <type>T1</type><purpose>If N == 1</purpose>
    </typedef>
    <typedef name="first_argument_type">
      <type>T1</type>
      <purpose>If N == 2</purpose>
    </typedef>
    <typedef name="second_argument_type">
      <type>T2</type>
      <purpose>If N == 2</purpose>
    </typedef>
    <typedef name="arg1_type"><type>T1</type></typedef>
    <typedef name="arg2_type"><type>T2</type></typedef>
    <typedef name="..."/>
    <typedef name="argN_type"><type>TN</type></typedef>

    <static-constant name="arity">
      <type>int</type>
      <default>N</default>
    </static-constant>

    <constructor>
      <postconditions><simpara><code>this-><methodname>empty</methodname>()</code></simpara></postconditions>
      <throws><simpara>Will not throw.</simpara></throws>
    </constructor>

    <constructor>
      <parameter name="f">
        <paramtype>const <classname>functionN</classname>&amp;</paramtype>
      </parameter>
      <postconditions><simpara>Contains a copy of the <code>f</code>'s target, if it has one, or is empty if <code>f.<methodname>empty</methodname>()</code>.</simpara></postconditions>
      <throws><simpara>Will not throw unless copying the target of <code>f</code> throws.</simpara></throws>
    </constructor>

    <constructor>
      <parameter name="f">
        <paramtype>const <classname>function</classname>&amp;</paramtype>
      </parameter>
      <postconditions><simpara>Contains a copy of the <code>f</code>'s target, if it has one, or is empty if <code>f.<methodname>empty</methodname>()</code>.</simpara></postconditions>
      <throws><simpara>Will not throw unless copying the target of <code>f</code> throws.</simpara></throws>
    </constructor>

    <constructor>
      <template>
        <template-type-parameter name="F"/>
      </template>
      <parameter name="f"><paramtype>F</paramtype></parameter>
      <requires><simpara>F is a function object Callable from <code>this</code>.</simpara></requires>
      <postconditions><simpara><code>*this</code> targets a copy of <code>f</code> if <code>f</code> is nonempty, or <code>this-&gt;<methodname>empty</methodname>()</code> if <code>f</code> is empty.</simpara></postconditions>
      <throws><simpara>Will not throw when <code>f</code> is a stateless function object.</simpara></throws>
    </constructor>

    <destructor>
      <effects><simpara>If <code>!this-><methodname>empty</methodname>()</code>, destroys the target of <code>this</code>.</simpara></effects>

    </destructor>

    <copy-assignment>
      <parameter name="f">
        <paramtype>const <classname>functionN</classname>&amp;</paramtype>
      </parameter>
      <postconditions><simpara><code>*this</code> targets a copy of <code>f</code>'s target, if it has one, or is empty if <code>f.<methodname>empty</methodname>()</code></simpara></postconditions>
      <throws><simpara>Will not throw when the target of <code>f</code> is a stateless function object or a reference to the function object.</simpara></throws>
    </copy-assignment>

    <copy-assignment>
      <parameter name="f">
        <paramtype>const <classname>function</classname>&amp;</paramtype>
      </parameter>
      <postconditions><simpara><code>*this</code> targets a copy of <code>f</code>'s target, if it has one, or is empty if <code>f.<methodname>empty</methodname>()</code></simpara></postconditions>
      <throws><simpara>Will not throw when the target of <code>f</code> is a stateless function object or a reference to the function object.</simpara></throws>
    </copy-assignment>

    <member-function-group name="modifiers">
      <method name="swap" return-type="void">
        <parameter name="f"><paramtype>const <classname>function</classname>&amp;</paramtype></parameter>
        <effects><simpara>Interchanges the targets of <code>*this</code> and <code>f</code>.</simpara></effects>
        <throws><simpara>Will not throw.</simpara></throws>
      </method>

      <method name="clear" return-type="void">
        <postconditions><simpara><code>this-&gt;<methodname>empty</methodname>()</code></simpara></postconditions>
        <throws><simpara>Will not throw.</simpara></throws>
      </method>
    </member-function-group>

    <member-function-group name="capacity">
      <method name="empty" return-type="bool" cv="const">
        <returns><simpara><code>true</code> if <code>this</code> has a target, and <code>false</code> otherwise.</simpara></returns>
        <throws><simpara>Will not throw.</simpara></throws>
      </method>

      <method name="conversion-operator" return-type="safe_bool" cv="const">
        <returns><simpara>A <code>safe_bool</code> that evaluates <code>false</code> in a boolean context when <code>this-&gt;<methodname>empty</methodname>()</code>, and <code>true</code> otherwise.</simpara></returns>
        <throws><simpara>Will not throw.</simpara></throws>
      </method>

      <method name="operator!" return-type="bool" cv="const">
        <returns><simpara><code>this-&gt;<methodname>empty</methodname>()</code></simpara></returns>
        <throws><simpara>Will not throw.</simpara></throws>
      </method>
    </member-function-group>

    <member-function-group name="invocation">
      <method name="operator()" return-type="result_type" cv="const">
        <parameter name="a1"><paramtype>arg1_type</paramtype></parameter>
        <parameter name="a2"><paramtype>arg2_type</paramtype></parameter>
        <parameter><paramtype>...</paramtype></parameter>
        <parameter name="aN"><paramtype>argN_type</paramtype></parameter>
        <effects><simpara><code>f(a1, a2, ..., aN)</code>, where <code>f</code> is the target of <code>*this</code>.</simpara></effects>
        <returns><simpara>if <code>R</code> is <code>void</code>, nothing is returned; otherwise, the return value of the call to <code>f</code> is returned.</simpara></returns>
        <throws><simpara><code><classname>bad_function_call</classname></code> if <code>!this-&gt;<methodname>empty</methodname>()</code>. Otherwise, may through any exception thrown by the target function <code>f</code>.</simpara></throws>
      </method>
    </member-function-group>

    <free-function-group name="specialized algorithms">
      <function name="swap" return-type="void">
        <template>
          <template-type-parameter name="Signature"/>
          <template-type-parameter name="Allocator"/>
        </template>
        <parameter name="f1"><paramtype><classname>function</classname>&lt;Signature, Allocator&gt;&amp;</paramtype></parameter>
        <parameter name="f2"><paramtype><classname>function</classname>&lt;Signature, Allocator&gt;&amp;</paramtype></parameter>
        <effects><simpara><code>f1.<methodname>swap</methodname>(f2)</code></simpara></effects>
        <throws><simpara>Will not throw.</simpara></throws>
      </function>
    </free-function-group>

    <free-function-group name="undefined operators">
      <function name="operator==" return-type="void">
        <template>
          <template-type-parameter name="Signature1"/>
          <template-type-parameter name="Allocator1"/>
          <template-type-parameter name="Signature2"/>
          <template-type-parameter name="Allocator2"/>
        </template>
        <parameter name="f1"><paramtype>const <classname>function</classname>&lt;Signature1, Allocator1&gt;&amp;</paramtype></parameter>
        <parameter name="f2"><paramtype>const <classname>function</classname>&lt;Signature2, Allocator2&gt;&amp;</paramtype></parameter>
        <notes><simpara>This function must be left undefined.</simpara></notes>
        <rationale><simpara>The <code>safe_bool</code> conversion opens a loophole whereby two function instances can be compared via <code>==</code>. This undefined <code>void operator ==</code> closes the loophole and ensures a compile-time or link-time error.</simpara></rationale>
      </function>

      <function name="operator!=" return-type="void">
        <template>
          <template-type-parameter name="Signature1"/>
          <template-type-parameter name="Allocator1"/>
          <template-type-parameter name="Signature2"/>
          <template-type-parameter name="Allocator2"/>
        </template>
        <parameter name="f1"><paramtype>const <classname>function</classname>&lt;Signature1, Allocator1&gt;&amp;</paramtype></parameter>
        <parameter name="f2"><paramtype>const <classname>function</classname>&lt;Signature2, Allocator2&gt;&amp;</paramtype></parameter>
        <notes><simpara>This function must be left undefined.</simpara></notes>
        <rationale><simpara>The <code>safe_bool</code> conversion opens a loophole whereby two function instances can be compared via <code>!=</code>. This undefined <code>void operator !=</code> closes the loophole and ensures a compile-time or link-time error.</simpara></rationale>
      </function>
    </free-function-group>
  </class>
</namespace>
</header>
</library-reference>