1[/ 2 Copyright 2014 Peter Dimov 3 Copyright 2014 Andrey Semashev 4 5 Distributed under the Boost Software License, Version 1.0. 6 7 See accompanying file LICENSE_1_0.txt 8 or copy at http://boost.org/LICENSE_1_0.txt 9] 10 11[section:demangle demangle] 12 13[simplesect Authors] 14 15* Peter Dimov 16* Andrey Semashev 17 18[endsimplesect] 19 20[section Header <boost/core/demangle.hpp>] 21 22The header `<boost/core/demangle.hpp>` defines several tools for undecorating 23symbol names. 24 25[section Synopsis] 26 27 namespace boost 28 { 29 30 namespace core 31 { 32 std::string demangle( char const * name ); 33 34 char const * demangle_alloc( char const * name ) noexcept; 35 void demangle_free( char const * demangled_name ) noexcept; 36 37 class scoped_demangled_name 38 { 39 public: 40 explicit scoped_demangled_name( char const * name ) noexcept; 41 ~scoped_demangled_name() noexcept; 42 char const * get() const noexcept; 43 44 scoped_demangled_name( scoped_demangled_name const& ) = delete; 45 scoped_demangled_name& operator= ( scoped_demangled_name const& ) = delete; 46 }; 47 } 48 49 } 50 51[endsect] 52 53[section Conventional interface] 54 55The function `boost::core::demangle` is the conventional 56way to obtain demangled symbol name. It takes a mangled string such as 57those returned by `typeid(T).name()` on certain implementations 58such as `g++`, and returns its demangled, human-readable, form. In case if 59demangling fails (e.g. if `name` cannot be interpreted as a mangled name) 60the function returns `name`. 61 62[section Example] 63 64 #include <boost/core/demangle.hpp> 65 #include <typeinfo> 66 #include <iostream> 67 68 template<class T> struct X 69 { 70 }; 71 72 int main() 73 { 74 char const * name = typeid( X<int> ).name(); 75 76 std::cout << name << std::endl; // prints 1XIiE 77 std::cout << boost::core::demangle( name ) << std::endl; // prints X<int> 78 } 79 80[endsect] 81 82[endsect] 83 84[section Low level interface] 85 86In some cases more low level interface may be desirable. For example: 87 88* Assuming that symbol demangling may fail, the user wants to be able to handle such errors. 89* The user needs to post-process the demangled name (e.g. remove common namespaces), and 90allocating a temporary string with the complete demangled name is significant overhead. 91 92The function `boost::core::demangle_alloc` performs name demangling and returns a pointer 93to a string with the demangled name, if succeeded, or `nullptr` otherwise. The returned pointer 94must be passed to `boost::core::demangle_free` to reclaim resources. Note that on some platforms 95the pointer returned by `boost::core::demangle_alloc` may refer to the string denoted by `name`, 96so this string must be kept immutable for the whole life time of the returned pointer. 97 98The `boost::core::scoped_demangled_name` class is a scope guard that automates the calls to 99`boost::core::demangle_alloc` (on its construction) and `boost::core::demangle_free` (on destruction). 100The string with the demangled name can be obtained with its `get` method. Note that this method may 101return `nullptr` if demangling failed. 102 103[section Example] 104 105 #include <boost/core/demangle.hpp> 106 #include <typeinfo> 107 #include <iostream> 108 109 template<class T> struct X 110 { 111 }; 112 113 int main() 114 { 115 char const * name = typeid( X<int> ).name(); 116 boost::core::scoped_demangled_name demangled( name ); 117 118 std::cout << name << std::endl; // prints 1XIiE 119 std::cout << (demangled.get() ? demangled.get() : "[unknown]") << std::endl; // prints X<int> 120 } 121 122[endsect] 123 124[endsect] 125 126[endsect] 127 128[section Acknowledgments] 129 130The implementation of `core::demangle` was taken from 131`boost/exception/detail/type_info.hpp`, which in turn was adapted 132from `boost/units/detail/utility.hpp` and `boost/log/utility/type_info_wrapper.hpp`. 133 134[endsect] 135 136[endsect] 137