From e8440e8855126312d568db2b7c99c4f050440999 Mon Sep 17 00:00:00 2001
From: Andrey Semashev <andrey.semashev@gmail.com>
Date: Sat, 8 Sep 2012 13:54:41 +0000
Subject: [PATCH] Added result_of usage guideline.

[SVN r80445]
---
 utility.htm | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/utility.htm b/utility.htm
index 73bd692..09a8632 100644
--- a/utility.htm
+++ b/utility.htm
@@ -230,6 +230,51 @@ typedef boost::result_of&lt;
 &gt;::type type; // type is int</pre>
                 </blockquote>
 
+                <p>The <code>result</code> template must be specialized for every valid calling signature of the function object.
+                If the <code>operator()</code> accepts arguments by (possibly <code>const</code>) reference and/or is <code>const</code>
+                qualified, the <code>result</code> specialization must take this into account. <a href="../type_traits/doc/html/index.html">Type traits</a>
+                and more generic specializations may help to reduce the number of <code>result</code> specializations. This way <code>result_of</code> users
+                will be able to specify argument types exactly according to the function object call expression. For example:</p>
+
+                <blockquote>
+                <pre>struct functor {
+    template&lt;class&gt; struct result;
+
+    // Use template parameter F to match the function object. This will allow result deduction for both const and non-const functor.
+    template&lt;class F, class T&gt;
+    struct result&lt;F(T)&gt; {
+        // When argument type is matched like above, remember that the type may be a (const-qualified) reference.
+        // Use type traits to transform the argument type.
+        typedef typename remove_cv&lt;typename remove_reference&lt;T&gt;::type&gt;::type argument_type;
+        typedef argument_type type;
+    };
+
+    // The operator can be called on both const and non-const functor. The argument can be lvalue or rvalue.
+    template&lt;class T&gt;
+    T operator()(T const&amp; x) const
+    {
+        return x;
+    }
+};
+
+// All following result_of uses are valid and result in int
+typedef boost::result_of&lt; functor(int) &gt;::type type1; // the argument is rvalue
+functor f;
+type1 r1 = f(10);
+
+typedef boost::result_of&lt; const functor(int) &gt;::type type2; // the function object is const
+const functor cf;
+type2 r2 = cf(10);
+
+typedef boost::result_of&lt; functor(int&amp;) &gt;::type type3; // the argument is lvalue
+int a = 10;
+type3 r3 = f(a);
+
+typedef boost::result_of&lt; functor(int const&amp;) &gt;::type type4; // the argument is const lvalue
+const int ca = 10;
+type4 r4 = f(ca);</pre>
+                </blockquote>
+
                 <p>Since <code>decltype</code> is a new language
                 feature recently standardized in C++11,
                 if you are writing a function object