Corrade::Utility::Debug class

Debug output handler.

Contents

Provides convenient stream interface for passing data to debug output (standard output). Data are by default separated with spaces and last value is enclosed with newline character. Example usage:

// Common usage
Debug{} << "string" << 34 << 275.0f;

// Redirect debug output to string
std::ostringstream out;
Debug{&out} << "the meaning of life, universe and everything is" << 42;

// Mute debug output
Debug{nullptr} << "no one should see my ebanking password" << password;

// Conditional debug output (avoid inserting newline where it's not desired)
Debug d;
d << "Cannot foo";
if(bar)
    d << "because of bar.";
else
    d << "because of everything else.";
// (newline character will be written to output on object destruction)

Support for printing more types can be added by implementing function operator<<(Debug&, const T&) for given type. If there is no operator<<() implemented for printing given type using the Debug class, suitable std::ostream operator<<() overload is used as fallback, if found.

Scoped output redirection

Output specified in class constructor is used for all instances created during that instance lifetime. Debug, Warning and Error classes outputs can be controlled separately:

std::ostringstream debugOut, errorOut;

Error{} << "this is printed into std::cerr";

Error redirectError{&errorOut};

{
    Debug redirectDebug{&debugOut};

    Debug{} << "this is printed into debugOut";
    Error{} << "this is printed into errorOut";
    Debug{} << "this is also printed into debugOut";
}

Debug{} << "this is printed into std::cout again";
Error{} << "this is still printed into errorOut";

Output modifiers

It's possible to modify the debug output by passing a special function to the output stream.

Explicit whitespace control

Sometimes you might not want to have everything separated by spaces or having newline at the end:

// Prints "Value: 16, 24"
Debug{} << "Value:" << 16 << Debug::nospace << "," << 24;

// Prints "Value\n16"
Debug{} << "Value:" << Debug::newline << 16;

// Doesn't output newline at the end
Debug{Debug::Flag::NoNewlineAtTheEnd} << "Hello!";

Colored output

It is possible to color the output using color() and boldColor(). The color is automatically reset to previous value on destruction to avoid messing up the terminal, you can also use resetColor() to reset it explicitly.

Debug{} << Debug::boldColor(Debug::Color::Green) << "Success!"
        << Debug::resetColor << "Everything is fine.";

On POSIX the coloring is done using ANSI color escape sequences and works both when outputting to a terminal or any other stream. On Windows, by default due to a platform limitation, the colored output works only when outputting directly to a terminal without any intermediate buffer. See CORRADE_UTILITY_USE_ANSI_COLORS for possible alternative.

Note that colors make sense only when they finally appear in a terminal and not when redirecting output to file. You can control this by setting Flag::DisableColors based on value of isTty(), for example:

Debug::Flags flags = Debug::isTty() ? Debug::Flags{} : Debug::Flag::DisableColors;
Debug{flags} << Debug::boldColor(Debug::Color::Green) << "Success!";

Similarly as with scoped output redirection, colors can be also scoped:

Debug{} << "this has default color";

{
    Debug d;
    if(errorHappened) d << Debug::color(Debug::Color::Red);

    Debug{} << "if an error happened, this will be printed red";
    Debug{} << "this also" << Debug::boldColor(Debug::Color::Blue) << "and this blue";
}

Debug{} << "this has default color again";

Derived classes

class Error
Error output handler.
class Warning
Warning output handler.

Public types

enum class Flag: unsigned char { NoNewlineAtTheEnd = 1 << 0, DisableColors = 1 << 1 }
Debug output flag.
using Flags = Containers::EnumSet<Flag>
Debug output flags.

Public static functions

static auto noNewlineAtTheEnd() -> Debug deprecated
Debug output without newline at the end.
static auto noNewlineAtTheEnd(std::ostream* output) -> Debug deprecated
Debug output without newline at the end.
static void setOutput(std::ostream* output) deprecated
Set output for instances in this scope.
static auto output() -> std::ostream*
Current debug output stream.
static auto isTty(std::ostream* output) -> bool
Whether given output stream is a TTY.
static auto isTty() -> bool
Whether current debug output is a TTY.

Constructors, destructors, conversion operators

Debug(Flags flags = {}) explicit
Default constructor.
Debug(std::ostream* output, Flags flags = {}) explicit
Constructor.
Debug(const Debug&) deleted
Copying is not allowed.
Debug(Debug&&) defaulted
Move constructor.
~Debug()
Destructor.

Public functions

auto operator=(const Debug&) -> Debug& deleted
Copying is not allowed.
auto operator=(Debug&&) -> Debug& deleted
Move assignment is not allowed.
auto operator<<(const std::string& value) -> Debug&
Print string to debug output.
auto operator<<(const char* value) -> Debug&
auto operator<<(const void* value) -> Debug&
auto operator<<(bool value) -> Debug&
auto operator<<(int value) -> Debug&
auto operator<<(long value) -> Debug&
auto operator<<(long long value) -> Debug&
auto operator<<(unsigned value) -> Debug&
auto operator<<(unsigned long value) -> Debug&
auto operator<<(unsigned long long value) -> Debug&
auto operator<<(float value) -> Debug&
Print float value to debug output.
auto operator<<(double value) -> Debug&
Print double value to debug output.
auto operator<<(long double value) -> Debug&
Print long double value to debug output.
auto operator<<(char32_t value) -> Debug&
Print UTF-32 character to debug output.
auto operator<<(const char32_t* value) -> Debug&
Print UTF-32 character literal to debug output.

Output modifiers

See Output modifiers for more information.

enum class Color: char { Black = 0, Red = 1, Green = 2, Yellow = 3, Blue = 4, Magenta = 5, Cyan = 6, White = 7, Default = 9 }
Output color.
using Modifier = void(*)(Debug&)
Debug output modifier.
static void nospace(Debug& debug)
Don't put space before next value.
static void newline(Debug& debug)
Output a newline.
static auto color(Color color) -> Modifier
Set output color.
static auto boldColor(Color color) -> Modifier
Set bold output color.
static void resetColor(Debug& debug)
Reset output color.
auto operator<<(Modifier f) -> Debug&
Debug output modification.

Enum documentation

enum class Corrade::Utility::Debug::Flag: unsigned char

Debug output flag.

Enumerators
NoNewlineAtTheEnd

Don't put newline at the end on destruction
DisableColors

Disable colored output in color(), boldColor() and resetColor().

enum class Corrade::Utility::Debug::Color: char

Output color.

Enumerators
Black

Black
Red

Red
Green

Green
Yellow

Yellow
Blue

Blue
Magenta

Magenta
Cyan

Cyan
White

White
Default

Default (implementation/style-defined)

Typedef documentation

typedef Containers::EnumSet<Flag> Corrade::Utility::Debug::Flags

Debug output flags.

typedef void(*Corrade::Utility::Debug::Modifier)(Debug&)

Debug output modifier.

Function documentation

static Debug Corrade::Utility::Debug::noNewlineAtTheEnd()

Debug output without newline at the end.

static Debug Corrade::Utility::Debug::noNewlineAtTheEnd(std::ostream* output)

Debug output without newline at the end.

static void Corrade::Utility::Debug::setOutput(std::ostream* output)

Set output for instances in this scope.

static std::ostream* Corrade::Utility::Debug::output()

Current debug output stream.

Debug output constructed with the Debug(Flags) constructor will be using this output stream.

static bool Corrade::Utility::Debug::isTty(std::ostream* output)

Whether given output stream is a TTY.

Useful for deciding whether to use ANSI colored output using Flag::DisableColors. Returns true if output is a pointer to std::cout / std::cerr and the stream is not redirected to a file, false otherwise. Calls isatty() on Unix-like systems and Windows with CORRADE_UTILITY_USE_ANSI_COLORS enabled, calls Windows APIs if CORRADE_UTILITY_USE_ANSI_COLORS is disabled. On platforms without isatty() equivalent returns always false.

static bool Corrade::Utility::Debug::isTty()

Whether current debug output is a TTY.

Calls isTty(std::ostream*) with output of enclosing Debug instance or with std::cerr if there isn't any.

Corrade::Utility::Debug::Debug(Flags flags = {}) explicit

Default constructor.

Parameters
flags Output flags

Uses output of enclosing Debug instance or uses std::cout if there isn't any.

Corrade::Utility::Debug::Debug(std::ostream* output, Flags flags = {}) explicit

Constructor.

Parameters
output Stream where to put debug output. If set to nullptr, no debug output will be written anywhere.
flags Output flags

All new instances created using the default Debug() constructor during lifetime of this instance will inherit the output set in output.

Corrade::Utility::Debug::~Debug()

Destructor.

Resets the output redirection back to the output of enclosing scope. If there was any output, adds newline at the end. Also resets output color modifier, if there was any.

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

Print string to debug output.

If there is already something on the output, puts space before the value, unless nospace() was set immediately before.

Debug& Corrade::Utility::Debug::operator<<(const char* value)

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

Debug& Corrade::Utility::Debug::operator<<(const void* value)

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

Debug& Corrade::Utility::Debug::operator<<(bool value)

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

Debug& Corrade::Utility::Debug::operator<<(int value)

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

Debug& Corrade::Utility::Debug::operator<<(long value)

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

Debug& Corrade::Utility::Debug::operator<<(long long value)

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

Debug& Corrade::Utility::Debug::operator<<(unsigned value)

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

Debug& Corrade::Utility::Debug::operator<<(unsigned long value)

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

Debug& Corrade::Utility::Debug::operator<<(unsigned long long value)

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

Debug& Corrade::Utility::Debug::operator<<(float value)

Print float value to debug output.

Prints the value with 6 significant digits.

Debug& Corrade::Utility::Debug::operator<<(double value)

Print double value to debug output.

Prints the value with 15 significant digits.

Debug& Corrade::Utility::Debug::operator<<(long double value)

Print long double value to debug output.

Prints the value with 18 significant digits.

Debug& Corrade::Utility::Debug::operator<<(char32_t value)

Print UTF-32 character to debug output.

Prints value as Unicode codepoint, i.e. U+0061.

Debug& Corrade::Utility::Debug::operator<<(const char32_t* value)

Print UTF-32 character literal to debug output.

Prints value as list of Unicode codepoints, i.e. [U+0061, U+0062, U+0063}.

static void Corrade::Utility::Debug::nospace(Debug& debug)

Don't put space before next value.

Debug output by default separates values with space, this disables it for the immediately following value. The default behavior is then restored. The following line outputs Value: 16, 24:

Debug() << "Value:" << 16 << Debug::nospace << "," << 24;

static void Corrade::Utility::Debug::newline(Debug& debug)

Output a newline.

Puts a newline (not surrounded by spaces) to the output. The following two lines are equivalent:

Debug() << "Value:" << Debug::newline << 16;
Debug() << "Value:" << Debug::nospace << "\n" << Debug::nospace << 16;

and their output is

Value:
16

static Modifier Corrade::Utility::Debug::color(Color color)

Set output color.

Resets previous color() or boldColor() setting. The color is also automatically reset on object destruction to a value that was active in outer scope. If Flag::DisableColors was set, this function does nothing.

static Modifier Corrade::Utility::Debug::boldColor(Color color)

Set bold output color.

Resets previous color() or boldColor() setting. The color is also automatically reset on object destruction to a value that was active in outer scope. If Flag::DisableColors was set, this function does nothing.

static void Corrade::Utility::Debug::resetColor(Debug& debug)

Reset output color.

Resets any previous color() or boldColor() setting to a value that was active in outer scope. The same is also automatically done on object destruction. If the color was not changed by this instance or Flag::DisableColors was set, this function does nothing.

Debug& Corrade::Utility::Debug::operator<<(Modifier f)

Debug output modification.

See Output modifiers for more information.

template<class T>
Debug& operator<<(Debug& debug, const T& value)

Operator for printing custom types to debug.

Parameters
debug Debug class
value Value to be printed

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 std::string) and then call Debug::operator<<(const std::string&) with it. You can also use Debug::nospace() and Debug::newline().

template<class Iterable>
Debug& operator<<(Debug& debug, const Iterable& value)

Operator for printing iterable types to debug.

Prints the value as {a, b, c}.

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

Operator for printing tuple types to debug.

Prints the value as (first, second, third...).

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

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