dfx::Utils::Exception Class Reference

Runtime error that captures a std::source_location. More...

#include <dfx-utilities/Exception.hpp>

Inheritance diagram for dfx::Utils::Exception:

Collaboration diagram for dfx::Utils::Exception:

Public Member Functions
template<typename ... Args>
	Exception (std::source_location location, std::format_string< Args ... > message, Args &&... args)
	Construct an exception with a formatted message and a specific source location.
	Exception (std::string const &message) noexcept
	Construct an exception from an already-formatted message.
uint32_t	line () const noexcept
	Return the line number recorded in the associated source location.
char const *	filename () const noexcept
	Return the base filename from the recorded source location.
char const *	function () const noexcept
	Return the function name recorded in the associated source location.

Static Public Member Functions
template<typename ... Args>
static void	throwNested (std::source_location location, std::format_string< Args ... > message, Args &&... args)
	Throw an Exception nested within the currently handled exception.
static ExceptionStack	getExceptionStack (Exception const &e)
	Extract a nested exception chain into an ExceptionStack.
static std::vector< std::string >	exceptionStackToString (Exception const &e, std::size_t initialIndentLevel=0, std::size_t indentSize=2, bool addSourceLocation=true)
	Convert a nested exception chain to a list of printable lines.
static void	printToLogger (Exception const &e, spdlog::level::level_enum lvl=spdlog::level::err, std::string const &loggerName="", std::size_t initialIndentLevel=0, std::string const &logPattern=noFileLogPattern, std::string const &currentLogPattern=defaultLogPattern)
	Log an exception (including nested exceptions) using a logger name.
static void	printToLogger (Exception const &e, std::shared_ptr< spdlog::logger > logger, spdlog::level::level_enum lvl=spdlog::level::err, std::size_t initialIndentLevel=0, std::string const &logPattern=noFileLogPattern, std::string const &currentLogPattern=defaultLogPattern)
	Log an exception (including nested exceptions) using an explicit logger instance.

Detailed Description

Runtime error that captures a std::source_location.

This exception is meant to be thrown via the THROW and THROW_NESTED macros so that file/line/function are captured at the throw site.

The type supports nested exceptions (via std::throw_with_nested) and utilities to:

• extract the nested chain as a vector (getExceptionStack),
• format it as text lines (exceptionStackToString),
• print it to a spdlog logger (printToLogger).

Note

This class stores the provided std::source_location by value. If constructed without a location (see the string-only constructor), the stored location will be default-initialized and may not provide meaningful file/line information.

Constructor & Destructor Documentation

Exception() [1/2]

template<typename ... Args>

dfx::Utils::Exception::Exception ( std::source_location location, std::format_string< Args ... > message, Args &&... args )

inline

Construct an exception with a formatted message and a specific source location.

Parameters

location	Source location to associate with the exception (typically std::source_location::current()).
message	std::format format string.
args	Format arguments.

Exception() [2/2]

dfx::Utils::Exception::Exception ( std::string const & message )

inlinenoexcept

Construct an exception from an already-formatted message.

This overload does not accept a source location and therefore does not provide reliable file/line/function information unless the default-initialized std::source_location happens to carry meaningful values in your standard library implementation.

Member Function Documentation

exceptionStackToString()

std::vector< std::string > dfx::Utils::Exception::exceptionStackToString ( Exception const & e, std::size_t initialIndentLevel = 0, std::size_t indentSize = 2, bool addSourceLocation = true )

static

Convert a nested exception chain to a list of printable lines.

Parameters

e	The exception to inspect (outer-most).
initialIndentLevel	Initial indentation level (in multiples of indentSize).
indentSize	Number of spaces per indentation level.
addSourceLocation	When true, include file/line/function information when available.

Returns

One string per stack frame (outer-most first).

filename()

char const * dfx::Utils::Exception::filename ( ) const

inlinenoexcept

Return the base filename from the recorded source location.

function()

char const * dfx::Utils::Exception::function ( ) const

inlinenoexcept

Return the function name recorded in the associated source location.

getExceptionStack()

ExceptionStack dfx::Utils::Exception::getExceptionStack ( Exception const & e )

static

Extract a nested exception chain into an ExceptionStack.

Walks the std::nested_exception chain (if any) starting from e.

Parameters

e	The exception to inspect (outer-most).

line()

uint32_t dfx::Utils::Exception::line ( ) const

inlinenoexcept

Return the line number recorded in the associated source location.

printToLogger() [1/2]

void dfx::Utils::Exception::printToLogger ( Exception const & e, spdlog::level::level_enum lvl = spdlog::level::err, std::string const & loggerName = "", std::size_t initialIndentLevel = 0, std::string const & logPattern = noFileLogPattern, std::string const & currentLogPattern = defaultLogPattern )

static

Log an exception (including nested exceptions) using a logger name.

The function temporarily switches the logger pattern to logPattern for printing, then restores currentLogPattern afterwards.

Parameters

e	Exception to print.
lvl	spdlog level to use.
loggerName	Logger name as registered in spdlog (empty string may mean the default logger depending on your setup).
initialIndentLevel	Initial indentation level for multi-line stacks.
logPattern	Pattern used while printing the exception stack.
currentLogPattern	Pattern restored after printing.

printToLogger() [2/2]

void dfx::Utils::Exception::printToLogger ( Exception const & e, std::shared_ptr< spdlog::logger > logger, spdlog::level::level_enum lvl = spdlog::level::err, std::size_t initialIndentLevel = 0, std::string const & logPattern = noFileLogPattern, std::string const & currentLogPattern = defaultLogPattern )

static

Log an exception (including nested exceptions) using an explicit logger instance.

Parameters

e	Exception to print.
logger	Logger instance to use (must be non-null to have any effect).
lvl	spdlog level to use.
initialIndentLevel	Initial indentation level for multi-line stacks.
logPattern	Pattern used while printing the exception stack.
currentLogPattern	Pattern restored after printing.

throwNested()

template<typename ... Args>

void dfx::Utils::Exception::throwNested ( std::source_location location, std::format_string< Args ... > message, Args &&... args )

inlinestatic

Throw an Exception nested within the currently handled exception.

Intended usage is inside a catch block:

try { ... }
catch (...) { THROW_NESTED("while doing X"); }

Internally calls std::throw_with_nested(Exception(...)).

---

The documentation for this class was generated from the following file:

• lib/dfx-utilities/Exception.hpp