Corrade::Utility namespace

enum class Corrade::Utility::ConfigurationValueFlag: std::uint8_t

#include <Corrade/Utility/ConfigurationValue.h>

Configuration value conversion flag.

enum class Corrade::Utility::TweakableState: std::uint8_t

#include <Corrade/Utility/TweakableParser.h>

Tweakable state.

typedef Containers::EnumSet<ConfigurationValueFlag> Corrade::Utility::ConfigurationValueFlags

#include <Corrade/Utility/ConfigurationValue.h>

Configuration value conversion flags.

#include <Corrade/Utility/TypeTraits.h>

template<class T>

using Corrade::Utility::IsIterable = std::integral_constant<bool, implementation-specific>

Traits class for checking whether given type is iterable.

Equivalent to std::true_type if the class is has either begin() / end() members, is usable with free begin() / end() functions or has std::begin() / std::end() overloads. Otherwise equivalent to std::false_type.

Used together with IsStringLike by Debug to decide whether given type should be printed as a container of its contents or as a whole.

#include <Corrade/Utility/TypeTraits.h>

template<class T>

using Corrade::Utility::IsStringLike = std::integral_constant<bool, implementation-specific>

Traits class for checking whether given type is iterable.

Equivalent to std::true_type if the class is has a c_str() member. Otherwise equivalent to std::false_type. Useful for dispatching on the std::string type without having to include or forward-declare it.

Used together with IsIterable by Debug to decide whether given type should be printed as a container of its contents or as a whole.

#include <Corrade/Utility/Debug.h>

template<class T>

Debug& Corrade::Utility::operator<<(Debug& debug, const T& value)

Operator for printing custom types to debug output.

Support for printing custom types (i.e. those not handled by std::iostream) can be added by implementing this function for given type.

The function should convert the type to one of supported types (such as the builtin types or std::string) and then call Debug::operator<<() with it. You can also use Debug::nospace and Debug::newline.

#include <Corrade/Utility/Debug.h>

template<class Iterable>

Debug& Corrade::Utility::operator<<(Debug& debug, const Iterable& value)

Operator for printing iterable types to debug output.

Prints the value as {a, b, c}. If the type contains a nested iterable type, the values are separated by newlines. Specifying Debug::Flag::Packed or using Debug::packed will print the values tightly-packed without commas and spaces in between.

#include <Corrade/Utility/Debug.h>

template<class T, class U>

Debug& Corrade::Utility::operator<<(Debug& debug, const std::pair<T, U>& value)

Print a std::pair to debug output.

Prints the value as (first, second). Unlike operator<<(Debug& debug, const Iterable& value), the output is not affected by Debug::Flag::Packed / Debug::packed.

Debug& Corrade::Utility::operator<<(Debug& debug, const std::string& value)

#include <Corrade/Utility/DebugStl.h>

Print a std::string to debug output.

#include <Corrade/Utility/DebugStl.h>

template<class T>

Debug& Corrade::Utility::operator<<(Debug& debug, const std::basic_string<T>& value)

Print a std::basic_string to debug output.

All other types than exactly std::string are printed as containers.

#include <Corrade/Utility/DebugStl.h>

template<class ... Args>

Debug& Corrade::Utility::operator<<(Debug& debug, const std::tuple<Args...>& value)

Print a std::tuple to debug output.

Prints the value as (first, second, third...). Unlike operator<<(Debug& debug, const Iterable& value), the output is not affected by Debug::Flag::Packed / Debug::packed.

#include <Corrade/Utility/Format.h>

template<class ... Args>

Containers::Array<char> Corrade::Utility::format(const char* format, const Args&... args)

Format a string.

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

std::string s = Utility::formatString("{} version {}.{}.{}, {} MB",
    "vulkan.hpp", 1, 1, 76, 1.79);
// vulkan.hpp version 1.1.76, 1.79 MB

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. Example:

std::string s = Utility::formatString("<{0}><{1}>Good {}, {}!</{1}></{0}>",
    "p", "strong", "afternoon", "ma'am!");
// <p><strong>Good afternoon, ma'am!</strong></p>

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:

std::string s = Utility::formatString("union {{ {} a; char data[{}]; }} caster;",
    "float", sizeof(float));
// union { float a; char data[4]; } caster;

Data type support

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, "%.2x" can be translated to "{:.2x}".

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:

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

Example of formating of CSS colors with correct width:

std::string s = Utility::formatString("path {{ fill: #{:6x}; stroke: #{:6x}; }}",
    0x33ff00, 0x00aa55);
// path { fill: #33ff00; stroke: #00aa55; }

Performance

This function always does exactly one allocation for the output array. See formatInto(std::string&, std::size_t, const char*, const Args&... args) for an ability to write into an existing string (with at most one reallocation) and formatInto(const Containers::ArrayView<char>&, const char*, const Args&... args) for a completely zero-allocation alternative. There is also formatInto(std::FILE*, const char*, const Args&... args) for writing to files or standard output.

Comparison to Debug

Debug class desired usage is for easy printing of complex nested types, containers, enum values or opaque types for logging and diagnostic purposes, with focus on convenience rather than speed or advanced formatting capabilities. The format() family of functions is intended for cases where it's required to have a complete control over the output, for example when serializing text files.

#include <Corrade/Utility/Format.h>

template<class ... Args>

std::size_t Corrade::Utility::formatInto(const Containers::ArrayView<char>& buffer, const char* format, const Args&... args)

Format 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. Example usage:

char shaderVersion[128]; // large enough
std::size_t size = Utility::formatInto(shaderVersion, "#version {}\n", 430);
addShaderSource({shaderVersion, size});

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

#include <Corrade/Utility/Format.h>

template<class ... Args>

void Corrade::Utility::formatInto(std::FILE* file, const char* format, const Args&... args)

Format a string into a file.

Writes formatted output to file, which can be either an arbitrary file opened using std::fopen() or stdout / stderr. Does not allocate on its own (though the underlying file writing routines might), does not write any terminating '\0' character. Example usage:

Utility::formatInto(stdout, "Hello, {}!", "world");

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

#include <Corrade/Utility/Format.h>

template<class ... Args>

void Corrade::Utility::print(const char* format, const Args&... args)

Print a string to the standard output.

Equivalent to calling formatInto(std::FILE*, const char*, const Args&... args) with stdout as a first parameter.

#include <Corrade/Utility/Format.h>

template<class ... Args>

void Corrade::Utility::printError(const char* format, const Args&... args)

Print a string to the standard error output.

Equivalent to calling formatInto(std::FILE*, const char*, const Args&... args) with stderr as a first parameter.

#include <Corrade/Utility/FormatStl.h>

template<class ... Args>

std::string Corrade::Utility::formatString(const char* format, const Args&... args)

Format a string.

Same as format(), but returning a std::string instead of Containers::Array.

#include <Corrade/Utility/FormatStl.h>

template<class ... Args>

std::size_t Corrade::Utility::formatInto(std::string& string, std::size_t offset, const char* format, const Args&... args)

Format a string into an existing string.

Takes an existing string and writes the formatted content starting at offset. If the string is not large enough, does at most one reallocation (by calling std::string::resize()). Returns final written size (which might be less than the string size if inserting in the middle). Does not write any terminating '\0' character. Example usage:

std::vector<float> positions{-0.5f, -0.5f, 0.0f,
                              0.5f, -0.5f, 0.0f,
                              0.0f,  0.5f, 0.0f};
std::string out;
for(std::size_t i = 0; i < positions.size(); i += 3)
    Utility::formatInto(out, out.size(), "{}[{0}, {1}, {2}]",
        out.empty() ? "" : ", ",
        positions[i*3 + 0], positions[i*3 + 1], positions[i*3 + 2]);

// [-0.5, -0.5, 0], [0.5, -0.5, 0], [0.0, 0.5, 0.0]

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

Debug& Corrade::Utility::operator<<(Debug& debug, TweakableState value)

#include <Corrade/Utility/TweakableParser.h>

Debug output operator.

#include <Corrade/Utility/utilities.h>

template<class To, class From>

To Corrade::Utility::bitCast(const From& from)

Cast type to another of the same size.

Unlike reinterpret_cast this doesn't break strict-aliasing rules.