Boost logo

Boost-Commit :

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


Author: steven_watanabe
Date: 2013-03-01 20:03:12 EST (Fri, 01 Mar 2013)
New Revision: 83237
URL: http://svn.boost.org/trac/boost/changeset/83237

Log:
Doc update
Text files modified:
   sandbox/type_erasure/boost/type_erasure/any.hpp | 2
   sandbox/type_erasure/boost/type_erasure/builtin.hpp | 11 ++++++++
   sandbox/type_erasure/boost/type_erasure/callable.hpp | 29 ++++++++++++++++-------
   sandbox/type_erasure/boost/type_erasure/constructible.hpp | 7 ++++
   sandbox/type_erasure/boost/type_erasure/iterator.hpp | 24 ++++++++++++++++++
   sandbox/type_erasure/boost/type_erasure/param.hpp | 2
   sandbox/type_erasure/libs/type_erasure/doc/type_erasure.qbk | 10 +++++++
   sandbox/type_erasure/libs/type_erasure/example/basic.cpp | 50 +++++++++++++++++++++++----------------
   8 files changed, 100 insertions(+), 35 deletions(-)

Modified: sandbox/type_erasure/boost/type_erasure/any.hpp
==============================================================================
--- sandbox/type_erasure/boost/type_erasure/any.hpp (original)
+++ sandbox/type_erasure/boost/type_erasure/any.hpp 2013-03-01 20:03:12 EST (Fri, 01 Mar 2013)
@@ -119,7 +119,7 @@
 /**
  * The class template @ref any can store any object that
  * models a specific @c Concept. It dispatches all
- * the function defined by the @c Concept to the contained type
+ * the functions defined by the @c Concept to the contained type
  * at runtime.
  *
  * \tparam Concept The concept that the type should model.

Modified: sandbox/type_erasure/boost/type_erasure/builtin.hpp
==============================================================================
--- sandbox/type_erasure/boost/type_erasure/builtin.hpp (original)
+++ sandbox/type_erasure/boost/type_erasure/builtin.hpp 2013-03-01 20:03:12 EST (Fri, 01 Mar 2013)
@@ -29,6 +29,10 @@
  * \note The @ref destructible concept rarely needs to
  * be specified explicitly, because it is included in
  * the @ref copy_constructible concept.
+ *
+ * \note @ref destructible may not be specialized and
+ * may not be passed to \call as it depends on the
+ * implementation details of @ref any.
  */
 template<class T = _self>
 struct destructible
@@ -84,6 +88,13 @@
 /**
  * Enables runtime type information. This is required
  * if you want to use \any_cast or \typeid_of.
+ *
+ * \note @ref typeid_ cannot be specialized because several
+ * library components including \any_cast would not work
+ * correctly if its behavior changed. There is no need
+ * to specialize it anyway, since it works for all types.
+ * @ref typeid_ also cannot be passed to \call. To access it,
+ * use \typeid_of.
  */
 template<class T = _self>
 struct typeid_

Modified: sandbox/type_erasure/boost/type_erasure/callable.hpp
==============================================================================
--- sandbox/type_erasure/boost/type_erasure/callable.hpp (original)
+++ sandbox/type_erasure/boost/type_erasure/callable.hpp 2013-03-01 20:03:12 EST (Fri, 01 Mar 2013)
@@ -33,6 +33,18 @@
 namespace boost {
 namespace type_erasure {
 
+template<class Sig, class F = _self>
+struct callable;
+
+namespace detail {
+
+template<class Sig>
+struct result_of_callable;
+
+}
+
+#if defined(BOOST_TYPE_ERASURE_DOXYGEN)
+
 /**
  * The @ref callable concept allows an @ref any to hold function objects.
  * @c Sig is interpreted in the same way as for Boost.Function, except
@@ -46,16 +58,15 @@
  * support @c boost::result_of.
  */
 template<class Sig, class F = _self>
-struct callable {};
-
-namespace detail {
-
-template<class Sig>
-struct result_of_callable;
-
-}
+struct callable
+{
+ /**
+ * @c R is the result type of @c Sig and @c T is the argument
+ * types of @c Sig.
+ */
+ static R apply(F& f, T... arg);
+};
 
-#if defined(BOOST_TYPE_ERASURE_DOXYGEN)
 #elif !defined(BOOST_NO_VARIADIC_TEMPLATES) && !defined(BOOST_NO_RVALUE_REFERENCES)
 
 template<class R, class... T, class F>

Modified: sandbox/type_erasure/boost/type_erasure/constructible.hpp
==============================================================================
--- sandbox/type_erasure/boost/type_erasure/constructible.hpp (original)
+++ sandbox/type_erasure/boost/type_erasure/constructible.hpp 2013-03-01 20:03:12 EST (Fri, 01 Mar 2013)
@@ -50,7 +50,12 @@
  * @c Sig should be a function signature. The return
  * type is the placeholder specifying the type to
  * be constructed. The arguments are the argument
- * types of the constructor.
+ * types of the constructor. The arguments of
+ * @c Sig may be placeholders.
+ *
+ * \note @ref constructible may not be specialized and
+ * may not be passed to \call as it depends on the
+ * implementation details of @ref any.
  */
 template<class Sig>
 struct constructible {};

Modified: sandbox/type_erasure/boost/type_erasure/iterator.hpp
==============================================================================
--- sandbox/type_erasure/boost/type_erasure/iterator.hpp (original)
+++ sandbox/type_erasure/boost/type_erasure/iterator.hpp 2013-03-01 20:03:12 EST (Fri, 01 Mar 2013)
@@ -60,6 +60,28 @@
 
 #ifdef BOOST_TYPE_ERASURE_DOXYGEN
 
+/**
+ * The @ref iterator concept can be used for any iterator category.
+ *
+ * \tparam Traversal must be one of @c boost::incrementable_traversal_tag,
+ * @c boost::single_pass_traversal_tag, @c boost::forward_traversal_tag,
+ * @c boost::bidirectional_traversal_tag, and @c boost::random_access_traversal_tag.
+ * \tparam T The placeholder representing the iterator.
+ * \tparam Reference The reference type. If it is boost::use_default, then
+ * reference will be value_type&.
+ * \tparam DifferenceType The iterator's difference type.
+ *
+ * The value_type of the iterator is deduced. To force it to be
+ * a specific type, use the @ref same_type concept.
+ *
+ * Example:
+ *
+ * \code
+ * mpl::vector<
+ * iterator<boost::forward_traversal_tag>,
+ * same_type<iterator<boost::forward_traversal_tag>::value_type, int> > int_it;
+ * \endcode
+ */
 template<
     class Traversal,
     class T = _self,
@@ -68,7 +90,7 @@
>
 struct iterator
 {
- typedef ValueType value_type;
+ typedef detail::unspecified value_type;
     typedef Reference reference;
     typedef DifferenceType difference_type;
 };

Modified: sandbox/type_erasure/boost/type_erasure/param.hpp
==============================================================================
--- sandbox/type_erasure/boost/type_erasure/param.hpp (original)
+++ sandbox/type_erasure/boost/type_erasure/param.hpp 2013-03-01 20:03:12 EST (Fri, 01 Mar 2013)
@@ -97,7 +97,7 @@
  * and base placeholder when there exists a corresponding
  * standard conversion for the placeholder.
  * A conversion sequence from @ref any<C, P> to @ref param<C, P1> is
- * a better conversion sequence than @ref any<C, P> to @ref param<C, C2>
+ * a better conversion sequence than @ref any<C, P> to @ref param<C, P2>
  * iff the corresponding placeholder standard conversion
  * sequence from P to P1 is a better conversion sequence than
  * P to P2.

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-01 20:03:12 EST (Fri, 01 Mar 2013)
@@ -1,7 +1,7 @@
 [library Boost.TypeErasure
     [quickbook 1.5]
     [authors [Watanabe, Steven]]
- [copyright 2011 Steven Watanabe]
+ [copyright 2011-2013 Steven Watanabe]
     [license
         Distributed under the Boost Software License, Version 1.0.
         (See accompanying file LICENSE_1_0.txt or copy at
@@ -308,6 +308,14 @@
 operators always return bool, and references will be
 added to the arguments and results as appropriate.
 
+Except as otherwise noted, primitive concepts defined by
+the library can be specialized to provide concept maps.
+__copy_constructible, and the iterator concepts cannot
+be specialized because they are composites. __constructible,
+__destructible, __typeid_, and __same_type cannot be
+specialized because they require special handling in
+the library.
+
 [table:special Special Members
     [[concept][notes]]
     [[__constructible`<Sig>`][-]]

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-01 20:03:12 EST (Fri, 01 Mar 2013)
@@ -31,12 +31,15 @@
         In the rare case when we only want a single concept, it doesn't
         need to be wrapped in an MPL sequence.]
     */
- any<mpl::vector<copy_constructible<>, typeid_<> > > x(10);
+ any<mpl::vector<copy_constructible<>, typeid_<>, relaxed_match> > x(10);
     int i = any_cast<int>(x); // i == 10
     /*`
         __copy_constructible is a builtin concept that allows us to
         copy and destroy the object. __typeid_ provides run-time
- type information so that we can use __any_cast.
+ type information so that we can use __any_cast. __relaxed_match
+ enables various useful defaults. Without __relaxed_match,
+ __any supports /exactly/ what you specify and nothing else.
+ In particular, it allows default construction and assignment of __any.
      */
     //]
 }
@@ -78,14 +81,15 @@
 }
 
 /*`
- There are a few things to note about this. First,
- we use the macro __BOOST_TYPE_ERASURE_MEMBER to
- define a concept called `has_push_back` for a
- unary member function called `push_back`.
- When we use `has_push_back`, we have to
- give it the signature of the function, `void(int)`.
- This means that we expect to find a function
- that looks like:
+ We use the macro __BOOST_TYPE_ERASURE_MEMBER
+ to define a concept called `has_push_back`.
+ The second parameter is the name of the member
+ function and the last macro parameter indicates
+ the number of arguments which is `1` since `push_back`
+ is unary. When we use `has_push_back`, we have to
+ tell it the signature of the function, `void(int)`.
+ This means that the type we store in the any
+ has to have a member that looks like:
 
     ``
     void push_back(int);
@@ -96,18 +100,19 @@
     convertible to `long`), but not `std::list<std::string>`
     or `std::set<int>`.
 
- Also, note the use of `_self&` as the second argument of
- __any. `_self` is a __placeholder. By using `_self&`,
- we indicate that the __any stores a reference
- to another object instead of owning its own object.
+ Also, note that `append_many` has to operate directly
+ on its argument. It cannot make a copy. To handle this
+ we use `_self&` as the second argument of __any. `_self`
+ is a __placeholder. By using `_self&`, we indicate that
+ the __any stores a reference to an external object instead of
+ allocating its own object.
 */
 
 /*`
- The concepts created by __BOOST_TYPE_ERASURE_MEMBER take
- a __placeholder as an optional second parameter. This
- __placeholder defaults to `_self`. If we wanted to use a
- different placeholder or have a constant member function,
- we'd have to specify it explicitly.
+ There's actually another __placeholder here. The second
+ parameter of `has_push_back` defaults to `_self`. If
+ we wanted to define a const member function, we would
+ have to change it to `const _self`, as shown below.
  */
 BOOST_TYPE_ERASURE_MEMBER((has_empty), empty, 0)
 bool is_empty(any<has_empty<bool(), const _self>, const _self&> x) {
@@ -135,8 +140,11 @@
 
     [note We could define `swappable` to be a typedef of
     `has_swap<void(_self&, _self&)>`, but `_self` is not the only
- __placeholder. We could use `_a` instead as long as
- we substitute it uniformly like `any<swappable<_a>, _a&>`]
+ __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


Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk