doc/demangle.qbk

[/
  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 Acknowledgments]

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]