diff --git a/boost/type_index.hpp b/boost/type_index.hpp index 3bebe59..b8fb9e2 100644 --- a/boost/type_index.hpp +++ b/boost/type_index.hpp @@ -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 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 if you do not whant to include -/// boost::template_index and boost::type_index classes while RTTI is available. +/// Consider including if you need only boost::type_info class +/// and boost::type_id* functions. // MS compatible compilers support #pragma once #if defined(_MSC_VER) diff --git a/boost/type_index/template_info.hpp b/boost/type_index/template_info.hpp index 4d09194..0876b5a 100644 --- a/boost/type_index/template_info.hpp +++ b/boost/type_index/template_info.hpp @@ -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 @@ -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::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 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 { diff --git a/boost/type_index/type_index.hpp b/boost/type_index/type_index.hpp index fc10d27..3ac6118 100644 --- a/boost/type_index/type_index.hpp +++ b/boost/type_index/type_index.hpp @@ -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. diff --git a/boost/type_index/type_info.hpp b/boost/type_index/type_info.hpp index ddc5bcf..26ed189 100644 --- a/boost/type_index/type_info.hpp +++ b/boost/type_index/type_info.hpp @@ -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 @@ -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 inline const type_info& type_id() BOOST_NOEXCEPT { return type_info::construct(); } -/// 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()`. diff --git a/libs/type_index/doc/type_index.qbk b/libs/type_index/doc/type_index.qbk index 4d22c5f..7fb0a39 100644 --- a/libs/type_index/doc/type_index.qbk +++ b/libs/type_index/doc/type_index.qbk @@ -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 ` ] +[note `T` means type here. Think of it as of `T` in `template ` ] -[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 `` instead of `` @@ -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::n()` +# get the output of `boost::template_id().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::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().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::n()` returns "const char *__cdecl boost::detail::ctti::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().name()` returns "const char *__cdecl boost::detail::ctti::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] diff --git a/libs/type_index/examples/exact_types_match.cpp b/libs/type_index/examples/exact_types_match.cpp index 181e565..e639775 100644 --- a/libs/type_index/examples/exact_types_match.cpp +++ b/libs/type_index/examples/exact_types_match.cpp @@ -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 diff --git a/libs/type_index/examples/inheritance.cpp b/libs/type_index/examples/inheritance.cpp index ae54d17..5cd1cb5 100644 --- a/libs/type_index/examples/inheritance.cpp +++ b/libs/type_index/examples/inheritance.cpp @@ -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" */