feedc0de/boost_type_index
1
0
Fork 0
forked from boostorg/type_index
Code Pull Requests Activity

- Documentation changes

Browse Source 
Signed-off-by: K-ballo <k@fusionfenix.com>
This commit is contained in:
K-ballo
2012-07-07 01:37:27 -03:00
parent 938034b166
commit a6bddfa8cd
1 changed files with 17 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
libs/type_index/doc/type_index.qbk
View File

@ -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 <class T>` ]
[note `T` means type here. Think of it as `T` in `template <class T>` ]
[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<T>()` 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<T>()` 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<T>();
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<ParamT&>().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<T>()` instead of `boost::type_id<T>()`.
If you need to preserve `const`, `volatile` and references, use `boost::template_index` instead of `boost::type_index`; `boost::template_id_with_cvr<T>()` instead of `boost::type_id<T>()`.
[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<type_index> types_;
@ -63,7 +62,7 @@ public:
type_index ti = type_id<T>();
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 <class T>
@ -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 <class ResultT>
@ -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]