3.0.0
|
|
Freundlich's C++ toolkit |
Macros and functions for assertions.
So called assertions are conditions in the source code that are checked at runtime. If the conditions do not hold, then some sort of error mechanism should be invoked. So, assertions fit into the greater picture of error handling, where they play an important role.
Error handling in C++ can be done using different mechanisms:
Checking return values of functions, acting appropriately when an error has occurred.
Throwing an exception, which may be caught later.
Calling std::terminate
.
Using other mechanisms like C's assert
macro, which might call std::abort
A lot of times you might hear that exceptions are the superior mechanism, and that you should never use return values to indicate errors or even abort the program.
The important thing to realize here is that there are different kinds of errors, that should be handled differently.
In this case, a function should definitely report this as a return value, probably using something like fcppt::optional.
Here an exception is usually a good choice. Common errors in this category include: Resources are exhausted and normal program execution is not possible, a file that should be there is missing, and so on.
This usually indicates a programming mistake. Throwing an exception here is almost never the right thing to do because code cannot be expected to recover from this.
An example for this would be a switch over an enum that handles every possible enumerator. The default case should never be reached. In such a case, throwing an exception would also be meaningless.
As previously outlined, errors not only fall into different categories, but you also want to act upon them differently. fcppt provides different assert macros to do that. For most of the macros, there also exists a message variant that lets you specify an additional message for what went wrong.
These should be used to check pre conditions for a function and they will terminate the program if they are violated.
These should be used to check for post conditions of functions. They will throw an exception on failure.
These should be used if something in the middle of a function goes wrong that could be considered a delayed pre condition. They will also terminate the program if they are violated.
These can generally be used as a replacement for throwing exceptions.
This macro can be used as a placeholder for unimplemented features. It must be given a message describing what feature is missing, and it will terminate the program.
These should be used to check for unreachable code, like reaching a default case in a switch that handles every possible enum value. They will terminate the program.
Here is an example on how to use the pre and post condition macros:
The usual case where every enumerator is handled in a switch can be tested as follows:
Another important feature is that assertions should be as elaborate as possible. Therefore, every macro gathers information about the current file, line of the current file, the current function's name, the failed assertion and the optional message. If a macro terminates the program, the message will be printed to cerr
before that happens. If a macro throws an exception, that exception will be constructed with an fcppt::assert_::information object that holds the information instead.
An exception that is to receive such information must have a constructor that takes an fcppt::assert_::information object.
Header file | Description |
---|---|
error.hpp | Contains FCPPT_ASSERT_ERROR |
error_message.hpp | Contains FCPPT_ASSERT_ERROR_MESSAGE |
exception.hpp | Contains fcppt::assert_::exception |
information_fwd.hpp | Contains fcppt::assert_::information's declaration |
information.hpp | Contains fcppt::assert_::information's definition |
make_message.hpp | Contains the fcppt::assert_::make_message function |
optional_error.hpp | Contains FCPPT_ASSERT_OPTIONAL_ERROR |
post.hpp | Contains FCPPT_ASSERT_POST |
post_message.hpp | Contains FCPPT_ASSERT_POST_MESSAGE |
pre.hpp | Contains FCPPT_ASSERT_PRE |
pre_message.hpp | Contains FCPPT_ASSERT_PRE_MESSAGE |
throw.hpp | Contains FCPPT_ASSERT_THROW |
throw_message.hpp | Contains FCPPT_ASSERT_THROW_MESSAGE |
unimplemented_message.hpp | Contains FCPPT_ASSERT_UNIMPLEMENTED_MESSAGE |
unreachable.hpp | Contains FCPPT_ASSERT_UNREACHABLE |
unreachable_message.hpp | Contains FCPPT_ASSERT_UNREACHABLE_MESSAGE |
Classes | |
class | fcppt::assert_::exception |
An exception class that can be used with throwing assertions. More... | |
class | fcppt::assert_::information |
Represents information gathered at the assertion side. More... | |
Macros | |
#define | FCPPT_ASSERT_BASIC_CONDITIONAL(condition, action) |
Asserts that a condition is true. More... | |
#define | FCPPT_ASSERT_BASIC_CONDITIONAL_MESSAGE(condition, message, action) |
Asserts that a condition is true, with an extra message on failure. More... | |
#define | FCPPT_ASSERT_BASIC_DEFAULT_MESSAGE FCPPT_TEXT("") |
The default assert message. More... | |
#define | FCPPT_ASSERT_BASIC_GATHER_INFORMATION(condition_arg, message_arg) |
Gathers fcppt::assert_::information at the current file and function. More... | |
#define | FCPPT_ASSERT_BASIC_MESSAGE_AND_ACTION(macro, message, reason, action) |
Executes a macro with an action and printing of a message. More... | |
#define | FCPPT_ASSERT_BASIC_PRINT_MESSAGE(condition_arg, message_arg) |
Prints an assert message to cerr, containing fcppt::assert_::information. More... | |
#define | FCPPT_ASSERT_BASIC_TERMINATE_CONDITIONAL(condition) |
Calls terminate on a failed assertion. More... | |
#define | FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE(reason, message) |
Prints a message and terminates the program. More... | |
#define | FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE_CONDITIONAL(condition, message) |
Calls terminate on a failed assertion, with an extra message on failure. More... | |
#define | FCPPT_ASSERT_BASIC_UNCONDITIONAL(action) action \ |
Takes an unconditional action. More... | |
#define | FCPPT_ASSERT_BASIC_UNCONDITIONAL_MESSAGE(reason, message, action) |
Takes an unconditional action, also printing a message. More... | |
#define | FCPPT_ASSERT_ERROR(condition) |
Asserts a condition in the middle of a function. More... | |
#define | FCPPT_ASSERT_ERROR_MESSAGE(condition, message) |
Asserts a condition in the middle of a function, with an extra message on failure. More... | |
#define | FCPPT_ASSERT_OPTIONAL_ERROR(opt) |
Asserts that an optional is not nothing or returns its contents. More... | |
#define | FCPPT_ASSERT_POST(condition, exception) |
Asserts a post condition of a function. More... | |
#define | FCPPT_ASSERT_POST_MESSAGE(condition, message, exception) |
Asserts a post condition of a function, with an extra message on failure. More... | |
#define | FCPPT_ASSERT_PRE(condition) |
Asserts a pre condition of a function. More... | |
#define | FCPPT_ASSERT_PRE_MESSAGE(condition, message) |
Asserts a pre condition of a function, with an extra message on failure. More... | |
#define | FCPPT_ASSERT_THROW(condition, exception) |
Throws an exception on a failed assertion. More... | |
#define | FCPPT_ASSERT_THROW_MESSAGE(condition, exception, message) |
Throws an exception on a failed assertion, with an extra message on failure. More... | |
#define | FCPPT_ASSERT_UNIMPLEMENTED_MESSAGE(message) |
Terminates the program, also printing a message. More... | |
#define | FCPPT_ASSERT_UNREACHABLE |
Terminates the program. More... | |
#define | FCPPT_ASSERT_UNREACHABLE_MESSAGE(message) |
Terminates the program, also printing a message. More... | |
Functions | |
fcppt::string | fcppt::assert_::make_message (fcppt::assert_::information const &_info) |
Generates a message string from assert information. More... | |
#define FCPPT_ASSERT_BASIC_CONDITIONAL | ( | condition, | |
action | |||
) |
Asserts that a condition is true.
Asserts that condition is true, taking action if it is not.
condition | The condition to check for |
action | The action to take on failure |
#define FCPPT_ASSERT_BASIC_CONDITIONAL_MESSAGE | ( | condition, | |
message, | |||
action | |||
) |
Asserts that a condition is true, with an extra message on failure.
Asserts that condition is true, taking action if it is not and also printing message.
condition | The condition to check for |
message | The message to print on failure |
action | The action to take on failure |
#define FCPPT_ASSERT_BASIC_DEFAULT_MESSAGE FCPPT_TEXT("") |
The default assert message.
The default assert message, which is empty.
#define FCPPT_ASSERT_BASIC_GATHER_INFORMATION | ( | condition_arg, | |
message_arg | |||
) |
Gathers fcppt::assert_::information at the current file and function.
This macro expands to an fcppt::assert_::information, which gathers the current source file, the line of the file, the function name, the failed condition obtained from condition_arg, and the message obtained from message_arg.
condition_arg | The condition of the assertion |
message_arg | The message of the assertion |
#define FCPPT_ASSERT_BASIC_MESSAGE_AND_ACTION | ( | macro, | |
message, | |||
reason, | |||
action | |||
) |
Executes a macro with an action and printing of a message.
Executes macro, passing it an action that consists of printing a message with reason and message and executing action afterwards.
macro | The macro to invoke with the new action |
message | The message to print |
reason | The reason for the assertion |
action | The action to execute after printing the message |
#define FCPPT_ASSERT_BASIC_PRINT_MESSAGE | ( | condition_arg, | |
message_arg | |||
) |
Prints an assert message to cerr, containing fcppt::assert_::information.
Prints an assert message to cerr
, consisting of information gathered at the current code position, like file, line and function name, and also the failed condition condition_arg and message_arg.
#define FCPPT_ASSERT_BASIC_TERMINATE_CONDITIONAL | ( | condition | ) |
Calls terminate on a failed assertion.
Calls terminate if condition is false.
condition | The condition to check for |
#define FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE | ( | reason, | |
message | |||
) |
Prints a message and terminates the program.
Prints message and reason, and then calls std::terminate
.
reason | The reason for the assertion to fail |
message | The message to print |
#define FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE_CONDITIONAL | ( | condition, | |
message | |||
) |
Calls terminate on a failed assertion, with an extra message on failure.
Calls terminate if condition is false and also prints message.
condition | The condition to check for |
message | The message to print on failure |
#define FCPPT_ASSERT_BASIC_UNCONDITIONAL | ( | action | ) | action \ |
Takes an unconditional action.
Takes the unconditional action action.
action | The action to take |
#define FCPPT_ASSERT_BASIC_UNCONDITIONAL_MESSAGE | ( | reason, | |
message, | |||
action | |||
) |
Takes an unconditional action, also printing a message.
Takes the unconditional action action, also printing a message with reason and message.
reason | The reason for the assertion to fail |
message | The message to print |
action | The action to take |
#define FCPPT_ASSERT_ERROR | ( | condition | ) |
Asserts a condition in the middle of a function.
Asserts that condition is true, calling std::terminate
if it is not. This macro should be used if an error occurs in the middle of a function that should not happen.
condition | The condition to check for |
#define FCPPT_ASSERT_ERROR_MESSAGE | ( | condition, | |
message | |||
) |
Asserts a condition in the middle of a function, with an extra message on failure.
Asserts that condition is true, calling std::terminate
if it is not and also printing message. This macro should be used if an error occurs in the middle of a function that should not happen.
condition | The condition to check for |
message | The message to print on failure |
#define FCPPT_ASSERT_OPTIONAL_ERROR | ( | opt | ) |
Asserts that an optional is not nothing or returns its contents.
If opt is nothing, std::terminate
is called. Otherwise, the result of the macro is opt.get_unsafe()
.
#define FCPPT_ASSERT_POST | ( | condition, | |
exception | |||
) |
Asserts a post condition of a function.
Asserts that condition is true, throw the exception exception if it is not. The exception must have a constructor that takes an fcppt::assert_::information. This macro should be used if an error occurs at the end of a function, which is a result of failed function excecution, although all pre conditions were true.
condition | The condition to check for |
exception | The exception to throw if the condition is false |
#define FCPPT_ASSERT_POST_MESSAGE | ( | condition, | |
message, | |||
exception | |||
) |
Asserts a post condition of a function, with an extra message on failure.
Asserts that condition is true, throw the exception exception if it is not and also printing message. The exception must have a constructor that takes an fcppt::assert_::information. This macro should be used if an error occurs at the end of a function, which is a result of failed function excecution, although all pre conditions were true.
condition | The condition to check for |
message | The message to print on failure |
exception | The exception to throw on failure |
#define FCPPT_ASSERT_PRE | ( | condition | ) |
Asserts a pre condition of a function.
Asserts that condition is true, calling std::terminate
if it is not. This macro should be used to check for a function's preconditions.
condition | The condition to check for |
#define FCPPT_ASSERT_PRE_MESSAGE | ( | condition, | |
message | |||
) |
Asserts a pre condition of a function, with an extra message on failure.
Asserts that condition is true, calling std::terminate
if it is not and also printing message. This macro should be used to check for a function's preconditions.
condition | The condition to check for |
message | The message to print on failure |
#define FCPPT_ASSERT_THROW | ( | condition, | |
exception | |||
) |
Throws an exception on a failed assertion.
Throw exception if condition is false. The exception must have a constructor that takes an fcppt::assert_::information.
condition | The condition to check for |
exception | The exception to throw on failure |
#define FCPPT_ASSERT_THROW_MESSAGE | ( | condition, | |
exception, | |||
message | |||
) |
Throws an exception on a failed assertion, with an extra message on failure.
Throw exception if condition is false and also prints message. The exception must have a constructor that takes an fcppt::assert_::information.
condition | The condition to check for |
exception | The exception to throw on failure |
message | The message to print on failure |
#define FCPPT_ASSERT_UNIMPLEMENTED_MESSAGE | ( | message | ) |
Terminates the program, also printing a message.
Terminates the program, printing message. This assertion should be used when an unimplemented feature is reached.
message | The message to print |
#define FCPPT_ASSERT_UNREACHABLE |
Terminates the program.
This macro should be used when an unreachable code part is executed.
#define FCPPT_ASSERT_UNREACHABLE_MESSAGE | ( | message | ) |
Terminates the program, also printing a message.
Prints message and terminates the program. This macro should be used when an unreachable code part is executed.
message | The message to print |
|
inline |
Generates a message string from assert information.
Generates a message string from the assert information contained in _info.
_info | The assert information |