boost_core/doc/demangle.qbk at develop · zanbilify/boost_core · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
[/
  Copyright 2014 Peter Dimov
  Copyright 2014 Andrey Semashev

  Distributed under the Boost Software License, Version 1.0.

  See accompanying file LICENSE_1_0.txt
  or copy at http://boost.org/LICENSE_1_0.txt
]

[section:demangle demangle]

[simplesect Authors]

* Peter Dimov
* Andrey Semashev

[endsimplesect]

[section Header <boost/core/demangle.hpp>]

The header `<boost/core/demangle.hpp>` defines several tools for undecorating
symbol names.

[section Synopsis]

    namespace boost
    {

    namespace core
    {
        std::string demangle( char const * name );

        char const * demangle_alloc( char const * name ) noexcept;
        void demangle_free( char const * demangled_name ) noexcept;

        class scoped_demangled_name
        {
        public:
            explicit scoped_demangled_name( char const * name ) noexcept;
            ~scoped_demangled_name() noexcept;
            char const * get() const noexcept;

            scoped_demangled_name( scoped_demangled_name const& ) = delete;
            scoped_demangled_name& operator= ( scoped_demangled_name const& ) = delete;
        };
    }

    }

[endsect]

[section Conventional interface]

The function `boost::core::demangle` is the conventional
way to obtain demangled symbol name. It takes a mangled string such as
those returned by `typeid(T).name()` on certain implementations
such as `g++`, and returns its demangled, human-readable, form. In case if
demangling fails (e.g. if `name` cannot be interpreted as a mangled name)
the function returns `name`.

[section Example]

    #include <boost/core/demangle.hpp>
    #include <typeinfo>
    #include <iostream>

    template<class T> struct X
    {
    };

    int main()
    {
        char const * name = typeid( X<int> ).name();

        std::cout << name << std::endl; // prints 1XIiE
        std::cout << boost::core::demangle( name ) << std::endl; // prints X<int>
    }

[endsect]

[endsect]

[section Low level interface]

In some cases more low level interface may be desirable. For example:

* Assuming that symbol demangling may fail, the user wants to be able to handle such errors.
* The user needs to post-process the demangled name (e.g. remove common namespaces), and
allocating a temporary string with the complete demangled name is significant overhead.

The function `boost::core::demangle_alloc` performs name demangling and returns a pointer
to a string with the demangled name, if succeeded, or `nullptr` otherwise. The returned pointer
must be passed to `boost::core::demangle_free` to reclaim resources. Note that on some platforms
the pointer returned by `boost::core::demangle_alloc` may refer to the string denoted by `name`,
so this string must be kept immutable for the whole life time of the returned pointer.

The `boost::core::scoped_demangled_name` class is a scope guard that automates the calls to
`boost::core::demangle_alloc` (on its construction) and `boost::core::demangle_free` (on destruction).
The string with the demangled name can be obtained with its `get` method. Note that this method may
return `nullptr` if demangling failed.

[section Example]

    #include <boost/core/demangle.hpp>
    #include <typeinfo>
    #include <iostream>

    template<class T> struct X
    {
    };

    int main()
    {
        char const * name = typeid( X<int> ).name();
        boost::core::scoped_demangled_name demangled( name );

        std::cout << name << std::endl; // prints 1XIiE
        std::cout << (demangled.get() ? demangled.get() : "[unknown]") << std::endl; // prints X<int>
    }

[endsect]

[endsect]

[endsect]

[section Acknowledgements]

The implementation of `core::demangle` was taken from
`boost/exception/detail/type_info.hpp`, which in turn was adapted
from `boost/units/detail/utility.hpp` and `boost/log/utility/type_info_wrapper.hpp`.

[endsect]

[endsect]