reference.html:

- Document semantics of reference_wrapper usage

tutorial.html:
  - Add short discussion and example of ref() and cref()


[SVN r11874]

doc/reference.html

@@ -46,10 +46,12 @@
     <a href="#functionN_default"><b>explicit</b> function<i>N</i>(<b>const</b> Mixin<b>&amp;</b> = Mixin())</a>;
     <a href="#functionN_copy">function<i>N</i>(<b>const</b> function<i>N</i><b>&amp;</b>)</a>;
     <a href="#functionN_target"><b>template</b>&lt;<b>typename</b> F&gt; function<i>N</i>(<b>const</b> F<b>&amp;</b>, <b>const</b> Mixin<b>&amp;</b> = Mixin())</a>;
+    <a href="#functionN_target_ref"><b>template</b>&lt;<b>typename</b> F&gt; function<i>N</i>(reference_wrapper&lt;F&gt;)</a>;
     
     <i>// Assignment</i>
     <a href="#functionN_copy_assn">function<i>N</i><b>&amp;</b> <b>operator</b>=(<b>const</b> function<i>N</i><b>&amp;</b>)</a>;
     <a href="#functionN_target_assn"><b>template</b>&lt;<b>typename</b> F&gt; function<i>N</i><b>&amp;</b> <b>operator</b>=(<b>const</b> F<b>&amp;</b>)</a>;
+    <a href="#functionN_target_ref_assn"><b>template</b>&lt;<b>typename</b> F&gt; function<i>N</i><b>&amp;</b> <b>operator</b>=(reference_wrapper&lt;F&gt;)</a>;
     <a href="#functionN_copy_set"><b>void</b> set(<b>const</b> function<i>N</i><b>&amp;</b>)</a>;
     <a href="#functionN_target_set"><b>template</b>&lt;<b>typename</b> F&gt; <b>void</b> set(<b>const</b> F<b>&amp;</b>)</a>;
     <a href="#functionN_swap"><b>void</b> swap(function<i>N</i><b>&amp;</b>)</a>;
@@ -126,16 +128,6 @@
 </pre>
         <p> 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, ..., Arg<em>N</em>) <em>cv-quals</em></code> be adapted to a function object with the following function call operator overloads:
 <pre>
-  R <b>operator</b>()(<em>cv-quals</em> X&amp; x, Arg1 arg1, Arg2 arg2, ..., Arg<em>N</em> arg<em>N</em>) <b>const</b>
-  {
-    <b>return</b> x.*mf(arg1, arg2, ..., arg<em>N</em>);
-  }
-
-  R <b>operator</b>()(<em>cv-quals</em> X* x, Arg1 arg1, Arg2 arg2, ..., Arg<em>N</em> arg<em>N</em>) <b>const</b>
-  {
-    <b>return</b> x->*mf(arg1, arg2, ..., arg<em>N</em>);
-  }
-  
   <b>template</b>&lt;<b>typename P</b>&gt;
   R <b>operator</b>()(<em>cv-quals</em> P&amp; x, Arg1 arg1, Arg2 arg2, ..., Arg<em>N</em> arg<em>N</em>) <b>const</b>
   {
@@ -190,6 +182,14 @@
   <li><b>Rationale</b>: <code>g</code> is a reference-to-<code><b>const</b></code> 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 <code>g</code> is reference-to-<code><b>const</b></code> pointer-to-function.</li>
 </ul>
 
+<p> <a name="functionN_target_ref"><code><b>template</b>&lt;<b>typename</b> F&gt; function<i>N</i>(<a href="../../bind/ref.html">reference_wrapper</a>&lt;F&gt; g);</code></a>
+<ul>
+  <li><b>Requires</b>: <code>g.get()</code> is a <a href="#compatible">compatible</a> function object.</li>
+  <li><b>Effects</b>: Constructs the <code>Mixin</code> subobject from the given mixin.</li>
+  <li><b>Postconditions</b>: <code>this</code> object targets <code>g</code> (<em>not</em> a copy of <code>g.get()</code>) if <code>g.get()</code> is nonempty, or <code>this-&gt;empty()</code> if <code>g.get()</code> is empty.</li>
+  <li><b>Throws</b>: will not throw.</li>
+</ul>
+
 <p> <a name="functionN_copy_assn"><code>function<i>N</i><b>&amp;</b> <b>operator</b>=(<b>const</b> function<i>N</i><b>&amp;</b> g);</code></a>
 <ul>
   <li><b>Postconditions</b>: <code>f</code> targets a copy of <code>g</code>'s target, if it has one, or is empty if <code>g.<a href="#empty">empty</a>()</code>. The mixin for <code>f</code> is assigned the value of the mixin for <code>g</code>.</li>
@@ -204,6 +204,14 @@
   <li><b>Rationale</b>: <code>g</code> is a reference-to-<code><b>const</b></code> 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 <code>g</code> is reference-to-<code><b>const</b></code> pointer-to-function.</li>
 </ul>
 
+<p> <a name="functionN_target_ref_assn"><code><b>template</b>&lt;<b>typename</b> F&gt; function<i>N</i><b>&amp;</b> <b>operator</b>=(<a href="../../bind/ref.html">reference_wrapper</a>&lt;F&gt; g);</code></a>
+<ul>
+  <li><b>Requires</b>: <code>g.get()</code> is a <a href="#compatible">compatible</a> function object.</li>
+  <li><b>Postconditions</b>: <code>f</code> targets <code>g.get()</code> (not a copy of <code>g.get()</code>) if <code>g.get()</code> is nonempty, or <code>f.<a href="#empty">empty</a>()</code> if <code>g.get()</code> is empty.</li>
+  <li><b>Returns</b>: <code>*this</code>.</li>
+  <li><b>Throws</b>: will throw only if the destruction or deallocation of the target of <code>this</code> throws.</li>
+</ul>
+
 <p> <a name="functionN_copy_set"><code><b>void</b> set(<b>const</b> function<i>N</i><b>&amp;</b> g);</code></a>
 <ul>
   <li><b>Effects</b>: <code><a href="#functionN_copy_assn">*this = g</a></code>.</li>

doc/tutorial.html

@@ -97,6 +97,29 @@ object. This is often referred to as "argument binding", and is beyond the scope
   <li><a href="http://lambda.cs.utu.fi/">The Lambda library</a>. This library provides a powerful composition mechanism to construct function objects that uses very natural C++ syntax. Lambda requires a compiler that is reasonably conformant to the C++ standard. Note that it is not a Boost library.</li>
 </ul>
 
+<h3>References to Functions</h3>
+<p> In some cases it is expensive (or semantically incorrect) to have
+Boost.Function clone a function object. In such cases, it is possible
+to request that Boost.Function keep only a reference to the actual
+function object. This is done using the <a
+href="../../bind/ref.html"><code>ref</code></a> and <a
+href="../../bind/ref.html"><code>cref</code></a> functions to wrap a
+reference to a function object:
+
+<pre>
+  stateful_type a_function_object;
+  boost::function&lt;int, int&gt; f;
+  f = ref(a_function_object);
+
+  boost::function&lt;int, int&gt; f2(f);
+</pre>
+
+Here, <code>f</code> will not make a copy of
+<code>a_function_object</code>, nor will <code>f2</code> when it is
+targeted to <code>f</code>'s reference to
+<code>a_function_object</code>. Additionally, when using references to
+function objects, Boost.Function will not throw exceptions during assignment.
+ 
 <h2><a name="family">The <code>function</code> family</a></h2>
 <p> The header &lt;<a href="../../../boost/function.hpp">boost/function.hpp</a>&gt; defines the primary entry point to the function object wrappers, the class template <code>boost::function</code>. This class template is essentially a thin wrapper around a set of similar numbered function object wrappers, <code>boost::function0</code>, <code>boost::function1</code>, etc., where the number indicates the number of arguments passed to the function object target. The declaration of <code>f</code> above could also be written as:
 <pre>