Subject: [Boost-commit] svn:boost r80974 - in sandbox/type_erasure: boost/type_erasure libs/type_erasure/doc libs/type_erasure/example
From: steven_at_[hidden]
Date: 2012-10-12 20:02:26
Author: steven_watanabe
Date: 2012-10-12 20:02:25 EDT (Fri, 12 Oct 2012)
New Revision: 80974
URL: http://svn.boost.org/trac/boost/changeset/80974
Log:
Doc update
Text files modified:
sandbox/type_erasure/boost/type_erasure/any_cast.hpp | 8 +----
sandbox/type_erasure/boost/type_erasure/builtin.hpp | 2
sandbox/type_erasure/boost/type_erasure/call.hpp | 6 ++--
sandbox/type_erasure/boost/type_erasure/concept_interface.hpp | 19 +++++++++++----
sandbox/type_erasure/boost/type_erasure/derived.hpp | 2 +
sandbox/type_erasure/boost/type_erasure/exception.hpp | 10 +++++++
sandbox/type_erasure/boost/type_erasure/require_match.hpp | 2
sandbox/type_erasure/libs/type_erasure/doc/Jamfile.jam | 6 ++++
sandbox/type_erasure/libs/type_erasure/doc/type_erasure.qbk | 1
sandbox/type_erasure/libs/type_erasure/example/basic.cpp | 50 ++++++++++++++++++++++++---------------
sandbox/type_erasure/libs/type_erasure/example/compose.cpp | 16 ++++--------
sandbox/type_erasure/libs/type_erasure/example/custom.cpp | 35 ++++++++++++++-------------
sandbox/type_erasure/libs/type_erasure/example/overload.cpp | 8 +----
sandbox/type_erasure/libs/type_erasure/example/printf.cpp | 2
14 files changed, 96 insertions(+), 71 deletions(-)
Modified: sandbox/type_erasure/boost/type_erasure/any_cast.hpp
==============================================================================
--- sandbox/type_erasure/boost/type_erasure/any_cast.hpp (original)
+++ sandbox/type_erasure/boost/type_erasure/any_cast.hpp 2012-10-12 20:02:25 EDT (Fri, 12 Oct 2012)
@@ -23,6 +23,7 @@
#include <boost/mpl/bool.hpp>
#include <boost/type_erasure/any.hpp>
#include <boost/type_erasure/builtin.hpp>
+#include <boost/type_erasure/exception.hpp>
#include <boost/type_erasure/detail/access.hpp>
namespace boost {
@@ -92,13 +93,8 @@
}
/**
- * Exception thrown when an any_cast to a reference or value fails.
- */
-class bad_any_cast : public std::bad_cast {};
-
-/**
* Attempts to extract the object that @c arg holds.
- * If casting to a pointer fails, @ref any_cast returns
+ * If casting to a pointer fails, \any_cast returns
* a null pointer. Casting to @c void* always succeeds
* and returns the address of stored object.
*
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 2012-10-12 20:02:25 EDT (Fri, 12 Oct 2012)
@@ -83,7 +83,7 @@
/**
* Enables runtime type information. This is required
- * if you want to use @ref any_cast or @ref typeid_of.
+ * if you want to use \any_cast or \typeid_of.
*/
template<class T = _self>
struct typeid_
Modified: sandbox/type_erasure/boost/type_erasure/call.hpp
==============================================================================
--- sandbox/type_erasure/boost/type_erasure/call.hpp (original)
+++ sandbox/type_erasure/boost/type_erasure/call.hpp 2012-10-12 20:02:25 EDT (Fri, 12 Oct 2012)
@@ -137,9 +137,9 @@
*
* @c Op must be a primitive concept which is present in
* @c Concept. Its signature determines how the arguments of
- * @ref call are handled. If the argument is a @ref placeholder,
- * @ref call expects an @ref any using that @ref placeholder.
- * This @ref any is unwrapped by @ref call. The type that
+ * \call are handled. If the argument is a @ref placeholder,
+ * \call expects an @ref any using that @ref placeholder.
+ * This @ref any is unwrapped by \call. The type that
* it stores must be the same type specified by @c binding.
* Any arguments that are not placeholders in the signature
* of @c Op are passed through unchanged.
Modified: sandbox/type_erasure/boost/type_erasure/concept_interface.hpp
==============================================================================
--- sandbox/type_erasure/boost/type_erasure/concept_interface.hpp (original)
+++ sandbox/type_erasure/boost/type_erasure/concept_interface.hpp 2012-10-12 20:02:25 EDT (Fri, 12 Oct 2012)
@@ -16,24 +16,33 @@
/**
* The @ref concept_interface class can be specialized to
- * add behavior to an @ref any.
+ * add behavior to an @ref any. An @ref any inherits from
+ * all the relevant specializations of @ref concept_interface.
*
* @ref concept_interface can be specialized for either
* primitive or composite concepts. If a concept @c C1
* contains another concept @c C2, then the library guarantees
* that the specialization of @ref concept_interface for
- * C2 is a base class of the specialization for C1.
- * This means that C1 can safely override members of C2.
+ * @c C2 is a base class of the specialization for @c C1.
+ * This means that @c C1 can safely override members of @c C2.
+ *
+ * @ref concept_interface may only be specialized for user-defined
+ * concepts. The library owns the specializations of its own
+ * built in concepts.
*
* \tparam Concept The concept that we're specializing
* @ref concept_interface for. One of its
* placeholders should be @c ID.
* \tparam Base The base of this class. Specializations of @ref
* concept_interface must inherit publicly from this type.
- * The metafunctions @ref derived and @ref rebind_any
- * can also be applied to @c Base.
* \tparam ID The placeholder representing this type.
* \tparam Enable A dummy parameter that can be used for SFINAE.
+ *
+ * The metafunctions @ref derived, @ref rebind_any, and @ref as_param
+ * (which can be applied to @c Base) are useful for determining the
+ * argument and return types of functions defined in @ref concept_interface.
+ *
+ * For dispatching the function use \call.
*/
template<class Concept, class Base, class ID, class Enable = void>
struct concept_interface : Base {};
Modified: sandbox/type_erasure/boost/type_erasure/derived.hpp
==============================================================================
--- sandbox/type_erasure/boost/type_erasure/derived.hpp (original)
+++ sandbox/type_erasure/boost/type_erasure/derived.hpp 2012-10-12 20:02:25 EDT (Fri, 12 Oct 2012)
@@ -18,6 +18,8 @@
* A metafunction which returns the full @ref any type,
* when given any of its base classes. This is primarily
* intended to be used when implementing @ref concept_interface.
+ *
+ * \see rebind_any, as_param
*/
template<class T>
struct derived
Modified: sandbox/type_erasure/boost/type_erasure/exception.hpp
==============================================================================
--- sandbox/type_erasure/boost/type_erasure/exception.hpp (original)
+++ sandbox/type_erasure/boost/type_erasure/exception.hpp 2012-10-12 20:02:25 EDT (Fri, 12 Oct 2012)
@@ -19,12 +19,20 @@
/**
* Exception thrown when the arguments to a primitive concept
* are incorrect.
+ *
+ * \see \call, \require_match
*/
-struct bad_function_call : ::std::invalid_argument
+class bad_function_call : public ::std::invalid_argument
{
+public:
bad_function_call() : ::std::invalid_argument("bad_function_call") {}
};
+/**
+ * Exception thrown when an \any_cast to a reference or value fails.
+ */
+class bad_any_cast : public std::bad_cast {};
+
}
}
Modified: sandbox/type_erasure/boost/type_erasure/require_match.hpp
==============================================================================
--- sandbox/type_erasure/boost/type_erasure/require_match.hpp (original)
+++ sandbox/type_erasure/boost/type_erasure/require_match.hpp 2012-10-12 20:02:25 EDT (Fri, 12 Oct 2012)
@@ -47,7 +47,7 @@
* If @c binding is not specified, it will be deduced from
* the arguments.
*
- * \post @c call(binding, concept, args...) is valid.
+ * \post \call<code>(binding, f, args...)</code> is valid.
*/
template<class Concept, class Op, class... U>
void require_match(const binding<Concept>& binding_arg, const Op& f, U&&... args);
Modified: sandbox/type_erasure/libs/type_erasure/doc/Jamfile.jam
==============================================================================
--- sandbox/type_erasure/libs/type_erasure/doc/Jamfile.jam (original)
+++ sandbox/type_erasure/libs/type_erasure/doc/Jamfile.jam 2012-10-12 20:02:25 EDT (Fri, 12 Oct 2012)
@@ -30,7 +30,11 @@
:
<doxygen:param>EXPAND_ONLY_PREDEF=YES
<doxygen:param>"ALIASES= \\
- CopyConstructible=\"<a href=\\\"$(BOOST_ROOT)/doc/html/CopyConstructible.html\\\">CopyConstructible</a>\" "
+ CopyConstructible=\"<a href=\\\"$(BOOST_ROOT)/doc/html/CopyConstructible.html\\\">CopyConstructible</a>\" \\
+ call=\"@xmlonly<functionname alt=\\\"boost::type_erasure::call\\\">call</functionname>@endxmlonly\" \\
+ any_cast=\"@xmlonly<functionname alt=\\\"boost::type_erasure::any_cast\\\">any_cast</functionname>@endxmlonly\" \\
+ typeid_of=\"@xmlonly<functionname alt=\\\"boost::type_erasure::typeid_of\\\">typeid_of</functionname>@endxmlonly\" \\
+ require_match=\"@xmlonly<functionname alt=\\\"boost::type_erasure::require_match\\\">require_match</functionname>@endxmlonly\" "
<doxygen:param>"PREDEFINED= \\
\"BOOST_TYPE_ERASURE_DOXYGEN=1\" \\
\"BOOST_TYPE_ERASURE_UNARY_INPLACE_OPERATOR(name, op)=template<class T = _self> struct name { static void apply(T&); };\" \\
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 2012-10-12 20:02:25 EDT (Fri, 12 Oct 2012)
@@ -27,6 +27,7 @@
[def __placeholder [classref boost::type_erasure::placeholder placeholder]]
[def __call [funcref boost::type_erasure::call call]]
[def __deduced [classref boost::type_erasure::deduced deduced]]
+[def __as_param [classref boost::type_erasure::as_param as_param]]
[def __addable [classref boost::type_erasure::addable addable]]
[def __subtractable [classref boost::type_erasure::subtractable subtractable]]
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 2012-10-12 20:02:25 EDT (Fri, 12 Oct 2012)
@@ -23,9 +23,9 @@
void basic1() {
//[basic1
/*`
- The main class in the library is __any. We can just pass
- it an MPL sequence specifying all the requirements on
- the types that it can hold.
+ The main class in the library is __any. An __any can
+ store objects that meet whatever requirements we specify.
+ These requirements are passed to __any as an MPL sequence.
[note The MPL sequence combines multiple concepts.
In the rare case when we only want a single concept, it doesn't
@@ -34,9 +34,9 @@
any<mpl::vector<copy_constructible<>, typeid_<> > > x(10);
int i = any_cast<int>(x); // i == 10
/*`
- __copy_constructible allows us to copy and destroy the
- object. __typeid_ provides run-time type information
- so that we can use __any_cast.
+ __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.
*/
//]
}
@@ -47,7 +47,7 @@
Now, this example doesn't do very much. `x` is approximately
equivalent to a [@boost:/libs/any/index.html boost::any].
We can make it more interesting by adding some operators,
- such as `operator++` and `operator<<`
+ such as `operator++` and `operator<<`.
*/
any<
mpl::vector<
@@ -64,10 +64,10 @@
//[basic3
/*`
- The library provides a full set of operators, but this
+ The library provides concepts for most C++ operators, but this
obviously won't cover all use cases; we often need to
define our own requirements. Let's take the `push_back`
- method, defined by several STL containers.
+ member, defined by several STL containers.
*/
BOOST_TYPE_ERASURE_MEMBER((has_push_back), push_back, 1)
@@ -81,8 +81,8 @@
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
- member function called `push_back` which takes
- one argument. When we use `has_push_back`, we have to
+ 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:
@@ -97,13 +97,13 @@
or `std::set<int>`.
Also, note the use of `_self&` as the second argument of
- __any. `_self` is a __placeholder. By using it here,
+ __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.
*/
/*`
- For free functions, we can use __BOOST_TYPE_ERASURE_FREE.
+ For free functions, we can use the macro __BOOST_TYPE_ERASURE_FREE.
*/
BOOST_TYPE_ERASURE_FREE((has_swap), swap, 2);
@@ -111,12 +111,24 @@
struct swappable : mpl::vector<has_swap<void(T&, T&)> > {};
/*`
- We use the __placeholder `_self` here to indicate which arguments
- of `swap` should be any's. When we use swap, we want it
- to look like `has_swap<void(_self&, _self&)>`, since `swap`
- takes two arguments of the same type by reference. Since
- the signature of swap always looks like this, we define
- `swappable<>` as a convenient short-cut.
+ 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 could use `_a` instead as long as
+ we substitute it uniformly like `any<swappable<_a>, _a&>`]
+
+ [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.]
*/
//]
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 2012-10-12 20:02:25 EDT (Fri, 12 Oct 2012)
@@ -17,11 +17,10 @@
//[compose1
/*`
- The basic concepts, like __copy_constructible and
- __incrementable, are useful, but dealing with many
- such concepts quickly gets cumbersome. Fortunately,
- the library allows us to combine several concepts into
- a single concept using an MPL sequence.
+ This 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.
*/
template<class T = _self>
struct arithmetic :
@@ -36,11 +35,8 @@
>
{};
/*`
- Now, `arithmetic` can be used just like any
- of the base concepts. We can even specialize
- __concept_interface for it if we want to
- add to or override the behavior of the base
- concepts.
+ Now, `arithmetic` is a concept that can be used just
+ like any of the base concepts.
*/
//]
Modified: sandbox/type_erasure/libs/type_erasure/example/custom.cpp
==============================================================================
--- sandbox/type_erasure/libs/type_erasure/example/custom.cpp (original)
+++ sandbox/type_erasure/libs/type_erasure/example/custom.cpp 2012-10-12 20:02:25 EDT (Fri, 12 Oct 2012)
@@ -19,11 +19,16 @@
//[custom1
/*`
Earlier, we used __BOOST_TYPE_ERASURE_MEMBER to define
- a concept for containers that support `push_back`. Let's
- take a look at what this actually entails. The first thing
- we need is a class template with a template parameter for
- each argument, and a static member function
- called `apply` that calls `push_back`.
+ a concept for containers that support `push_back`. Sometimes
+ this interface isn't flexible enough, however. The library
+ also provides a lower level interface that gives full
+ control of the behavior. Let's take a look at what we
+ would need in order to define `has_push_back.` First,
+ we need to define the `has_push_back` template itself. We'll
+ give it two template parameters, one for the container
+ and one for the element type. This template must have
+ a static member function called apply which is used
+ to dispatch the operation.
*/
template<class C, class T>
@@ -35,13 +40,13 @@
//[custom3
/*`
- This works, but we'd really like to call `c.push_back(10)`.
- We can add members to __any by specializing __concept_interface.
- The first argument is `push_back`, since we want to inject a member
+ The second part is to customize __any so that we can call `c.push_back(10)`.
+ We do this by specializing __concept_interface.
+ The first argument is `has_push_back`, since we want to inject a member
into every __any that uses the `push_back` concept. The second argument,
- Base, is used by the library to chain multiple uses of __concept_interface
- together. We have to inherit from it publicly. Other than
- that we can ignore it. The third argument is the placeholder
+ `Base`, is used by the library to chain multiple uses of __concept_interface
+ together. We have to inherit from it publicly. `Base` is also used
+ to get access to the full __any type. The third argument is the placeholder
that represents this any. If someone used `push_back<_c, _b>`,
we only want to insert a `push_back` member in the container,
not the value type. Thus, the third argument is the container
@@ -52,7 +57,7 @@
template<class C, class T, class Base>
struct concept_interface<has_push_back<C, T>, Base, C> : Base
{
- void push_back(typename rebind_any<Base, const T&>::type arg)
+ void push_back(const T& arg)
{ call(has_push_back<C, T>(), *this, arg); }
};
}
@@ -76,11 +81,7 @@
void custom4() {
//[custom4
/*`
- Note the use of __rebind_any to determine the argument
- type. We could just use `T`, but that would fail when
- `T` is a placeholder. __rebind_any does the work to
- determine the correct type in that case. Our example
- now becomes
+ Our example now becomes
*/
std::vector<int> vec;
any<has_push_back<_self, int>, _self&> c(vec);
Modified: sandbox/type_erasure/libs/type_erasure/example/overload.cpp
==============================================================================
--- sandbox/type_erasure/libs/type_erasure/example/overload.cpp (original)
+++ sandbox/type_erasure/libs/type_erasure/example/overload.cpp 2012-10-12 20:02:25 EDT (Fri, 12 Oct 2012)
@@ -9,7 +9,7 @@
// $Id$
#include <boost/type_erasure/concept_interface.hpp>
-#include <boost/type_erasure/rebind_any.hpp>
+#include <boost/type_erasure/as_param.hpp>
#include <boost/type_erasure/derived.hpp>
#include <boost/type_erasure/is_placeholder.hpp>
#include <boost/utility/enable_if.hpp>
@@ -120,7 +120,7 @@
template<class T, class U, class Base>
struct concept_interface< ::bar_concept<T, U>, Base, T>
{
- friend void bar(typename derived<Base>::type& t, typename rebind_any<Base, const U&>::type u)
+ friend void bar(typename derived<Base>::type& t, typename as_param<Base, const U&>::type u)
{
call(::bar_concept<T, U>(), t, u);
}
@@ -153,10 +153,6 @@
possible to merge the two specializations with a bit of metaprogramming,
but unless you have a lot of arguments, it's probably not
worth while.
-
- At first I tried overloading `bar` at namespace scope. This
- seems like a more obvious solution at first. Don't use it.
- It doesn't work with overloads.
*/
//]
Modified: sandbox/type_erasure/libs/type_erasure/example/printf.cpp
==============================================================================
--- sandbox/type_erasure/libs/type_erasure/example/printf.cpp (original)
+++ sandbox/type_erasure/libs/type_erasure/example/printf.cpp 2012-10-12 20:02:25 EDT (Fri, 12 Oct 2012)
@@ -286,7 +286,7 @@
print("double: %+20.9e\n", 3.14159265358979323846);
print("double: %0+20.9g\n", 3.14159265358979323846);
print("double: %*.*g\n", 20, 5, 3.14159265358979323846);
- print("string: %.10s\n", (const char *)"Hello World!");
+ print("string: %.10s\n", "Hello World!");
print("double: %2$*.*g int: %1$d\n", 10, 20, 5, 3.14159265358979323846);
}