From 004ef17e42316d2060927900d0bc8cc779d98207 Mon Sep 17 00:00:00 2001 From: Peter Dimov Date: Tue, 10 Jun 2014 17:44:08 +0300 Subject: [PATCH] Update documentation. --- doc/core.qbk | 3 ++ doc/demangle.qbk | 74 +++++++++++++++++++++++++++++++++++++ doc/is_same.qbk | 69 +++++++++++++++++++++++++++++++++++ doc/lightweight_test.qbk | 7 +++- doc/typeinfo.qbk | 79 ++++++++++++++++++++++++++++++++++++++++ 5 files changed, 230 insertions(+), 2 deletions(-) create mode 100644 doc/demangle.qbk create mode 100644 doc/is_same.qbk create mode 100644 doc/typeinfo.qbk diff --git a/doc/core.qbk b/doc/core.qbk index 0c90773..a225d16 100644 --- a/doc/core.qbk +++ b/doc/core.qbk @@ -34,9 +34,11 @@ criteria for inclusion is that the utility component be: [include:core addressof.qbk] [include:core checked_delete.qbk] +[include:core demangle.qbk] [include:core enable_if.qbk] [include:core explicit_operator_bool.qbk] [include:core ignore_unused.qbk] +[include:core is_same.qbk] [include:core lightweight_test.qbk] [include:core no_exceptions_support.qbk] [include:core noncopyable.qbk] @@ -44,3 +46,4 @@ criteria for inclusion is that the utility component be: [include:core ref.qbk] [include:core scoped_enum.qbk] [include:core swap.qbk] +[include:core typeinfo.qbk] diff --git a/doc/demangle.qbk b/doc/demangle.qbk new file mode 100644 index 0000000..3971fae --- /dev/null +++ b/doc/demangle.qbk @@ -0,0 +1,74 @@ +[/ + Copyright 2014 Peter Dimov + + Distributed under the Boost Software License, Version 1.0. + + See accompanying file LICENSE_1_0.txt + or copy at http://boost.org/LICENSE_1_0.txt +] + +[section:demangle demangle] + +[section Authors] + +* Peter Dimov +* Andrey Semashev + +[endsect] + +[section Header ] + +The header `` defines the function +`boost::core::demangle`. It takes a mangled string such as +those returned by `typeid(T).name()` on certain implementations +such as `g++`, and returns its demangled, human-readable, form. + +[section Synopsis] + +`` +namespace boost +{ + +namespace core +{ + std::string demangle( char const * name ); +} + +} +`` + +[endsect] + +[section Example] + +`` +#include +#include +#include + +template struct X +{ +}; + +int main() +{ + char const * name = typeid( X ).name(); + + std::cout << name << std::endl; // prints 1XIiE + std::cout << boost::core::demangle( name ) << std::endl; // prints X +} +`` + +[endsect] + +[endsect] + +[section Acknowledgments] + +The implementation of `core::demangle` was taken from +`boost/exception/detail/type_info.hpp`, which in turn was adapted +from `boost/units/detail/utility.hpp`. + +[endsect] + +[endsect] diff --git a/doc/is_same.qbk b/doc/is_same.qbk new file mode 100644 index 0000000..a73b3e0 --- /dev/null +++ b/doc/is_same.qbk @@ -0,0 +1,69 @@ +[/ + Copyright 2014 Peter Dimov + + Distributed under the Boost Software License, Version 1.0. + + See accompanying file LICENSE_1_0.txt + or copy at http://boost.org/LICENSE_1_0.txt +] + +[section:is_same is_same] + +[section Authors] + +* Peter Dimov + +[endsect] + +[section Header ] + +The header `` defines the class template +`boost::core::is_same`. It defines a nested integral constant +`value` which is `true` when `T1` and `T2` are the same type, and +`false` when they are not. + +In tandem with `BOOST_TEST_TRAIT_TRUE` and `BOOST_TEST_TRAIT_FALSE`, +`is_same` is useful for writing tests for traits classes that have +to define specific nested types. + +[section Synopsis] + +`` +namespace boost +{ + +namespace core +{ + template struct is_same; +} + +} +`` + +[endsect] + +[section Example] + +`` +#include +#include + +template struct X +{ + typedef T& type; +}; + +using boost::core::is_same; + +int main() +{ + BOOST_TEST_TRAIT_TRUE(( is_same::type, int&> )); + return boost::report_errors(); +} +`` + +[endsect] + +[endsect] + +[endsect] diff --git a/doc/lightweight_test.qbk b/doc/lightweight_test.qbk index a840906..d41e820 100644 --- a/doc/lightweight_test.qbk +++ b/doc/lightweight_test.qbk @@ -119,7 +119,10 @@ Return the error count from `main`. `` #include -int sqr( int x ); // should return x * x +int sqr( int x ) +{ + return x * x; +} int main() { @@ -181,7 +184,7 @@ message containing `Trait`. Note the double set of parentheses. template struct X { typedef T type; -} +}; using boost::core::is_same; diff --git a/doc/typeinfo.qbk b/doc/typeinfo.qbk new file mode 100644 index 0000000..4ce3840 --- /dev/null +++ b/doc/typeinfo.qbk @@ -0,0 +1,79 @@ +[/ + Copyright 2014 Peter Dimov + + Distributed under the Boost Software License, Version 1.0. + + See accompanying file LICENSE_1_0.txt + or copy at http://boost.org/LICENSE_1_0.txt +] + +[section:typeinfo typeinfo] + +[section Authors] + +* Peter Dimov + +[endsect] + +[section Header ] + +The header `` defines a class +`boost::core::typeinfo`, which is an alias for `std::type_info` +when RTTI is enabled, and is a reasonable substitute when RTTI +is not supported. + +The macro `BOOST_CORE_TYPEID`, when applied to a type `T`, is the +equivalent of `typeid(T)` and produces a reference to a const +`typeinfo` object. + +The function `boost::core::demangled_name` takes a +`boost::core::typeinfo const & ti` and either returns `ti.name()`, +when that string doesn't need to be demangled, or +`boost::core::demangle(ti.name())`, when it does. The return type +of `boost::core::demangled_name` is `char const*` in the first case +and `std::string` in the second. + +[section Synopsis] + +`` +namespace boost +{ + +namespace core +{ + class typeinfo; + /* char const* or std::string */ demangled_name( typeinfo const & ti ); +} + +} + +#define BOOST_CORE_TYPEID(T) /*unspecified*/ +`` + +[endsect] + +[section Example] + +`` +#include +#include + +template struct X +{ +}; + +int main() +{ + typedef X T; + + boost::core::typeinfo const & ti = BOOST_CORE_TYPEID(T); + + std::cout << boost::core::demangled_name( ti ) << std::endl; +} +`` + +[endsect] + +[endsect] + +[endsect]