namespace
UtilityUtitlities.
Contents
- Reference
This library contains utility classes used by all other Corrade parts, like debug and error output (class Debug), access to configuration files (class Configuration) or compiling data files into the executable (class Resource, see also tutorial).
This library is built if WITH_UTILITY
is enabled when building Corrade. To use this library with CMake, request the Utility
component of the Corrade
package and link to the Corrade::Utility
target:
find_package(Corrade REQUIRED Utility) # ... target_link_libraries(your-app PRIVATE Corrade::Utility)
Parts of this library are additionally available in a form of single-header libraries. See also Downloading and building Corrade and Using Corrade with CMake for more information.
Namespaces
- namespace Directory
- Filesystem utilities.
- namespace Endianness
- Endianness-related functions.
- namespace String
- String utilities.
- namespace System
- System utilities.
- namespace Unicode
- Unicode utilities.
Classes
-
template<std::class AbstractHash
size_t digestSize> - Base template for hashing classes.
- class AndroidLogStreamBuffer
- Stream buffer that sends the data to Android log.
- class Arguments
- Command-line argument parser.
- class Configuration
- Parser and writer for configuration files.
- class ConfigurationGroup
- Group of values in configuration file.
-
template<class T>struct ConfigurationValue
- Configuration value parser and writer.
-
template<>struct ConfigurationValue<bool>
- Configuration value parser and writer for
bool
type. -
template<>struct ConfigurationValue<char32_t>
- Configuration value parser and writer for
char32_t
type. -
template<>struct ConfigurationValue<Containers::String> new in Git master
- Configuration value parser and writer for Containers::
String. -
template<>struct ConfigurationValue<Containers::StringView> new in Git master
- Configuration value parser and writer for Containers::
StringView. -
template<>struct ConfigurationValue<double>
- Configuration value parser and writer for the
double
type. -
template<>struct ConfigurationValue<float>
- Configuration value parser and writer for the
float
type. -
template<>struct ConfigurationValue<int>
- Configuration value parser and writer for the
int
type. -
template<>struct ConfigurationValue<long>
- Configuration value parser and writer for the
long
type. -
template<>struct ConfigurationValue<long double>
- Configuration value parser and writer for
long double
type. -
template<>struct ConfigurationValue<long long>
- Configuration value parser and writer for the
long long
type. -
template<>struct ConfigurationValue<short>
- Configuration value parser and writer for the
short
type. -
template<>struct ConfigurationValue<std::string>
- Configuration value parser and writer for std::
string type. -
template<>struct ConfigurationValue<unsigned int>
- Configuration value parser and writer for the
unsigned int
type. -
template<>struct ConfigurationValue<unsigned long>
- Configuration value parser and writer for the
unsigned long
type. -
template<>struct ConfigurationValue<unsigned long long>
- Configuration value parser and writer for the
unsigned long long
type. -
template<>struct ConfigurationValue<unsigned short>
- Configuration value parser and writer for the
unsigned short
type. - class Debug
- Debug output handler.
- class Error
- Error output handler.
- class Fatal
- Fatal output handler.
- class FileWatcher
- File watcher.
-
template<std::class HashDigest
size_t size> - Hash digest.
- class MurmurHash2
- MurmurHash 2.
- class Resource
- Data resource management.
- class Sha1
- SHA-1.
- class Tweakable
- Tweakable constants.
-
template<class T>struct TweakableParser
- Parser for Tweakable types.
-
template<>struct TweakableParser<bool>
- Tweakable constant parser for the
bool
type. -
template<>struct TweakableParser<char>
- Tweakable constant parser for the
char
type. -
template<>struct TweakableParser<double>
- Tweakable constant parser for the
double
type. -
template<>struct TweakableParser<float>
- Tweakable constant parser for the
float
type. -
template<>struct TweakableParser<int>
- Tweakable constant parser for the
int
type. -
template<>struct TweakableParser<long>
- Tweakable constant parser for the
long int
type. -
template<>struct TweakableParser<long double>
- Tweakable constant parser for the
long double
type. -
template<>struct TweakableParser<long long>
- Tweakable constant parser for the
long long int
type. -
template<>struct TweakableParser<unsigned int>
- Tweakable constant parser for the
unsigned int
type. -
template<>struct TweakableParser<unsigned long>
- Tweakable constant parser for the
unsigned long int
type. -
template<>struct TweakableParser<unsigned long long>
- Tweakable constant parser for the
unsigned long long int
type. - class Warning
- Warning output handler.
Enums
-
enum class ConfigurationValueFlag: std::
uint8_t { Oct = 1 << 0, Hex = 1 << 1, Scientific = 1 << 2, Uppercase = 1 << 3 } - Configuration value conversion flag.
-
enum class TweakableState: std::
uint8_t { NoChange = 0, Success = 1, Recompile = 2, Error = 3 } - Tweakable state.
Typedefs
-
using ConfigurationValueFlags = Containers::
EnumSet<ConfigurationValueFlag> - Configuration value conversion flags.
-
template<class T>using IsIterable = std::
integral_constant<bool, implementation-specific> - Traits class for checking whether given type is iterable.
-
template<class T>using IsStringLike = std::
integral_constant<bool, implementation-specific> new in 2019.10 - Traits class for checking whether given type is string-like.
Functions
-
void copy(const Containers::
ArrayView<const void>& src, const Containers:: ArrayView<void>& dst) new in 2020.06 - Copy an array view to another.
-
template<class T>void copy(const Containers::
ArrayView<const T>& src, const Containers:: ArrayView<T>& dst) new in 2020.06 - Copy an array view to another.
-
template<unsigned dimensions>void copy(const Containers::
StridedArrayView<dimensions, const char>& src, const Containers:: StridedArrayView<dimensions, char>& dst) new in 2020.06 - Copy a strided array view to another.
-
void copy(const Containers::
StridedArrayView1D<const char>& src, const Containers:: StridedArrayView1D<char>& dst) new in 2020.06 -
void copy(const Containers::
StridedArrayView2D<const char>& src, const Containers:: StridedArrayView2D<char>& dst) new in 2020.06 -
void copy(const Containers::
StridedArrayView3D<const char>& src, const Containers:: StridedArrayView3D<char>& dst) new in 2020.06 -
void copy(const Containers::
StridedArrayView4D<const char>& src, const Containers:: StridedArrayView4D<char>& dst) new in 2020.06 -
template<unsigned dimensions, class T>void copy(const Containers::
StridedArrayView<dimensions, const T>& src, const Containers:: StridedArrayView<dimensions, T>& dst) new in 2020.06 - Copy a strided array view to another.
-
template<class From, class To, class FromView = decltype(Implementation::stridedArrayViewTypeFor(std::void copy(From&& src, To&& dst) new in 2020.06
declval<From && >())), class ToView = decltype(Implementation::stridedArrayViewTypeFor(std:: declval<To && >()))> - Copy a view to another.
- auto operator!(Implementation::DebugSourceLocation debug) -> Debug& new in 2020.06
- Prefix the output with source location.
-
template<class T>auto operator<<(Debug& debug, const T& value) -> Debug&
- Operator for printing custom types to debug output.
-
template<class Iterable>auto operator<<(Debug& debug, const Iterable& value) -> Debug&
- Operator for printing iterable types to debug output.
-
template<class T, class U>auto operator<<(Debug& debug, const std::
pair<T, U>& value) -> Debug& - Print a std::
pair to debug output. -
auto operator<<(Debug& debug,
const std::
string& value) -> Debug& - Print a std::
string to debug output. -
template<class T>auto operator<<(Debug& debug, const std::
basic_string<T>& value) -> Debug& - Print a std::
basic_string to debug output. -
template<class ... Args>auto operator<<(Debug& debug, const std::
tuple<Args...>& value) -> Debug& - Print a std::
tuple to debug output. -
template<class ... Args>auto format(const char* format, const Args&... args) -> Containers::
Array<char> new in 2019.10 - Format a string.
-
template<class ... Args>auto formatInto(const Containers::
ArrayView<char>& buffer, const char* format, const Args&... args) -> std:: size_t - Format a string into an existing buffer.
-
template<class ... Args>void formatInto(std::
FILE* file, const char* format, const Args&... args) - Format a string into a file.
-
template<class ... Args>void print(const char* format, const Args&... args)
- Print a string to the standard output.
-
template<class ... Args>void printError(const char* format, const Args&... args)
- Print a string to the standard error output.
-
template<class ... Args>auto formatString(const char* format, const Args&... args) -> std::
string - Format a string.
-
template<class ... Args>auto formatInto(std::
string& string, std:: size_t offset, const char* format, const Args&... args) -> std:: size_t - Format a string into an existing string.
- auto operator<<(Debug& debug, TweakableState value) -> Debug&
- Debug output operator.
Type utilities
-
template<class To, class From>auto bitCast(const From& from) -> To
- Cast type to another of the same size.
Enum documentation
enum class Corrade:: Utility:: ConfigurationValueFlag: std:: uint8_t
Configuration value conversion flag.
Enumerators | |
---|---|
Oct |
Numeric value as octal |
Hex |
Numeric value as hexadecimal |
Scientific |
Floating point values in scientific notation |
Uppercase |
Use uppercase characters for numeric output |
enum class Corrade:: Utility:: TweakableState: std:: uint8_t
#include <Corrade/Utility/TweakableParser.h>
Tweakable state.
Enumerators | |
---|---|
NoChange |
No source file has any changes that affect tweakable values. Nothing to do. |
Success |
Tweakable values in some source files were changed and successfully updated. Values that are neither accessed in the main event loop nor were part of any Tweakable:: |
Recompile |
Source files were changed in a way that can't be handled by updating just the tweakable values alone. No values were updated, hot-reload the affected code or restart a recompiled version of the app to pick up the changes. Note that this state is optimistic — it may happen that the changes will lead to a compile error similarly as with TweakableState:: |
Error |
Source files were changed in a way that caused a parse error. No values were updated, fix the error and save the file again to retry the parsing. This state is returned only when the utility is absolutely sure there is a syntax error (for example when a char literal is not terminated). If not sure, TweakableState:: |
Typedef documentation
typedef Containers:: EnumSet<ConfigurationValueFlag> Corrade:: Utility:: ConfigurationValueFlags
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::begin()
/ end()
members, is usable with free begin()
/ end()
functions or has std::
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> new in 2019.10
Traits class for checking whether given type is string-like.
Equivalent to std::c_str()
member or is a Containers::
Used together with IsIterable by Debug to decide whether given type should be printed as a container of its contents or as a whole.
Function documentation
void Corrade:: Utility:: copy(const Containers:: ArrayView<const void>& src,
const Containers:: ArrayView<void>& dst) new in 2020.06
#include <Corrade/Utility/Algorithms.h>
Copy an array view to another.
Calls std::
#include <Corrade/Utility/Algorithms.h>
template<class T>
void Corrade:: Utility:: copy(const Containers:: ArrayView<const T>& src,
const Containers:: ArrayView<T>& dst) new in 2020.06
Copy an array view to another.
Casts views into a void
type and delegates into copy(const Containers::T
is a trivially copyable type.
#include <Corrade/Utility/Algorithms.h>
template<unsigned dimensions>
void Corrade:: Utility:: copy(const Containers:: StridedArrayView<dimensions, const char>& src,
const Containers:: StridedArrayView<dimensions, char>& dst) new in 2020.06
Copy a strided array view to another.
Optimized to call std::
void Corrade:: Utility:: copy(const Containers:: StridedArrayView1D<const char>& src,
const Containers:: StridedArrayView1D<char>& dst) new in 2020.06
#include <Corrade/Utility/Algorithms.h>
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void Corrade:: Utility:: copy(const Containers:: StridedArrayView2D<const char>& src,
const Containers:: StridedArrayView2D<char>& dst) new in 2020.06
#include <Corrade/Utility/Algorithms.h>
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void Corrade:: Utility:: copy(const Containers:: StridedArrayView3D<const char>& src,
const Containers:: StridedArrayView3D<char>& dst) new in 2020.06
#include <Corrade/Utility/Algorithms.h>
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void Corrade:: Utility:: copy(const Containers:: StridedArrayView4D<const char>& src,
const Containers:: StridedArrayView4D<char>& dst) new in 2020.06
#include <Corrade/Utility/Algorithms.h>
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
#include <Corrade/Utility/Algorithms.h>
template<unsigned dimensions, class T>
void Corrade:: Utility:: copy(const Containers:: StridedArrayView<dimensions, const T>& src,
const Containers:: StridedArrayView<dimensions, T>& dst) new in 2020.06
Copy a strided array view to another.
Casts views into a char
type of one dimension more (where the last dimension has a size of sizeof(T)
and delegates into copy(const Containers::T
is a trivially copyable type.
#include <Corrade/Utility/Algorithms.h>
template<class From, class To, class FromView = decltype(Implementation::stridedArrayViewTypeFor(std:: declval<From && >())), class ToView = decltype(Implementation::stridedArrayViewTypeFor(std:: declval<To && >()))>
void Corrade:: Utility:: copy(From&& src,
To&& dst) new in 2020.06
Copy a view to another.
Converts src
and dst
to a common array view type that's either Containers::dst
is not const
.
Debug& Corrade:: Utility:: operator!(Implementation::DebugSourceLocation debug) new in 2020.06
#include <Corrade/Utility/Debug.h>
Prefix the output with source location.
Only on supported compilers, does nothing otherwise. See Source location for more information.
#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.
Parameters | |
---|---|
debug | Debug class |
value | Value to be printed |
Support for printing custom types (i.e. those not handled by std::
The function should convert the type to one of supported types (such as the builtin types or std::
#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::
#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::
Prints the value as (first, second)
. Unlike operator<<(Debug& debug, const Iterable& value), the output is not affected by Debug::
Debug& Corrade:: Utility:: operator<<(Debug& debug,
const std:: string& value)
#include <Corrade/Utility/DebugStl.h>
Print a std::
#include <Corrade/Utility/DebugStl.h>
template<class T>
Debug& Corrade:: Utility:: operator<<(Debug& debug,
const std:: basic_string<T>& value)
Print a std::
All other types than exactly std::
#include <Corrade/Utility/DebugStl.h>
template<class ... Args>
Debug& Corrade:: Utility:: operator<<(Debug& debug,
const std:: tuple<Args...>& value)
Print a std::
Prints the value as (first, second, third...)
. Unlike operator<<(Debug& debug, const Iterable& value), the output is not affected by Debug::
#include <Corrade/Utility/Format.h>
template<class ... Args>
Containers:: Array<char> Corrade:: Utility:: format(const char* format,
const Args&... args) new in 2019.10
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
Type | Behavior |
---|---|
char , unsigned char | Written as an integer (not as a character) |
short , unsigned short | Written as an integer |
int , unsigned int | Written as an integer |
long , unsigned long | Written as an integer |
long long , unsigned long long | Written as an integer |
float | Written as a float with 6 significant digits by default |
double | Written as a float with 15 significant digits by default |
long double | Written 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 |
char* | Written as a sequence of characters until '\0' (which is not written) |
Containers:: MutableStringView, String | Written as a sequence of Containers:: |
Containers:: | Written as a sequence of Containers:: Deprecated, use Containers:: |
std:: | Written as a sequence of std:: ( #include Corrade/ |
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 -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:
Value | Meaning |
---|---|
'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. |
none | Default 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:
Type | Meaning |
---|---|
Integers | If 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 specifier | The 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 specifier | The 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 specifier | The 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 | 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. |
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::
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 format() 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::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 format() 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::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::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::
#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.