From a6bddfa8cd24fb264c3abd2b44ab0df8f09045d3 Mon Sep 17 00:00:00 2001 From: K-ballo Date: Sat, 7 Jul 2012 01:37:27 -0300 Subject: [PATCH] - Documentation changes Signed-off-by: K-ballo --- libs/type_index/doc/type_index.qbk | 35 +++++++++++++++--------------- 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/libs/type_index/doc/type_index.qbk b/libs/type_index/doc/type_index.qbk index 0cb64f8..1f60f01 100644 --- a/libs/type_index/doc/type_index.qbk +++ b/libs/type_index/doc/type_index.qbk @@ -11,19 +11,18 @@ ] [section Motivation] -Sometimes getting and storing at runtime information about template type is required. For such cases usually used a construction like `&typeid(T)` or C++11 class `std::type_index`. And that is the point, where problems strat: +Sometimes getting and storing information about a template type at runtime is required. For such cases a construction like `&typeid(T)` or C++11 class `std::type_index` is usually used. And that is the point, where problems strat: * `typeid(T)` and `std::type_index` require Run Time Type Info (RTTI) -* `typeid(T)` strips const, volatile and references from type -* some compilers have bugs and do not correctly compare `std::type_info` across shared libraries -* some implementations of `typeid(T)` do not strip const, volatile and references -* only a few STLs have `std::type_index` implementation +* some implementations of `typeid(T)` strips const, volatile and references from type, while others don't +* some compilers have bugs and do not correctly compare `std::type_info` objects across shared libraries +* only a few implementations already provide `std::type_index` * no easy way to store type info without stripping const, volatile and references -* no nice and portable way to get human readable type name +* no nice and portable way to get human readable type names Boost.TypeIndex was designed to work around those issues. -[note `T` means here type. Think of it, as of `T` in `template ` ] +[note `T` means type here. Think of it as `T` in `template ` ] [warning This library is not accepted to Boost, it is currrently waiting for review. ] @@ -32,9 +31,9 @@ Boost.TypeIndex was designed to work around those issues. [section Getting started] In short: -Just replace `&typeid(T)`, `typeid(T)` with `boost::type_id()` and `const std::type_info&`, `std::type_index` with `boost::type_index`. For cases when RTTI is really required, replace `typeid(variable)` with `boost::type_id_rtti_only(variable)`. That's all, you are now using Boost.TypeIndex. +Just replace `typeid(T)`, `&typeid(T)` with `boost::type_id()` and `std::type_index`, `const std::type_info&` with `boost::type_index`. For cases when RTTI is actually required, replace `typeid(variable)` with `boost::type_id_rtti_only(variable)`. That's all, you are now using Boost.TypeIndex. -To get nice human readable name, use `name_demangled()` member function: +To get nice human readable names, use the `name_demangled()` member function: `` type_index ti = type_id(); std::string nice_name = ti.name_demangled(); @@ -42,17 +41,17 @@ std::string nice_name = ti.name_demangled(); std::string nice_name_with_const_volatile_ref = template_id_with_cvr().name_demangled(); `` -`template_index` and `type_index` have full set of comparison operators, hashing functions and ostream operators. Thay can be used with any container class. +`template_index` and `type_index` provide the full set of comparison operators, hashing functions and ostream operators. Thay can be used with any container class. -If you need to save `const`, `volatile` and references, use `boost::template_index` instead of `boost::type_index`; `boost::template_id_with_cvr()` instead of `boost::type_id()`. +If you need to preserve `const`, `volatile` and references, use `boost::template_index` instead of `boost::type_index`; `boost::template_id_with_cvr()` instead of `boost::type_id()`. [endsect] [section Examples] -All the code in examples will work with and without RTTI support. +All code in the examples will work with and without RTTI support. -Class that allows to register type only once. +Class that allows to register a given type only once. `` class types_registry { unordered_set types_; @@ -63,7 +62,7 @@ public: type_index ti = type_id(); std::cout << "Adding type " << ti << " to registry \n"; if (!types_.insert(ti).second) - throw std::logic_error("Type " + ti.name_demangled() + " already in registry"); + throw std::logic_error("Type " + ti.name_demangled() + " already registered"); } template @@ -92,8 +91,8 @@ Has type int: 1 Has type std::string: 0 `` -Another example (this time checking for exact parameter match). -`my_unary_function` is a class, that stroes function with result type `ResultT` and any input parameter type. In `opertaor()`, it checks for input parameter match and then executes the stored function: +Another example, this time checking for exact parameter match. +`my_unary_function` is a class, that stores a function with result type `ResultT` and any input parameter type. In `operator()`, it checks for input parameter match and then executes the stored function: `` template @@ -117,8 +116,8 @@ class my_unary_function { [section Performance] -`type_index` and `template_index` classes hold a single pointer, so they are easy and fast to copy. Calls to `const char* name()` do not require dynamic memory allocation and usually just return a pointer to an array of chars in read-only section of binary file. Comparison operators are optimized as much as possible, and in worst case only execute `std::strcmp`. Calls to `std::string name_demangled()` for `type_index` do usually require dynamic memory allocation and some computations, so they are not recomended for usage in performance critical sections. Calls to `std::string name_demangled()` for `template_index` require only `std::strlen` call and are much faster than `std::string name_demangled()` for `type_index`. +`type_index` and `template_index` classes hold a single pointer, so they are easy and fast to copy. Calls to `const char* name()` do not require dynamic memory allocation and usually just return a pointer to an array of chars in a read-only section of the binary image. Comparison operators are optimized as much as possible, and will at worst execute a single `std::strcmp`. Calls to `std::string name_demangled()` for `type_index` do usually require dynamic memory allocation and some computations, so they are not recomended for usage in performance critical sections. Calls to `std::string name_demangled()` for `template_index` only require a single `std::strlen` call and are considerably faster than `std::string name_demangled()` for `type_index`. -`template_index` uses `BOOST_CURRENT_FUNCTION` macro, which could lead to code bloat. So if you do not need to save `const`, `volatile` and references, use `type_index`. +`template_index` uses the `BOOST_CURRENT_FUNCTION` macro, which could lead to code bloat. In those cases where preserving `const`, `volatile` and references is not needed prefer using `type_index`. [endsect]