Death namespace

Shared root namespace.

The shared root namespace contains definitions and classes that don't depend on any other namespace. Most of the definitions are defined in CommonBase.h, which should be included (even transitively) in every .h/.cpp file to avoid issues due to missing configuration-specific and platform-specific definitions. Besides that, some definitions are listed separately. Most of the time Common.h should be used instead, which also includes <cstddef>, <cstdint> and some function-like macros. For event tracing and assertions, see Asserts.h.

Namespaces

namespace Backward
Exception handling implementation.
namespace Containers
Container implementations.
namespace Cpu
Compile-time and runtime CPU instruction set detection and dispatch.
namespace Environment
Platform-specific environment helper functions.
namespace IO
File system, streaming and IO-related classes.
namespace Threading
Multithreading-related classes.
namespace Trace
Runtime event tracing implementation, should be used along with Asserts.h.
namespace Utf8
Unicode (UTF-8. UTF-16 and UTF-32) utilities.

Classes

class IDisposable
Base interface for releasing resources on object destruction.
class ITraceSink
Interface for sink to be used by logger writing to it.
class Memory
Memory-related utilities.

Functions

template<class ... Args>
auto format(const char* format, const Args&... args) -> Containers::String
Formats a string.
template<class ... Args>
auto formatInto(Containers::MutableStringView buffer, const char* format, const Args&... args) -> std::size_t
Formats a string into an existing buffer.
template<class ... Args, std::size_t size>
auto formatInto(char(&buffer)[size], const char* format, const Args&... args) -> std::size_t
template<class T>
auto forward(typename std::remove_reference<T>::type& t) -> T&& constexpr noexcept
Forwards an l-value.
template<class T>
auto forward(typename std::remove_reference<T>::type&& t) -> T&& constexpr noexcept
Forwards an r-value.
template<class T>
auto move(T&& t) -> std::remove_reference<T>::type&& constexpr noexcept
Converts a value to an r-value.
template<class T>
void swap(T& a, T& b) noexcept(…)
Swaps two values.
template<std::size_t size, class T>
void swap(T(&a)[size], T(&b)[size]) noexcept(…)
Swaps two arrays.
template<typename T, typename U>
auto runtime_cast(U* u) -> T* noexcept
Casts a pointer to another type.
template<class T, class U>
auto runtime_cast(const std::shared_ptr<U>& u) -> std::shared_ptr<T> noexcept
template<class T, class U>
auto runtime_cast(std::shared_ptr<U>&& u) -> std::shared_ptr<T> noexcept

Function documentation

#include <Base/Format.h>
template<class ... Args>
Containers::String Death::format(const char* format, const Args&... args)

Formats a string.

Provides type-safe formatting of arbitrary types into a template string, similar in syntax to Python's format().

Templating language

Formatting placeholders are denoted by {}, which can have either implicit ordering (as shown above), or be numbered, such as {2}. Zero means first item from args, it's allowed to repeat the numbers. An implicit placeholder following a numbered one will get next position after.

Unlike in Python, it's allowed to both have more placeholders than arguments or more arguments than placeholders. Extraneous placeholders are copied to the output verbatim, extraneous arguments are simply ignored.

In order to write a literal curly brace to the output, simply double it.

Data type support

TypeDefault behavior
char, signed char, unsigned charWritten as a base-10 integer (not as a character)
short, unsigned shortWritten as a base-10 integer
int, unsigned intWritten as a base-10 integer
long, unsigned longWritten as a base-10 integer
long long, unsigned long longWritten as a base-10 integer
floatWritten as a float with 6 significant digits by default
doubleWritten as a float with 15 significant digits by default
long doubleWritten as a float, by default with 18 significant digits on platforms
with 80-bit long double and 15 digits on platforms where it is 64-bit
boolWritten as true / false
char*Written as a sequence of characters until '\0' (which is not written)
Containers::StringView,
MutableStringView, String		Written as a sequence of Containers::StringView::size() characters

Advanced formatting options

Advanced formatting such as precision or presentation type is possible by putting extra options after a semicolon, following the optional placeholder number, such as {:x} to print an integer value in hexadecimal. In general, the syntax similar to the std::printf() -style formatting, with the addition of {} and : used instead of % — for example, "%.2f" can be translated to "{:.2f}".

The full placeholder syntax is the following, again a subset of the Python format():

{[number][:[.precision][type]]}

The type is a single character specifying output conversion:

ValueMeaning
'c'Character. Valid only for 8-, 16- and 32-bit integer types. At the moment, arbitrary UTF-32 codepoints don't work, only 7-bit ASCII values have a guaranteed output.
'd'Decimal integer (base 10). Valid only for integer types. Default for integers if nothing is specified.
'o'Octal integer (base 8). Valid only for integer types.
'x'Hexadecimal integer (base 16) with lowercase letters a–f. Valid only for integer types.
'X'Hexadecimal integer with uppercase letters A–F. Valid only for integer types.
'g'General floating-point, formatting the value either in exponent notation or fixed-point format depending on its magnitude. The exponent e and special values such as nan or inf are printed lowercase. Valid only for floating-point types.
'G'General floating-point. The exponent E and special values such as NAN or INF are printed uppercase. Valid only for floating-point types.
'e'Exponent notation. The exponent e and special values such as nan or inf are printed lowercase. Valid only for floating-point types.
'E'Exponent notation. The exponent E and special values such as NAN or INF are printed uppercase. Valid only for floating-point types.
'f'Fixed point. The exponent e and special values such as nan or inf are printed lowercase. Valid only for floating-point types.
'F'Fixed point. The exponent E and special values such as NAN or INF are printed uppercase. Valid only for floating-point types.
noneDefault based on type, equivalent to 'd' for integral types and 'g' for floating-point types. The only valid specifier for strings.

The precision field specifies a precision of the output. It's interpreted differently based on the data type:

TypeMeaning
Integers, except for the 'c' type specifierIf the number of decimals is smaller than precision, the integer gets padded with the 0 character from the left. If both the number and precision is 0, nothing is written to the output. Default precision is 1.
Floating-point types with default or 'g' / 'G' type specifierThe number is printed with at most precision significant digits. Default precision depends on data type, see the type support table above.
Floating-point types with 'e' / 'E' type specifierThe number is always printed with exactly one decimal, precision decimal points (including trailing zeros) and the exponent. Default precision depends on data type, see the type support table above.
Floating-point types with 'f' / 'F' type specifierThe number is always printed with exactly precision decimal points including trailing zeros. Default precision depends on data type, see the type support table above.
Strings, characters (integers with the 'c' type specifier)If the string length is larger than precision, only the first precision bytes are written to the output. Default precision is unlimited. Note that this doesn't work with UTF-8 at the moment and specifying precision of 0 doesn't give the expected output for characters.

Performance

This function always does exactly one allocation for the output array. See formatInto(Containers::MutableStringView, const char*, const Args&... args) for a completely zero-allocation alternative.

#include <Base/Format.h>
template<class ... Args>
std::size_t Death::formatInto(Containers::MutableStringView buffer, const char* format, const Args&... args)

Formats a string into an existing buffer.

Writes formatted output to given buffer, expecting that it is large enough. The formatting is done completely without any allocation. Returns total amount of bytes written, does not write any terminating '\0' character.

See format() for more information about usage and templating language.

#include <Base/Format.h>
template<class ... Args, std::size_t size>
std::size_t Death::formatInto(char(&buffer)[size], const char* format, const Args&... args)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

#include <Base/Move.h>
template<class T>
T&& Death::forward(typename std::remove_reference<T>::type& t) constexpr noexcept

Forwards an l-value.

Returns static_cast<T&&>(t). Equivalent to std::forward(), which is used to implement perfect forwarding, but without the #include <utility> dependency and guaranteed to be constexpr even in C++11.

#include <Base/Move.h>
template<class T>
T&& Death::forward(typename std::remove_reference<T>::type&& t) constexpr noexcept

Forwards an r-value.

Returns static_cast<T&&>(t). Equivalent to std::forward(), which is used to implement perfect forwarding, but without the #include <utility> dependency and guaranteed to be constexpr even in C++11.

#include <Base/Move.h>
template<class T>
std::remove_reference<T>::type&& Death::move(T&& t) constexpr noexcept

Converts a value to an r-value.

Returns static_cast<typename std::remove_reference<T>::type&&>(t). Equivalent to std::move(), but without the #include <utility> dependency and guaranteed to be constexpr even in C++11.

#include <Base/Move.h>
template<class T>
void Death::swap(T& a, T& b) noexcept(…)

Swaps two values.

Swaps specified values. Equivalent to std::swap(), but without the #include <utility> dependency, and without the internals delegating to std::move(), hurting debug performance. In order to keep supporting custom specializations, the usage pattern should be similar to the standard utility, i.e. with using Death::swap.

#include <Base/Move.h>
template<std::size_t size, class T>
void Death::swap(T(&a)[size], T(&b)[size]) noexcept(…)

Swaps two arrays.

Does the same as swap(T&, T&), but for every array element.

#include <Base/TypeInfo.h>
template<typename T, typename U>
T* Death::runtime_cast(U* u) noexcept

Casts a pointer to another type.

Safely converts pointers to classes up, down, and sideways along the inheritance hierarchy of classes annotated by DEATH_RUNTIME_OBJECT() in an optimized way. Additionally, it can perform downcast at no performance cost.

If DEATH_SUPPRESS_RUNTIME_CAST is defined, the optimized implementation is suppressed and the standard dynamic_cast<T>() is used to cast the pointer instead.

#include <Base/TypeInfo.h>
template<class T, class U>
std::shared_ptr<T> Death::runtime_cast(const std::shared_ptr<U>& u) noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

#include <Base/TypeInfo.h>
template<class T, class U>
std::shared_ptr<T> Death::runtime_cast(std::shared_ptr<U>&& u) noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.