[Boost-commit] svn:boost r83371 - in sandbox/type_erasure/libs/type_erasure: doc example

Subject: [Boost-commit] svn:boost r83371 - in sandbox/type_erasure/libs/type_erasure: doc example
From: steven_at_[hidden]
Date: 2013-03-09 14:03:09

Author: steven_watanabe
Date: 2013-03-09 14:03:08 EST (Sat, 09 Mar 2013)
New Revision: 83371
URL: http://svn.boost.org/trac/boost/changeset/83371

Log:
Doc restructuring.
Text files modified: 
   sandbox/type_erasure/libs/type_erasure/doc/type_erasure.qbk     |    61 ++++++++++++++++++++++++++++----------- 
   sandbox/type_erasure/libs/type_erasure/example/basic.cpp        |    45 +++++++++++++---------------            
   sandbox/type_erasure/libs/type_erasure/example/compose.cpp      |     6 ---                                     
   sandbox/type_erasure/libs/type_erasure/example/construction.cpp |    27 +----------------                       
   sandbox/type_erasure/libs/type_erasure/example/multi.cpp        |    39 +++++++++++++++++--------               
   5 files changed, 93 insertions(+), 85 deletions(-)

Modified: sandbox/type_erasure/libs/type_erasure/doc/type_erasure.qbk
==============================================================================
--- sandbox/type_erasure/libs/type_erasure/doc/type_erasure.qbk	(original)
+++ sandbox/type_erasure/libs/type_erasure/doc/type_erasure.qbk	2013-03-09 14:03:08 EST (Sat, 09 Mar 2013)
@@ -141,20 +141,18 @@
 [endsect]
 
 [section:basic Basic Usage]
-
 [import ../example/basic.cpp]
 [basic]
+[endsect]
 
 [section Composing Concepts]
 [import ../example/compose.cpp]
 [compose]
 [endsect]
 
-[section Conversions]
-[import ../example/convert.cpp]
-[convert]
-[endsect]
-
+[section:multi Functions with Multiple Arguments]
+[import ../example/multi.cpp]
+[multi]
 [endsect]
 
 [section:concept Concepts in Depth]
@@ -169,29 +167,56 @@
 [overload]
 [endsect]
 
-[section:references Using References]
-[import ../example/references.cpp]
-[references]
+[section:concept_map Concept Maps]
+[import ../example/concept_map.cpp]
+[concept_map]
+[endsect]
+
+[section:overload Associated Types]
+[import ../example/associated.cpp]
+[associated]
 [endsect]
 
-[section:multi Functions with Multiple Arguments]
-[import ../example/multi.cpp]
-[multi]
 [endsect]
 
+[section:any Using Any]
+
 [section:construction Construction]
 [import ../example/construction.cpp]
 [construction]
 [endsect]
 
-[section:concept_map Concept Maps]
-[import ../example/concept_map.cpp]
-[concept_map]
+[section Conversions]
+[import ../example/convert.cpp]
+[convert]
 [endsect]
 
-[section:overload Associated Types]
-[import ../example/associated.cpp]
-[associated]
+[section:references References]
+[import ../example/references.cpp]
+[references]
+[endsect]
+
+[section:limit Syntax Limitations]
+
+In most cases using an any has the same
+syntax as using the underlying object.
+However, there are a few cases where
+this is not possible to implement.
+An __any reference is proxy and cannot
+be used in contexts where a real
+reference is required.  In particular,
+__forward_iterator does not create
+a conforming ForwardIterator (unless
+the value_type is fixed.)  Another
+difference is that all operations
+which do not take at least one __any
+argument have to be passed the type
+information explicitly.  Static member
+functions and constructors can fall in
+this category.  All this means that generic
+algorithms might not work when applied to
+__any arguments.
+
 [endsect]
 
 [endsect]

Modified: sandbox/type_erasure/libs/type_erasure/example/basic.cpp
==============================================================================
--- sandbox/type_erasure/libs/type_erasure/example/basic.cpp	(original)
+++ sandbox/type_erasure/libs/type_erasure/example/basic.cpp	2013-03-09 14:03:08 EST (Sat, 09 Mar 2013)
@@ -123,34 +123,31 @@
     For free functions, we can use the macro __BOOST_TYPE_ERASURE_FREE.
 */
 
-BOOST_TYPE_ERASURE_FREE((has_swap), swap, 2);
-template<class T = _self>
-struct swappable : mpl::vector<has_swap<void(T&, T&)> > {};
+BOOST_TYPE_ERASURE_FREE((has_getline), getline, 2)
+std::vector<std::string> read_lines(any<has_getline<bool(_self&, std::string&)>, _self&> stream)
+{
+    std::vector<std::string> result;
+    std::string tmp;
+    while(getline(stream, tmp))
+        result.push_back(tmp);
+    return result;
+}
 
 /*`
-    The use of `has_swap` is essentially similar to `has_push_back`.
-    We have to pass it the function signature.  In this case, however,
-    the signature has one extra twist.  We use the __placeholder `_self`
-    to indicate which arguments of `swap` should be __any's.
-    
-    Now, swap should always have the same signature.  It should
-    always look like `has_swap<void(_self&, _self&)>`, since `swap`
-    takes two arguments of the same type by reference.  Thus,
-    we define `swappable<>` as a convenient short-cut.
-
-    [note We could define `swappable` to be a typedef of
-    `has_swap<void(_self&, _self&)>`, but `_self` is not the only
-    __placeholder.  We can use another __placeholder instead.  The
-    library doesn't care what placeholder we use as long as we're consistent.
-    So, if we wanted to use `_a`, we'd have to write `any<swappable<_a>, _a&>`.
-    Neither `any<swappable<_self>, _a&>` nor `any<swappable<_a>, _self&>`
-    would work.]
-
-    [warning Do not try to make one concept inherit directly from
-    another.  The use of `mpl::vector` is necessary for the library
-    to understand the relationship between the two concepts.]
+    The use of `has_getline` is very similar to `has_push_back` above.
+    The difference is that the placeholder `_self` is passed in
+    the function signature instead of as a separate argument.
+
+    The __placeholder doesn't have to be the first argument.
+    We could just as easily make it the second argument.
 */
 
+
+void read_line(any<has_getline<bool(std::istream&, _self&)>, _self&> str)
+{
+    getline(std::cin, str);
+}
+
 //]
 
 //[basic

Modified: sandbox/type_erasure/libs/type_erasure/example/compose.cpp
==============================================================================
--- sandbox/type_erasure/libs/type_erasure/example/compose.cpp	(original)
+++ sandbox/type_erasure/libs/type_erasure/example/compose.cpp	2013-03-09 14:03:08 EST (Sat, 09 Mar 2013)
@@ -17,11 +17,7 @@
 
 //[compose1
 /*`
-    The use of `mpl::vector` for concept inheritence
-    can be generalized to define a concept that
-    is composed of multiple other concepts.  The
-    MPL sequence can contain as many concepts as
-    we need.
+    Multiple concepts can be composed using an MPL sequence.
 */
 template<class T = _self>
 struct arithmetic :

Modified: sandbox/type_erasure/libs/type_erasure/example/construction.cpp
==============================================================================
--- sandbox/type_erasure/libs/type_erasure/example/construction.cpp	(original)
+++ sandbox/type_erasure/libs/type_erasure/example/construction.cpp	2013-03-09 14:03:08 EST (Sat, 09 Mar 2013)
@@ -34,29 +34,6 @@
         constructible<_a(const _b&, const _c&)>
     > construct;
 
-    std::vector<double> vec;
-    int i = 10;
-    double d = 2.5;
-    tuple<construct, _a&, _b, _c> t(vec, i, d);
-    any<construct, _a> v(get<1>(t), get<2>(t));
-    // v holds std::vector<double>(10, 2.5);
-    //]
-}
-
-void construction2() {
-    typedef mpl::vector<
-        copy_constructible<_a>,
-        copy_constructible<_b>,
-        copy_constructible<_c>,
-        constructible<_a(const _b&, const _c&)>
-    > construct;
-    //[construction2
-    /*`
-        This requires us to create a vector to deduce
-        its type, even though the object is never used.
-        Instead, we can explicitly specify the types
-        that the placeholders should be bound to.
-    */
     typedef mpl::map<
         mpl::pair<_a, std::vector<double> >,
         mpl::pair<_b, std::size_t>,
@@ -66,6 +43,7 @@
     any<construct, _b> size(std::size_t(10), make_binding<types>());
     any<construct, _c> val(2.5, make_binding<types>());
     any<construct, _a> v(size, val);
+    // v holds std::vector<double>(10, 2.5);
     //]
 }
 
@@ -85,7 +63,7 @@
     > construct;
 
     any<construct> x(std::string("Test"));
-    any<construct> y(binding_of(x));
+    any<construct> y(binding_of(x)); // y == ""
     //]
 }
 
@@ -110,7 +88,6 @@
 //` (For the source of the examples in this section see
 //` [@boost:/libs/type_erasure/example/construction.cpp construction.cpp])
 //` [construction1]
-//` [construction2]
 //` [construction3]
 //` [construction4]
 //]

Modified: sandbox/type_erasure/libs/type_erasure/example/multi.cpp
==============================================================================
--- sandbox/type_erasure/libs/type_erasure/example/multi.cpp	(original)
+++ sandbox/type_erasure/libs/type_erasure/example/multi.cpp	2013-03-09 14:03:08 EST (Sat, 09 Mar 2013)
@@ -38,8 +38,13 @@
     any_type z(x + y);
     std::cout << z << std::endl; // prints 17
     /*`
-        The underlying types of the arguments of `+` must match or the
-        behavior is undefined.
+        This is /not/ a multimethod.  The underlying types of the
+        arguments of `+` must be the same or the behavior is undefined.
+        This example is correct because the arguments both hold
+        `int`'s.
+
+        [note Adding __relaxed leads an exception rather than undefined
+        behavior if the argument types are wrong.]
     */
     //]
 }
@@ -47,11 +52,15 @@
 void multi2() {
     //[multi2
     /*`
-        __addable`<>` requires the types of the arguments to be
-        the same.  We can also capture relationships among several types.
-        To do this we'll need to identify each type with a
-        __placeholder.
+        __addable`<>` requires the types of the arguments to be exactly
+        the same.  This doesn't cover all uses of addition though.  For
+        example, pointer arithmetic takes a pointer and an integer and
+        returns a pointer.  We can capture this kind of relationship among
+        several types by identifying each type involved with a placeholder.
+        We'll let the placeholder `_a` represent the pointer and the
+        placeholder `_b` represent the integer.
     */
+
     int array[5];
 
     typedef mpl::vector<
@@ -62,6 +71,9 @@
     > requirements;
 
     /*`
+        Our new concept, `addable<_a, _b, _a>` captures the
+        rules of pointer addition: `_a + _b -> _a`.
+
         Also, we can no longer capture the variables
         independently.
         ``
@@ -75,19 +87,20 @@
      */
 
     typedef mpl::map<mpl::pair<_a, int*>, mpl::pair<_b, int> > types; 
-    any<requirements, _a> ptr(&array[0], static_binding<types>());
-    any<requirements, _b> idx(2, static_binding<types>());
+    any<requirements, _a> ptr(&array[0], make_binding<types>());
+    any<requirements, _b> idx(2, make_binding<types>());
     any<requirements, _a> x(ptr + idx);
     // x now holds array + 2
 
     /*`
-        Here the arguments of `+` are no longer the same.
-        What we require is that the dynamic bindings of
-        the two arguments to `+` must map the placeholders
-        `_a` and `_b` to the same types.
+        Now that the arguments of `+` aren't the same type,
+        we require that both arguments agree that `_a` maps
+        to `int*` and that `_b` maps to `int`.
 
         We can also use __tuple to avoid having to
-        write out the map out explicitly.
+        write out the map out explicitly.  __tuple is
+        just a convienience class that combines the
+        placeholder bindings it gets from all its arguments.
      */
     tuple<requirements, _a, _b> t(&array[0], 2);
     any<requirements, _a> y(get<0>(t) + get<1>(t));