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));