Subject: [Boost-commit] svn:boost r67356 - in trunk/boost/spirit/home/support/utree: . detail
From: hartmut.kaiser_at_[hidden]
Date: 2010-12-19 20:54:40
Author: hkaiser
Date: 2010-12-19 20:54:35 EST (Sun, 19 Dec 2010)
New Revision: 67356
URL: http://svn.boost.org/trac/boost/changeset/67356
Log:
Spirit: utree documentation work
Text files modified:
trunk/boost/spirit/home/support/utree/detail/utree_detail2.hpp | 22 ++--
trunk/boost/spirit/home/support/utree/operators.hpp | 12 +-
trunk/boost/spirit/home/support/utree/utree.hpp | 216 ++++++++++++++++++++++-----------------
trunk/boost/spirit/home/support/utree/utree_traits.hpp | 60 +++++-----
4 files changed, 171 insertions(+), 139 deletions(-)
Modified: trunk/boost/spirit/home/support/utree/detail/utree_detail2.hpp
==============================================================================
--- trunk/boost/spirit/home/support/utree/detail/utree_detail2.hpp (original)
+++ trunk/boost/spirit/home/support/utree/detail/utree_detail2.hpp 2010-12-19 20:54:35 EST (Sun, 19 Dec 2010)
@@ -477,16 +477,16 @@
return f(list_range(iterator(x.r.first, 0), iterator(0, x.r.last)));
case type::string_type:
- return f(utf8_string_range(x.s.str(), x.s.size()));
+ return f(utf8_string_range_type(x.s.str(), x.s.size()));
case type::string_range_type:
- return f(utf8_string_range(x.sr.first, x.sr.last));
+ return f(utf8_string_range_type(x.sr.first, x.sr.last));
case type::symbol_type:
- return f(utf8_symbol_range(x.s.str(), x.s.size()));
+ return f(utf8_symbol_range_type(x.s.str(), x.s.size()));
case type::binary_type:
- return f(binary_range(x.s.str(), x.s.size()));
+ return f(binary_range_type(x.s.str(), x.s.size()));
case type::reference_type:
return apply(*x.p, f);
@@ -542,19 +542,19 @@
case type::string_type:
return visit_impl::apply(y, detail::bind(
- f, utf8_string_range(x.s.str(), x.s.size())));
+ f, utf8_string_range_type(x.s.str(), x.s.size())));
case type::string_range_type:
return visit_impl::apply(y, detail::bind(
- f, utf8_string_range(x.sr.first, x.sr.last)));
+ f, utf8_string_range_type(x.sr.first, x.sr.last)));
case type::symbol_type:
return visit_impl::apply(y, detail::bind(
- f, utf8_symbol_range(x.s.str(), x.s.size())));
+ f, utf8_symbol_range_type(x.s.str(), x.s.size())));
case type::binary_type:
return visit_impl::apply(y, detail::bind(
- f, binary_range(x.s.str(), x.s.size())));
+ f, binary_range_type(x.s.str(), x.s.size())));
case type::reference_type:
return apply(*x.p, y, f);
@@ -732,7 +732,7 @@
set_type(type::range_type);
}
- inline utree::utree(utf8_string_range const& str, shallow_tag)
+ inline utree::utree(utf8_string_range_type const& str, shallow_tag)
{
s.initialize();
this->sr.first = str.begin();
@@ -1403,7 +1403,7 @@
To dispatch(From const& val, boost::mpl::false_) const
{
// From is NOT convertible to To !!!
- throw std::bad_cast();
+ boost::throw_exception(std::bad_cast());
return To();
}
@@ -1429,7 +1429,7 @@
T* operator()(From const& val) const
{
// From is NOT convertible to T !!!
- throw std::bad_cast();
+ boost::throw_exception(std::bad_cast());
return 0;
}
Modified: trunk/boost/spirit/home/support/utree/operators.hpp
==============================================================================
--- trunk/boost/spirit/home/support/utree/operators.hpp (original)
+++ trunk/boost/spirit/home/support/utree/operators.hpp 2010-12-19 20:54:35 EST (Sun, 19 Dec 2010)
@@ -208,21 +208,21 @@
out << (b ? "true" : "false") << ' ';
}
- void operator()(binary_range const& b) const
+ void operator()(binary_range_type const& b) const
{
out << "#";
out.width(2);
out.fill('0');
- typedef binary_range::const_iterator iterator;
+ typedef binary_range_type::const_iterator iterator;
for (iterator i = b.begin(); i != b.end(); ++i)
out << std::hex << int((unsigned char)*i);
out << std::dec << "# ";
}
- void operator()(utf8_string_range const& str) const
+ void operator()(utf8_string_range_type const& str) const
{
- typedef utf8_string_range::const_iterator iterator;
+ typedef utf8_string_range_type::const_iterator iterator;
iterator i = str.begin();
out << '"';
for (; i != str.end(); ++i)
@@ -230,9 +230,9 @@
out << "\" ";
}
- void operator()(utf8_symbol_range const& str) const
+ void operator()(utf8_symbol_range_type const& str) const
{
- typedef utf8_symbol_range::const_iterator iterator;
+ typedef utf8_symbol_range_type::const_iterator iterator;
iterator i = str.begin();
for (; i != str.end(); ++i)
out << *i;
Modified: trunk/boost/spirit/home/support/utree/utree.hpp
==============================================================================
--- trunk/boost/spirit/home/support/utree/utree.hpp (original)
+++ trunk/boost/spirit/home/support/utree/utree.hpp 2010-12-19 20:54:35 EST (Sun, 19 Dec 2010)
@@ -1,7 +1,7 @@
/*=============================================================================
- Copyright (c) 2001-2010 Joel de Guzman
- Copyright (c) 2001-2010 Hartmut Kaiser
- Copyright (c) 2010 Bryce Lelbach
+ Copyright (c) 2001-2011 Joel de Guzman
+ Copyright (c) 2001-2011 Hartmut Kaiser
+ Copyright (c) 2011 Bryce Lelbach
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -37,12 +37,13 @@
namespace boost { namespace spirit
{
//[utree_exceptions
- // All exceptions thrown by utree are derived from utree_exception.
+ /*` All exceptions thrown by utree are derived from utree_exception. */
struct utree_exception : std::exception {};
- // bad_type_exception is thrown whenever somebody calls a member function
- // which applies to certain stored utree_type's only, but this precondition
- // is violated as the utree instance holds some other type.
+ /*`The `bad_type_exception` is thrown whenever somebody calls a member
+ function, which applies to certain stored utree_type's only, but this
+ precondition is violated as the `utree` instance holds some other type.
+ */
struct bad_type_exception : utree_exception
{
virtual const char* what() const throw()
@@ -53,30 +54,34 @@
//]
//[utree_types
+ /*`Each instance of an `utree` data structure can store exactly one of the
+ following data types at a time:
+ */
struct utree_type
{
enum info
{
- nil_type, // nil is the sentinel utree type.
- list_type, // A doubly linked list of utrees.
- range_type, // A range of list::iterators.
- reference_type, // A reference to another utree.
- any_type, // A pointer or reference to any C++ type.
- function_type, // A utree holding a stored_function<F> object,
- // where F is an unary function object taking a
- // scope as it's parameter and returning a
- // utree.
+ nil_type, // nil is the sentinel (empty) utree type.
+ list_type, // A doubly linked list of utrees.
+ range_type, // A range of list::iterators.
+ reference_type, // A reference to another utree.
+ any_type, // A pointer or reference to any C++ type.
+ function_type, // A utree holding a stored_function<F> object,
+ // where F is an unary function object taking a
+ // scope as it's parameter and returning a
+ // utree.
// numeric atoms
- bool_type,
- int_type,
- double_type,
+ bool_type, // An utree holding a boolean value
+ int_type, // An utree holding a integer (int) value
+ double_type, // An utree holding a floating point (double) value
// text atoms (utf8)
- string_type,
- string_range_type,
- symbol_type,
- binary_type
+ string_type, // An UTF-8 string
+ string_range_type, // A pair of iterators into an UTF-8 string
+ symbol_type, // An UTF-8 symbol name
+
+ binary_type // Arbitrary binary data
};
};
//]
@@ -123,35 +128,44 @@
};
//[utree_strings
- // Binary string
+ /*`The `utree` string types described below are used by the `utree` API
+ only. These are not used to store information in the `utree` itself.
+ Their purpose is to refer to different internal `utree` node types
+ only. For instance, creating a `utree` from a binary data type will
+ create a `binary_type` utree node (see above).
+ */
+ /*`The binary data type can be represented either verbatim as a sequence
+ of bytes or as a pair of iterators into some other stored binary data
+ sequence. Use this string type to access/create a `binary_type` `utree`.
+ */
typedef basic_string<
- boost::iterator_range<char const*>,
- utree_type::binary_type>
- binary_range;
+ boost::iterator_range<char const*>, utree_type::binary_type
+ > binary_range_type;
typedef basic_string<
- std::string,
- utree_type::binary_type>
- binary_string;
+ std::string, utree_type::binary_type
+ > binary_string_type;
- // UTF-8 string
+ /*`The UTF-8 string can be represented either verbatim as a sequence of
+ characters or as a pair of iterators into some other stored binary data
+ sequence. Use this string type to access/create a `string_type` `utree`.
+ */
typedef basic_string<
- boost::iterator_range<char const*>,
- utree_type::string_type>
- utf8_string_range;
+ boost::iterator_range<char const*>, utree_type::string_type
+ > utf8_string_range_type;
typedef basic_string<
- std::string,
- utree_type::string_type>
- utf8_string_type;
+ std::string, utree_type::string_type
+ > utf8_string_type;
- // UTF-8 symbol
+ /*`The UTF-8 symbol can be represented either verbatim as a sequence of
+ characters or as a pair of iterators into some other stored binary data
+ sequence. Use this string type to access/create a `symbol_type` `utree`.
+ */
typedef basic_string<
- boost::iterator_range<char const*>,
- utree_type::symbol_type>
- utf8_symbol_range;
+ boost::iterator_range<char const*>, utree_type::symbol_type
+ > utf8_symbol_range_type;
typedef basic_string<
- std::string,
- utree_type::symbol_type>
- utf8_symbol;
+ std::string, utree_type::symbol_type
+ > utf8_symbol_type;
//]
///////////////////////////////////////////////////////////////////////////
@@ -195,7 +209,6 @@
class any_ptr
{
public:
-
template <typename Ptr>
typename boost::disable_if<
boost::is_polymorphic<
@@ -221,7 +234,6 @@
}
private:
-
// constructor is private
any_ptr(void* p, std::type_info const* i)
: p(p), i(i) {}
@@ -238,16 +250,17 @@
//[utree
class utree {
public:
+ //[utree_container_types
typedef utree value_type;
typedef utree& reference;
typedef utree const& const_reference;
typedef std::ptrdiff_t difference_type;
typedef std::size_t size_type;
- typedef detail::list::node_iterator<utree>
- iterator;
- typedef detail::list::node_iterator<utree const>
- const_iterator;
+ typedef detail::list::node_iterator<utree> iterator;
+ typedef detail::list::node_iterator<utree const> const_iterator;
+ //]
+
typedef detail::list::node_iterator<boost::reference_wrapper<utree> >
ref_iterator;
@@ -258,60 +271,70 @@
~utree();
////////////////////////////////////////////////////////////////////////
- // ctors and assignment operators
-
- // nil
+ //[utree_initialization
+ /*`A `utree` can be constructed or initialized from a wide range of
+ data types, allowing to create `utree` instances for every
+ possible node type (see the description of `utree_type::info` above).
+ For this reason it exposes a constructor and a assignment operator
+ for each of the allowed node types as shown below:
+ */
+ // constructs `nil_type` node
utree();
- // boolean
+ // initializes a `boolean_type` node
utree(bool);
reference operator=(bool);
- // integer
+ // initializes a `integer_type` node
utree(unsigned int);
utree(int);
reference operator=(unsigned int);
reference operator=(int);
- // double
+ // initializes a `double_type` node
utree(double);
reference operator=(double);
- // string
+ // initializes a `string_type` node
utree(char);
utree(char const*);
utree(char const*, std::size_t);
utree(std::string const&);
- utree(utf8_string_range const&, shallow_tag);
reference operator=(char);
reference operator=(char const*);
reference operator=(std::string const&);
- // reference
+ // constructs a `string_range_type` node, does not copy the data
+ // but stores the iterator range
+ utree(utf8_string_range_type const&, shallow_tag);
+
+ // initializes a `reference_type` node
utree(boost::reference_wrapper<utree>);
reference operator=(boost::reference_wrapper<utree>);
- // any
+ // initializes an `any_type` node
utree(any_ptr const&);
reference operator=(any_ptr const&);
- // range
- template <class Iter>
- utree(boost::iterator_range<Iter>);
- template <class Iter>
- reference operator=(boost::iterator_range<Iter>);
+ // initialize a `range_type` node
+ template <class Iterator>
+ utree(boost::iterator_range<Iterator>);
+ template <class Iterator>
+ reference operator=(boost::iterator_range<Iterator>);
- // function object
+ // initialize a `function_type` node
template <class F>
- utree(stored_function<F> const&);
+ utree(stored_function<F> const&);
template <class F>
- reference operator=(stored_function<F> const&);
+ reference operator=(stored_function<F> const&);
- // typed string
+ // initialize either a `string_type`, a `symbol_type`, or a `binary_type`
+ // node (depending on the template parameter `type_`)
template <class Base, utree_type::info type_>
- utree(basic_string<Base, type_> const&);
+ utree(basic_string<Base, type_> const&);
template <class Base, utree_type::info type_>
- reference operator=(basic_string<Base, type_> const&);
+ reference operator=(basic_string<Base, type_> const&);
+ //]
// copy
utree(const_reference);
@@ -323,7 +346,7 @@
// assign dispatch
template <class Iter>
- void assign(Iter, Iter);
+ void assign(Iter, Iter);
////////////////////////////////////////////////////////////////////////
@@ -332,46 +355,47 @@
// single dispatch
template <class F>
- typename boost::result_of<F(utree const&)>::type
- static visit(utree const&, F);
+ typename boost::result_of<F(utree const&)>::type
+ static visit(utree const&, F);
template <class F>
- typename boost::result_of<F(utree&)>::type
- static visit(utree&, F);
+ typename boost::result_of<F(utree&)>::type
+ static visit(utree&, F);
// double dispatch
template <class F>
- typename boost::result_of<F(utree const&, utree const&)>::type
- static visit(utree const&, utree const&, F);
+ typename boost::result_of<F(utree const&, utree const&)>::type
+ static visit(utree const&, utree const&, F);
template <class F>
- typename boost::result_of<F(utree&, utree const&)>::type
- static visit(utree&, utree const&, F);
+ typename boost::result_of<F(utree&, utree const&)>::type
+ static visit(utree&, utree const&, F);
template <class F>
- typename boost::result_of<F(utree const&, utree&)>::type
- static visit(utree const&, utree&, F);
+ typename boost::result_of<F(utree const&, utree&)>::type
+ static visit(utree const&, utree&, F);
template <class F>
- typename boost::result_of<F(utree&, utree&)>::type
- static visit(utree&, utree&, F);
+ typename boost::result_of<F(utree&, utree&)>::type
+ static visit(utree&, utree&, F);
////////////////////////////////////////////////////////////////////////
- ////////////////////////////////////////////////////////////////////////
+ ///////////////////////////////////////////////////////////////////////
+ //[utree_container_functions
// STL Container interface
// insertion
template <class T>
- void push_back(T const&);
+ void push_back(T const&);
template <class T>
- void push_front(T const&);
+ void push_front(T const&);
template <class T>
- iterator insert(iterator, T const&);
+ iterator insert(iterator, T const&);
template <class T>
- void insert(iterator, std::size_t, T const&);
- template <class Iter>
- void insert(iterator, Iter, Iter);
+ void insert(iterator, std::size_t, T const&);
+ template <class Iterator>
+ void insert(iterator, Iterator, Iterator);
// erasure
void pop_front();
@@ -392,6 +416,7 @@
iterator end();
const_iterator end() const;
ref_iterator ref_end();
+ //]
// random access
reference operator[](size_type);
@@ -406,10 +431,17 @@
////////////////////////////////////////////////////////////////////////
+ //[utree_variant_functions
+ // return the data type (`utree_type::info`) of the currently stored
+ // data item
utree_type::info which() const;
+ // access the currently stored data in a type safe manner, this will
+ // throw a `std::bad_cast()` if the currently stored data item is not
+ // default convertible to `T`.
template <class T>
- T get() const;
+ T get() const;
+ //]
reference deref();
const_reference deref() const;
Modified: trunk/boost/spirit/home/support/utree/utree_traits.hpp
==============================================================================
--- trunk/boost/spirit/home/support/utree/utree_traits.hpp (original)
+++ trunk/boost/spirit/home/support/utree/utree_traits.hpp 2010-12-19 20:54:35 EST (Sun, 19 Dec 2010)
@@ -119,18 +119,18 @@
///////////////////////////////////////////////////////////////////////////
// this specialization keeps symbols from being transformed into strings
template<>
- struct assign_to_attribute_from_value<utree, utf8_symbol>
+ struct assign_to_attribute_from_value<utree, utf8_symbol_type>
{
- static void call (utf8_symbol const& val, utree& attr)
+ static void call (utf8_symbol_type const& val, utree& attr)
{
attr = val;
}
};
template<>
- struct assign_to_attribute_from_value<utree, utf8_symbol_range>
+ struct assign_to_attribute_from_value<utree, utf8_symbol_range_type>
{
- static void call (utf8_symbol_range const& val, utree& attr)
+ static void call (utf8_symbol_range_type const& val, utree& attr)
{
attr = val;
}
@@ -141,11 +141,11 @@
template <>
struct attribute_as_string<utree>
{
- typedef utf8_string_range type;
+ typedef utf8_string_range_type type;
static type call(utree const& attr)
{
- return boost::get<utf8_string_range>(attr);
+ return boost::get<utf8_string_range_type>(attr);
}
};
@@ -319,10 +319,10 @@
template <>
struct compute_compatible_component_variant<
- utree, utf8_string_range>
+ utree, utf8_string_range_type>
: mpl::true_
{
- typedef utf8_string_range compatible_type;
+ typedef utf8_string_range_type compatible_type;
static bool is_compatible(int d)
{
@@ -345,10 +345,10 @@
template <>
struct compute_compatible_component_variant<
- utree, utf8_symbol_range>
+ utree, utf8_symbol_range_type>
: mpl::true_
{
- typedef utf8_symbol_range compatible_type;
+ typedef utf8_symbol_range_type compatible_type;
static bool is_compatible(int d)
{
@@ -358,10 +358,10 @@
template <>
struct compute_compatible_component_variant<
- utree, utf8_symbol>
+ utree, utf8_symbol_type>
: mpl::true_
{
- typedef utf8_symbol compatible_type;
+ typedef utf8_symbol_type compatible_type;
static bool is_compatible(int d)
{
@@ -371,10 +371,10 @@
template <>
struct compute_compatible_component_variant<
- utree, binary_range>
+ utree, binary_range_type>
: mpl::true_
{
- typedef binary_range compatible_type;
+ typedef binary_range_type compatible_type;
static bool is_compatible(int d)
{
@@ -384,10 +384,10 @@
template <>
struct compute_compatible_component_variant<
- utree, binary_string>
+ utree, binary_string_type>
: mpl::true_
{
- typedef binary_string compatible_type;
+ typedef binary_string_type compatible_type;
static bool is_compatible(int d)
{
@@ -438,23 +438,23 @@
///////////////////////////////////////////////////////////////////////////
template <>
- struct symbols_lookup<utree, utf8_symbol>
+ struct symbols_lookup<utree, utf8_symbol_type>
{
typedef std::string type;
static type call(utree const& t)
{
- utf8_symbol_range r = boost::get<utf8_symbol_range>(t);
+ utf8_symbol_range_type r = boost::get<utf8_symbol_range_type>(t);
return std::string(r.begin(), r.end());
}
};
template <>
- struct symbols_lookup<utf8_symbol, utf8_symbol>
+ struct symbols_lookup<utf8_symbol_type, utf8_symbol_type>
{
typedef std::string type;
- static type call(utf8_symbol const& t)
+ static type call(utf8_symbol_type const& t)
{
return t;
}
@@ -469,7 +469,7 @@
template <typename Context>
static type call(utree const& t, Context&)
{
- utf8_symbol_range r = boost::get<utf8_symbol_range>(t);
+ utf8_symbol_range_type r = boost::get<utf8_symbol_range_type>(t);
return r.front();
}
};
@@ -518,21 +518,21 @@
template <typename Context>
static type call(utree const& t, Context&)
{
- utf8_symbol_range r = boost::get<utf8_string_range>(t);
+ utf8_symbol_range_type r = boost::get<utf8_string_range_type>(t);
return std::basic_string<char, Traits, Alloc>(r.begin(), r.end());
}
};
///////////////////////////////////////////////////////////////////////////
template <>
- struct extract_from_attribute<utree, utf8_symbol>
+ struct extract_from_attribute<utree, utf8_symbol_type>
{
typedef std::string type;
template <typename Context>
static type call(utree const& t, Context&)
{
- utf8_symbol_range r = boost::get<utf8_symbol_range>(t);
+ utf8_symbol_range_type r = boost::get<utf8_symbol_range_type>(t);
return std::string(r.begin(), r.end());
}
};
@@ -545,7 +545,7 @@
template <typename Context>
static type call(utree const& t, Context&)
{
- utf8_string_range r = boost::get<utf8_string_range>(t);
+ utf8_string_range_type r = boost::get<utf8_string_range_type>(t);
return std::string(r.begin(), r.end());
}
};
@@ -571,7 +571,7 @@
static type pre(utree const& t)
{
- utf8_string_range r = boost::get<utf8_string_range>(t);
+ utf8_string_range_type r = boost::get<utf8_string_range_type>(t);
return r.front();
}
};
@@ -617,7 +617,7 @@
static type pre(utree const& t)
{
- utf8_symbol_range r = boost::get<utf8_string_range>(t);
+ utf8_symbol_range_type r = boost::get<utf8_string_range_type>(t);
return std::basic_string<char, Traits, Alloc>(r.begin(), r.end());
}
};
@@ -645,19 +645,19 @@
static type pre(utree const& t)
{
- utf8_string_range r = boost::get<utf8_string_range>(t);
+ utf8_string_range_type r = boost::get<utf8_string_range_type>(t);
return std::string(r.begin(), r.end());
}
};
template <>
- struct transform_attribute<utree const, utf8_symbol, karma::domain>
+ struct transform_attribute<utree const, utf8_symbol_type, karma::domain>
{
typedef std::string type;
static type pre(utree const& t)
{
- utf8_symbol_range r = boost::get<utf8_symbol_range>(t);
+ utf8_symbol_range_type r = boost::get<utf8_symbol_range_type>(t);
return std::string(r.begin(), r.end());
}
};