Description

Simple functions to represent objects, for debugging and diagnostics.

The helpers provided here are rather commonplace, but written in a way as to incur only modest header inclusion load. It should be OK to use these even on widely used interface headers.

util::toString() performs a failsafe to-String conversion, thereby preferring a built-in conversion operator, falling back to a lexical conversion (boost) or just a unmangled and simplified type string as default.
util::typedString() combines this with a always visible type display
lib::meta::demangleCxx() uses the built-in compiler support to translate a mangled type-ID (as given by typeid(TY).name()) into a readable, fully qualified C++ type name. This is only supported for GNU compatible compilers.

Todo:: is it possible to stash away the boost::lexical_cast behind a custom facade, the way we did it for boost::format? This would reduce inclusion cost...

See also: FormatHelper_test; frontend for boost::format, printf-style

Definition in file format-obj.hpp.

#include "lib/symbol.hpp"
#include "lib/meta/trait.hpp"
#include <boost/lexical_cast.hpp>

Classes
class	basic_ostream< Char >
	STL class.

class	char_traits< C >

struct	StringConv< bool >

struct	StringConv< double >
	explicit specialisation to control precision of double values. More...

struct	StringConv< float >

struct	StringConv< SP, show_SmartPointer< SP > >

struct	StringConv< X, enable_LexicalConversion< X > >

Typedefs
template<typename X >
using	enable_LexicalConversion = lib::meta::enable_if< lib::meta::use_LexicalConversion< X > >
	toggle to prefer specialisation with direct lexical conversion

using	ostream = basic_ostream< char, char_traits< char > >

template<typename SP >
using	show_SmartPointer = lib::meta::enable_if< lib::meta::is_smart_ptr< typename lib::meta::Strip< SP >::TypeReferred > >

Functions
string	demangleCxx (Literal rawName)
	Fallback type-ID: More...

string	humanReadableTypeID (lib::Literal)
	pretty-print an internal C++ type representation More...

string	primaryTypeComponent (lib::Literal)
	extract core name component from a raw type spec More...

string	sanitisedFullTypeName (lib::Literal)
	build a sanitised ID from full type name

ostream &	showAdr (std::ostream &, void const *addr)
	preconfigured format for pretty-printing of addresses More...

string	showAdr (void const *addr) noexcept
	pretty-print an address as hex-suffix

string	showComplete (double) noexcept
	show enough decimal digits to represent every distinct value

string	showComplete (float val) noexcept

string	showComplete (f128 val) noexcept

string	showDecimal (double) noexcept
	show maximum reproducible decimal representation

string	showDecimal (float val) noexcept

string	showDecimal (f128 val) noexcept

string	showDouble (double) noexcept
	pretty-print a double in (rounded) fixed-point format More...

string	showFloat (float val) noexcept

string	showHash (size_t hash, uint showBytes=8) noexcept
	renders the size_t in hex, optionally only trailing bytes

std::string	showHashLSB (size_t hash) noexcept

string	showSize (size_t val) noexcept

template<typename TY >
std::string	toString (TY const &val) noexcept
	get some string representation of any object, reliably. More...

template<typename TY >
std::string	typedString (TY const &val) noexcept
	indicate type and possibly a (custom) conversion to string More...

Namespaces
	lib
	Implementation namespace for support and library code.

Function Documentation

◆ demangleCxx()

std::string demangleCxx ( Literal rawName )

Fallback type-ID:

reverse the effect of C++ name mangling.

Returns: unaltered internal type-ID; string in language-level form of a C++ type or object name, or a string with the original input if demangling fails.

Warning: implementation relies on the cross vendor C++ ABI in use by GCC and compatible compilers, so portability is limited. The implementation is accessed through libStdC++ Name representation in emitted object code and type IDs is essentially an implementation detail and subject to change.

Examples:: /Werk/devel/lumi/src/lib/test/test-helper.hpp.

Definition at line 159 of file format-obj.cpp.

References lib::meta::demangleCxx().

Referenced by lib::meta::demangleCxx(), lib::meta::humanReadableTypeID(), and lib::meta::primaryTypeComponent().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ humanReadableTypeID()

std::string humanReadableTypeID ( Literal rawType )

pretty-print an internal C++ type representation

implementation notes

we do not strip type adornments like const, & or *, however, the typical usage from within util::typeStr() is arranged in a way to absorb these adornments by the way the template signatures are defined
we do simplify the type display and strip some obnoxious namespace prefixes with the help of std::regex_replace
we perform those simplifying rewrites in place thus overwriting the result string. This exploits the fact that the replacements are always shorter than what is being replaced (beware).
standard regular expressions can be assumed to be threadsafe. Thus, we're able to build an embedded shared static variable on demand and use the performance optimisation offered by the standard library
performance wise we'll assume the transformation happens within the cache, so it doesn't make much of a difference if we scan the same comparatively short string multiple times

See also: format-obj.cpp implementation

Examples:: /Werk/devel/lumi/src/lib/test/test-helper.hpp.

Definition at line 190 of file format-obj.cpp.

References lib::meta::demangleCxx(), and lib::meta::humanReadableTypeID().

Referenced by lib::meta::humanReadableTypeID(), and lib::meta::sanitisedFullTypeName().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ primaryTypeComponent()

std::string primaryTypeComponent ( Literal rawType )

extract core name component from a raw type spec

implementation notes: We want to get at the name of the most relevant type entity. This in itself is a heuristic. But we can work on the assumption, that we get a sequence of nested namespaces and type names, and we'll be interested in the last, the innermost of these types. In the most general case, each type could be templated, and thus will be followed by parameter specs enclosed in angle braces. Behind this spec, only type adornments will follow. Thus we'll inspect the string from the back side, skipping over all type parameter contents, until we reach brace level zero again. From this point, we have to search backwards to the first namespace separator ::

Warning: we acknowledge this function can fail in various ways, some of which will be indicated by returning the string "void". But it may well happen that the returned string contains whitespace, superfluous punctuation or even the whole demangled type specification as is.

Returns: simple identifier possibly "the" type

Warning: implemented lexically, not necessarily correct!

Definition at line 268 of file format-obj.cpp.

References lib::meta::demangleCxx(), lib::meta::primaryTypeComponent(), and lib::meta::typeStr().

Referenced by lib::meta::primaryTypeComponent().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ showDouble()

std::string showDouble ( double val )

noexcept

pretty-print a double in (rounded) fixed-point format

Returns: fixed point string representation, never empty

Note: we set an explicit precision, since this is a diagnostic facility

Remarks: typically do not want to see all digits, but, for test code, we do want a predictable string representation of simple fractional values like 0.1 (which can not be represented as binary floats)

Definition at line 360 of file format-obj.cpp.

References util::showDouble().

Referenced by util::showDouble().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ showAdr()

std::ostream & showAdr	(	ostream &	stream,
		void const *	addr
	)

preconfigured format for pretty-printing of addresses

Note: show only the trailing X bytes of any address

Examples:: /Werk/devel/lumi/src/lib/test/test-helper.hpp.

Definition at line 385 of file format-obj.cpp.

References util::showAdr().

Referenced by util::showAdr().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ toString()

std::string toString ( TY const & val )

inlinenoexcept

get some string representation of any object, reliably.

A custom string conversion operator is invoked, if applicable, while all lexically convertible types (numbers etc) are treated by boost::lexical_cast. For double or float values, hard wired rounding to a fixed number of digits will be performed, to yield a predictable display of printed unit-test results.

Remarks: while the actual parameter is passed by const-ref, cv-qualifiactions and references are stripped from the type

Note: Deliberately there is no magic detection/support for pointers. This function must not be overloaded (to avoid ambiguities in more elaborate template instantiations).

Remarks: Since 10/2023 an attempt was made to solve this problem down in StringConf<TY>, yet this solution might be brittle. If you want pointers to be indicated (with address), consider using util::showPtr explicitly.