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

Updated docs

Browse Source
This commit is contained in:
Antony Polukhin
2013-10-29 16:19:26 +04:00
parent d0d30d56df
commit 1508e1d560
7 changed files with 80 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
boost/type_index.hpp
View File

@@ -12,13 +12,13 @@
/// \brief Includes all the headers of the Boost.TypeIndex library.
///
/// By inclusion of this file all classes (boost::type_info + boost::type_index if RTTI is on
/// and boost::template_index) will be available.
/// and boost::template_info + boost::template_index) will be available.
///
/// Consider including <boost/type_index/type_index.hpp> if you do not whant to include
/// boost::template_index class while RTTI is available.
/// boost::template_info and boost::template_index class while RTTI is available.
///
/// Consider including <boost/type_index/type_info.hpp> if you do not whant to include
/// boost::template_index and boost::type_index classes while RTTI is available.
/// Consider including <boost/type_index/type_info.hpp> if you need only boost::type_info class
/// and boost::type_id* functions.
// MS compatible compilers support #pragma once
#if defined(_MSC_VER)

15
boost/type_index/template_info.hpp
View File

@@ -18,7 +18,9 @@
/// \file template_info.hpp
/// \brief Contains implementation of boost::template_info class.
///
/// boost::template_info class is used instead of boost::type_index class in situations when RTTI is disabled.
/// boost::template_info class is used instead of boost::type_info and boost::type_index classes
/// in situations when RTTI is disabled.
///
/// It combines functionality of std::type_info and std::type_index.
#include <cstring>
@@ -54,7 +56,8 @@ namespace detail {
/// that outputs the WHOLE function signature, including template parameters.
///
/// If your compiler is not recognised and BOOST_TYPE_INDEX_FUNCTION_SIGNATURE is not defined,
/// then a compile-time error will arise at any attempt to use boost::template_info class.
/// then a compile-time error will arise at any attempt to use boost::template_info or
/// boost::template_index classes.
#define BOOST_TYPE_INDEX_FUNCTION_SIGNATURE BOOST_CURRENT_FUNCTION
#elif defined(BOOST_TYPE_INDEX_FUNCTION_SIGNATURE)
@@ -147,8 +150,8 @@ inline void lazy_function_signature_assert() {
};
} // namespace detail
/// Copyable type_info that does not require RTTI and could store const,
/// volatile and references if constructed via construct_with_cvr()
/// Copyable type_info class that does not require RTTI.
/// When RTTI is disabled this class will be used instead of boost::type_info and boost::type_index.
class template_info {
private:
const char* name_;
@@ -165,7 +168,7 @@ public:
: name_(detail::ctti<void>::name())
{}
/// Factory method for constructing template_info instance for type T.
/// Factory method for constructing boost::template_info instance for type T.
/// Strips const, volatile and & modifiers from T
template <class T>
static const template_info& construct(){
@@ -213,7 +216,6 @@ public:
return std::string(name_, std::strlen(name_ + detail::ctti_skip_size_at_end));
}
/// @cond
bool operator == (const template_info& rhs) const BOOST_NOEXCEPT {
return !std::strcmp(name_, rhs.name());
}
@@ -237,7 +239,6 @@ public:
bool operator >= (const template_info& rhs) const BOOST_NOEXCEPT {
return std::strcmp(name_, rhs.name()) >= 0;
}
/// @endcond
/// Function for getting hash value
std::size_t hash_code() const BOOST_NOEXCEPT {

6
boost/type_index/type_index.hpp
View File

@@ -16,7 +16,9 @@
/// \file boost/type_index/type_index.hpp
/// \brief Contains implementation of boost::type_index class.
///
/// boost::type_index class is used in situations when RTTI is enabled.
/// boost::type_index class is used in situations when RTTI is enabled, it is designed to be a drop-in
/// replacement for C++11 std::type_index class.
///
/// When RTTI is disabled boost::template_index will be used instead of
/// this class.
@@ -35,6 +37,8 @@
namespace boost {
/// This class is designed to be a drop-in replacement for C++11 std::type_index class.
///
/// Copyable std::type_index class that requires RTTI.
/// When RTTI is disabled boost::template_index will be used instead of
/// this class.

14
boost/type_index/type_info.hpp
View File

@@ -17,12 +17,12 @@
/// \file type_info.hpp
/// \brief Contains implementation of boost::type_info class.
///
/// boost::type_info class can be used as a drop-in replacement for std::type_info, but unlike std::type_info
/// this class has a name_demangled() function for getting human-readable type names.
///
/// boost::type_info class is used in situations when RTTI is enabled.
/// When RTTI is disabled or BOOST_TYPE_INDEX_FORCE_NORTTI_COMPATIBILITY macro is defined boost::template_info
/// is used instead of it.
///
/// boost::type_info class can be used as a drop-in replacement for std::type_info, but unlike std::type_info
/// this class has a name_demangled() function for getting human-readable type names.
#include <boost/config.hpp>
@@ -83,8 +83,8 @@ namespace detail {
///
/// Unlike std::type_info this class:
/// * has a name_demangled() function for getting human-readable type names
/// * name() function always noexcept and returns simple mangled name as character array
/// * workarounds some cimpiler issues
/// * name() function always noexcept and returns simple mangled name as character a character array
/// * contains workarounds for some compiler issues
class type_info: public detail::stl_type_info {
public:
typedef detail::stl_type_info stl_type_info;
@@ -234,14 +234,14 @@ public:
#undef BOOST_CLASSINFO_COMPARE_BY_NAMES
#endif
/// Function to get std::type_info for a type T.
/// Function to get boost::type_info for a type T.
/// Strips const, volatile and & modifiers from T.
template <class T>
inline const type_info& type_id() BOOST_NOEXCEPT {
return type_info::construct<T>();
}
/// Function for constructing std::type_info instance for type T.
/// Function for constructing boost::type_info instance for type T.
/// Does not strip const, volatile, & and && modifiers from T.
/// If T has no const, volatile, & and && modifiers, then returns exactly
/// the same result as in case of calling `type_id<T>()`.

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

@@ -20,21 +20,24 @@ Sometimes getting and storing information about a type at runtime is required. F
* no easy way to store type info without stripping const, volatile and references
* no nice and portable way to get human readable type names
Boost.TypeIndex was designed to work around all those issues.
Boost.TypeIndex library was designed to work around all those issues.
[note `T` means type here. Think of it as of `T` in `template <class T>` ]
[note `T` means type here. Think of it as of `T` in `template <class T>` ]
[warning This library is not accepted to Boost, it is currrently waiting for review. ]
[warning This library is not accepted to Boost, it is currently waiting for review. ]
[endsect]
[section Getting started]
`boost::type_index` can be used as a drop-in replacement for `std::type_index`, but
it usually does not require RTTI. It provides the full set of comparison operators,
hashing functions and ostream operators, so it can be used with any container class.
`boost::type_info` is a drop-in replacement for `std::type_index` and `boost::type_index` is a drop-in
replacement for `std::type_index`. Unlike Standard Library versions those classes usually do not
require RTTI.
To start using it:
`boost::type_index` provides the full set of comparison operators, hashing functions and ostream
operators, so it can be used with any container class.
To start using Boost.TypeIndex:
* Replace headers:
* Use `<boost/type_index/type_index.hpp>` instead of `<typeindex>`
@@ -79,19 +82,20 @@ std::string nice_name_with_const_volatile_ref
[section Space and Performance]
* `template_index` uses the `BOOST_CURRENT_FUNCTION` macro which could lead to code bloat, so prefer using `type_index` type.
* `template_info` uses macro for getting full text representation of function name which could lead to code bloat,
so prefer using `type_info` type.
* `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`.
* Calls to `std::string name_demangled()` usually require dynamic memory allocation and some computations, so they are not recommended for usage in performance critical sections.
[endsect]
[section Code bloat]
Without RTTI TypeIndex library will switch from using `boost::type_index` class to `boost::template_index`. `boost::template_index` uses the `BOOST_CURRENT_FUNCTION` for each type that is passed to `type_id()` and `type_id_with_cvr()`
functions.
Without RTTI TypeIndex library will switch from using `boost::type_info` class to `boost::template_info`.
`boost::template_info` uses macro for getting full text representation of function name for each type that
is passed to `type_id()` and `type_id_with_cvr()` functions.
This leads to big strings in binary file:
```
@@ -109,28 +113,47 @@ i
[section Compiler support]
TypeIndex has been tested and sucessfully work on MSVC2010, GCC-4.5, Clang-2.9. If your compiler is not in a list of tested compilers, you shall correctly define `BOOST_TYPE_INDEX_FUNCTION_SIGNATURE`,`BOOST_TYPE_INDEX_CTTI_BEGIN_SKIP` and `BOOST_TYPE_INDEX_CTTI_END_SKIP` macroses:
TypeIndex has been tested and successfully work on MSVC2010, GCC-4.5, Clang-2.9. If your compiler is not
in a list of tested compilers, you shall correctly define `BOOST_TYPE_INDEX_FUNCTION_SIGNATURE`,
`BOOST_TYPE_INDEX_CTTI_BEGIN_SKIP` and `BOOST_TYPE_INDEX_CTTI_END_SKIP` macroses:
# define `BOOST_TYPE_INDEX_FUNCTION_SIGNATURE` to a a compiler specific macro, that outputs the *whole* function signature, including template parameters
# define `BOOST_TYPE_INDEX_FUNCTION_SIGNATURE` to a a compiler specific macro, that outputs the *whole*
function signature, including template parameters
# define `BOOST_TYPE_INDEX_CTTI_BEGIN_SKIP` and `BOOST_TYPE_INDEX_CTTI_END_SKIP` to `0`
# get the output of `boost::detail::ctti<int>::n()`
# get the output of `boost::template_id<int>().name()`
# set `BOOST_TYPE_INDEX_CTTI_BEGIN_SKIP` equal to characters count before last occurrence of `int` in output
# set `BOOST_TYPE_INDEX_CTTI_END_SKIP` equal to characters count after last occurrence of `int` in output
# check that `boost::detail::ctti<int>::name_demangled()` returns "int"
# (optional, but highly recomended) [@http://www.boost.org/support/bugs.html create ticket] with feature request to add your compiler to supported compilers list. Include `BOOST_TYPE_INDEX_CTTI_BEGIN_SKIP` and `BOOST_TYPE_INDEX_CTTI_END_SKIP` numbers.
# check that `boost::template_id<int>().name_demangled()` returns "int"
# (optional, but highly recomended) [@http://www.boost.org/support/bugs.html create ticket] with
feature request to add your compiler to supported compilers list. Include
`BOOST_TYPE_INDEX_FUNCTION_SIGNATURE`, `BOOST_TYPE_INDEX_CTTI_BEGIN_SKIP` and
`BOOST_TYPE_INDEX_CTTI_END_SKIP` values.
Consider the following example:
With `BOOST_TYPE_INDEX_CTTI_BEGIN_SKIP` and `BOOST_TYPE_INDEX_CTTI_END_SKIP` set to `0`, `boost::detail::ctti<int>::n()` returns "const char *__cdecl boost::detail::ctti<int>::n(void)". Then you shall set `BOOST_TYPE_INDEX_CTTI_BEGIN_SKIP` to `sizeof("const char *__cdecl boost::detail::ctti<") - 1` and `BOOST_TYPE_INDEX_CTTI_END_SKIP` to `sizeof(">::n(void)") - 1`
With `BOOST_TYPE_INDEX_CTTI_BEGIN_SKIP` and `BOOST_TYPE_INDEX_CTTI_END_SKIP` set to `0`,
`boost::template_id<int>().name()` returns "const char *__cdecl boost::detail::ctti<int>::n(void)".
Then you shall set `BOOST_TYPE_INDEX_CTTI_BEGIN_SKIP` to
`sizeof("const char *__cdecl boost::detail::ctti<") - 1` and `BOOST_TYPE_INDEX_CTTI_END_SKIP`
to `sizeof(">::n(void)") - 1`
[endsect]
[section Mixing sources with RTTI on and RTTI off]
Linking a binary from source files that were compiled with different RTTI flags is not a very good idea and may lead to a lot of surprises. However if there is a very strong need TypeIndex library provides a solution for mixing sources: just define `BOOST_TYPE_INDEX_FORCE_NORTTI_COMPATIBILITY` macro. This would lead to usage of `boost::template_index` instead of `boost::type_index` class.
Linking a binary from source files that were compiled with different RTTI flags is not a very good
idea and may lead to a lot of surprises. However if there is a very strong need, TypeIndex library
provides a solution for mixing sources: just define `BOOST_TYPE_INDEX_FORCE_NORTTI_COMPATIBILITY`
macro. This would lead to usage of `boost::template_index` instead of `boost::type_index` class
and `boost::template_info` instead of `boost::type_info` class.
[note Do not forget to rebuild *all* the projects with `BOOST_TYPE_INDEX_FORCE_NORTTI_COMPATIBILITY` macro defined ]
You must know that linking RTTI on and RTTI off binaries may succeed even without defining the `BOOST_TYPE_INDEX_FORCE_NORTTI_COMPATIBILITY` macro, but that does not mean that you'll get a working binary. Such actions may break the One Definition Rule. Take a look at the table below, that shows how the `boost::type_index get_integer();` function will look like with different RTTI flags:
You must know that linking RTTI on and RTTI off binaries may succeed even without defining the
`BOOST_TYPE_INDEX_FORCE_NORTTI_COMPATIBILITY` macro, but that does not mean that you'll get a
working binary. Such actions may break the One Definition Rule. Take a look at the table below,
that shows how the `boost::type_index get_integer();` function will look like with different
RTTI flags:
[table:diffs
[[RTTI on] [RTTI off]]
@@ -139,5 +162,11 @@ You must know that linking RTTI on and RTTI off binaries may succeed even withou
Such differences are usually not detected by linker and lead to errors at runtime.
[warning
Even with `BOOST_TYPE_INDEX_FORCE_NORTTI_COMPATIBILITY` defined there is no guarantee
that everything will be OK. Libraries that use their own workarounds for disabled RTTI
may fail to link orwork correctly.
]
[endsect]

9
libs/type_index/examples/exact_types_match.cpp
View File

@@ -6,11 +6,12 @@
//[type_index_exact_type_match_example
/*`
The following example shows that `boost::type_index` (and `boost::type_info`) is able to store the exact type, without stripping const, volatile and references.
Example works with and without RTTI.
The following example shows that `boost::type_index` (and `boost::type_info`) is able to store the exact type,
without stripping const, volatile and references. Example works with and without RTTI.
In this example we'll create a class, that stores pointer to function and remembers the exact type of a parameter that function accepts.
When an attempt to call the stored function will be made, type of input parameter will be checked for exact match with initaily erased type of function.
In this example we'll create a class, that stores pointer to function and remembers the exact type of a
parameter that function accepts. When an attempt to call the stored function will be made, type of input
parameter will be checked for exact match with initaily erased type of function.
*/
#include <boost/type_index/type_index.hpp>

3
libs/type_index/examples/inheritance.cpp
View File

@@ -6,8 +6,9 @@
//[type_index_derived_example
/*`
The following example shows that `boost::type_index` is able to store the real type, successfully getting through
The following example shows that `boost::type_info` is able to store the real type, successfully getting through
all the inheritances.
Example works with RTTI only. Without RTTI support it won't compile, producing a compile-time error with message:
"boost::type_id_rtti_only(T&) requires RTTI"
*/