fcf::Exception class

Type:

class fcf::Exception

Base class: std::exception

File: bits/PartException/ExceptionDecl.hpp ( link_to_the_text_position_in_the_file )

Available from version: 1.0.1

A robust, feature-rich exception class providing detailed diagnostic information, support for parameterized messages, and exception nesting.

The fcf::Exception class is the foundation of the framework's error handling mechanism. Unlike a standard exception, it is designed to capture rich context about the error, including the exact file and line number where it occurred, and support dynamic message formatting using placeholders.

Key capabilities include:

Parameterized Messages: Supports templates like "Error at ${{1}}$" where arguments are automatically injected into the final message during formatting.
Rich Diagnostics: Provides access to the source file, line number, and a formatted message containing the error context via position and message methods.
Exception Nesting: Allows attaching sub-exceptions to a primary exception, creating a hierarchy of errors that can be traversed and displayed using the full method.
Macro-driven Declaration: Easily define custom exception types with specific argument counts using the FCF_EXCEPTION_DECLARE macro.

Methods

[CONSTRUCTOR] Exception()

[CONSTRUCTOR] Exception(const fcf::Exception& a_exception)

[CONSTRUCTOR] Exception(const fcf::Exception& a_exception, bool a_copySub)

template <typename ...TArgPack>
[CONSTRUCTOR] Exception(const char* a_file, unsigned int a_line, const TArgPack&... a_argPack)

template <typename ...TArgPack>
[CONSTRUCTOR] Exception(const char* a_shortMessage, const char* a_patternMessage, const char* a_file, unsigned int a_line, const TArgPack&... a_argPack)

template <typename ...TArgPack>
[CONSTRUCTOR] Exception(const fcf::Exception& a_subException, const char* a_file, unsigned int a_line, const TArgPack&... a_argPack)

template <typename ...TArgPack>
[CONSTRUCTOR] Exception(const fcf::Exception& a_subException, const char* a_shortMessage, const char* a_patternMessage, const char* a_file, unsigned int a_line, const TArgPack&... a_argPack)

- Initializes a new instance of the fcf::Exception class. Depending on the arguments provided, it can create a simple error, an error with an associated exception object, or a complex exception with formatted messages and arguments.

const char* what() const

- Returns a string containing the full error description, including the formatted message and the source code position.

const char* name() const

- Returns the unique string identifier of the exception type.

std::string message() const

- Returns the dynamically formatted error message string.

std::string position() const

- Returns a string representing the source code location where the exception occurred.

const char* file() const

- Returns the name of the file where the exception occurred.

unsigned int line() const

- Returns the line number where the exception occurred.

std::string info() const

- Returns a human-readable summary of the exception information.

std::string full() const

- Returns a comprehensive, hierarchical description of the exception and all its sub-exceptions.

const fcf::Exception& nested(size_t a_index) const

- Provides access to a specific nested exception within the exception hierarchy.

size_t nestedSize() const

- Returns the number of nested exceptions contained within this exception.

bool operator bool() const

- Checks whether the exception object contains any error information (a non-empty message).

Example: Custom Exception with Parameterized Messages

Demonstrates how to define a custom exception using FCF_EXCEPTION_DECLARE, throw it with dynamic arguments, and retrieve detailed diagnostic information.

#include <iostream> #define FCF_BASIS_IMPLEMENTATION #include <fcfBasis/basis.hpp> // 1. Define a custom exception using the framework macro. // This exception is configured to accept 2 arguments for its message template. FCF_EXCEPTION_DECLARE(MyCustomException, "MY_CUSTOM_ERR", "Custom error: ${{1}}$ with value ${{2}}$", 2); int main(int argc, char** argv) { try { // 2. Trigger the custom exception with specific arguments. // The arguments will be used to fill the placeholders in the message. throw MyCustomException(__FILE__, __LINE__, "Operation failed", 100); } catch (const fcf::Exception& e) { // 3. Log the formatted message (placeholders are resolved here). std::cout << "Caught exception: " << e.message() << std::endl; // 4. Log the source code position (file and line). std::cout << "\nPosition: " << e.position() << std::endl; // 5. Log the 'what' diagnostic report. std::cout << "\nWhat result:\n" << e.what() << std::endl; // 6. Log the complete diagnostic report. std::cout << "\nFull Info:\n" << e.full() << std::endl; } return 0; }

Output:

Caught exception: Custom error: Operation failed with value 100 Position: /home/phoenix/Projects/fcfcpp/documentation/fcfBasis/fcf-Exception/main.cpp:14 What result: Custom error: Operation failed with value 100 Position: /home/phoenix/Projects/fcfcpp/documentation/fcfBasis/fcf-Exception/main.cpp:14 Full Info: Error: MY_CUSTOM_ERR Message: Custom error: Operation failed with value 100 Position: /home/phoenix/Projects/fcfcpp/documentation/fcfBasis/fcf-Exception/main.cpp:14