3.0.0
Freundlich's C++ toolkit
Classes | Macros | Functions
fcppt.assert

Description

Macros and functions for assertions.

Introduction

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:

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.

A failed function call that is to be expected under certain conditions.

In this case, a function should definitely report this as a return value, probably using something like fcppt::optional.

A failed function call that is not expected under normal conditions.

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.

A failed function call because the parameters are wrong.

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.

Other conditions that are impossible in the absence of errors.

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.

Assertion categories

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.

FCPPT_ASSERT_PRE and FCPPT_ASSERT_PRE_MESSAGE

These should be used to check pre conditions for a function and they will terminate the program if they are violated.

FCPPT_ASSERT_POST and FCPPT_ASSERT_POST_MESSAGE

These should be used to check for post conditions of functions. They will throw an exception on failure.

FCPPT_ASSERT_ERROR and FCPPT_ASSERT_ERROR_MESSAGE

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.

FCPPT_ASSERT_THROW and FCPPT_ASSERT_THROW_MESSAGE

These can generally be used as a replacement for throwing exceptions.

FCPPT_ASSERT_UNIMPLEMENTED_MESSAGE

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.

FCPPT_ASSERT_UNREACHABLE and FCPPT_ASSERT_UNREACHABLE_MESSAGE

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:

void
library_function(
int const _parameter
)
{
// Assert a precondition without a message
_parameter < 10
);
bool const some_value(
other_function()
);
// Assert a postcondition with a message
some_value,
FCPPT_TEXT("other_function failed")
);
}

The usual case where every enumerator is handled in a switch can be tested as follows:

enum class food
{
apple,
banana,
potato,
bread
};
// Check if a given kind of food is a fruit
bool
is_fruit(
food const _value
)
{
// Handle every possible enumerator
switch(
_value
)
{
case food::apple:
case food::banana:
return true;
case food::potato:
case food::bread:
return false;
}
// This should never be reached
}

Assertion messages

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.

// Define an exception that can be constructed from an
// fcppt::assert_::information
class my_exception
{
public:
explicit
my_exception(
)
:
info_(
_info
)
{
}
info() const
{
return info_;
}
private:
};
void
throwing_function()
{
// Throw an object of my_exception if other_function returns false
other_function(),
my_exception
);
}
void
test_function()
try
{
throwing_function();
}
catch(
my_exception const &_exception
)
{
// fcppt::assert_::make_message can be used to turn an
// fcppt::assert_::information into a string.
<<
_exception.info()
)
<< FCPPT_TEXT('\n');
}

Header files

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...
 

Macro Definition Documentation

◆ FCPPT_ASSERT_BASIC_CONDITIONAL

#define FCPPT_ASSERT_BASIC_CONDITIONAL (   condition,
  action 
)
Value:
if( \
!(condition)\
)\
FCPPT_ASSERT_BASIC_UNCONDITIONAL(\
action \
)

Asserts that a condition is true.

Asserts that condition is true, taking action if it is not.

Parameters
conditionThe condition to check for
actionThe action to take on failure

◆ FCPPT_ASSERT_BASIC_CONDITIONAL_MESSAGE

#define FCPPT_ASSERT_BASIC_CONDITIONAL_MESSAGE (   condition,
  message,
  action 
)
Value:
if( \
!(condition)\
)\
FCPPT_ASSERT_BASIC_UNCONDITIONAL_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.

Parameters
conditionThe condition to check for
messageThe message to print on failure
actionThe action to take on failure

◆ FCPPT_ASSERT_BASIC_DEFAULT_MESSAGE

#define FCPPT_ASSERT_BASIC_DEFAULT_MESSAGE   FCPPT_TEXT("")

The default assert message.

The default assert message, which is empty.

◆ FCPPT_ASSERT_BASIC_GATHER_INFORMATION

#define FCPPT_ASSERT_BASIC_GATHER_INFORMATION (   condition_arg,
  message_arg 
)
Value:
),\
__LINE__\
),\
),\
condition_arg\
)\
),\
message_arg\
) \
)
Represents information gathered at the assertion side.
Definition: information.hpp:31
#define FCPPT_PP_FILE
Prints the current file name.
Definition: file.hpp:20
#define FCPPT_PP_FUNCTION
Pretty prints the current function name.
Definition: function.hpp:25
#define FCPPT_PP_STRINGIZE(string)
Creates a string from its macro argument.
Definition: stringize.hpp:21

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.

Parameters
condition_argThe condition of the assertion
message_argThe message of the assertion

◆ FCPPT_ASSERT_BASIC_MESSAGE_AND_ACTION

#define FCPPT_ASSERT_BASIC_MESSAGE_AND_ACTION (   macro,
  message,
  reason,
  action 
)
Value:
macro(\
(\
reason,\
message\
),\
action \
)\
)
#define FCPPT_ASSERT_BASIC_PRINT_MESSAGE(condition_arg, message_arg)
Prints an assert message to cerr, containing fcppt::assert_::information.
Definition: print_message.hpp:26

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.

Parameters
macroThe macro to invoke with the new action
messageThe message to print
reasonThe reason for the assertion
actionThe action to execute after printing the message

◆ FCPPT_ASSERT_BASIC_PRINT_MESSAGE

#define FCPPT_ASSERT_BASIC_PRINT_MESSAGE (   condition_arg,
  message_arg 
)
Value:
<< \
condition_arg,\
message_arg\
) \
) \
<< FCPPT_TEXT('\n') \
)
fcppt::string make_message(fcppt::assert_::information const &_info)
Generates a message string from assert information.
Definition: make_message.hpp:34
void to_void(Type const &_value) noexcept
Casts an expression to void.
Definition: to_void.hpp:34
#define FCPPT_ASSERT_BASIC_GATHER_INFORMATION(condition_arg, message_arg)
Gathers fcppt::assert_::information at the current file and function.
Definition: gather_information.hpp:34
FCPPT_DETAIL_SYMBOL fcppt::io::ostream & cerr()
Returns either std::cerr or std::wcerr, depending on fcppt::char_type.
#define FCPPT_TEXT(x)
A macro to wrap a narrow character literal so it results in a fcppt::char_type[] array.See the string module description for more information.
Definition: text.hpp:19

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.

◆ FCPPT_ASSERT_BASIC_TERMINATE_CONDITIONAL

#define FCPPT_ASSERT_BASIC_TERMINATE_CONDITIONAL (   condition)
Value:
condition,\
)
#define FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE_CONDITIONAL(condition, message)
Calls terminate on a failed assertion, with an extra message on failure.
Definition: terminate_message_conditional.hpp:27
#define FCPPT_ASSERT_BASIC_DEFAULT_MESSAGE
The default assert message.
Definition: default_message.hpp:20

Calls terminate on a failed assertion.

Calls terminate if condition is false.

Parameters
conditionThe condition to check for

◆ FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE

#define FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE (   reason,
  message 
)
Value:
reason,\
message,\
std::terminate()\
)
#define FCPPT_ASSERT_BASIC_UNCONDITIONAL_MESSAGE(reason, message, action)
Takes an unconditional action, also printing a message.
Definition: unconditional_message.hpp:28

Prints a message and terminates the program.

Prints message and reason, and then calls std::terminate.

Parameters
reasonThe reason for the assertion to fail
messageThe message to print

◆ FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE_CONDITIONAL

#define FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE_CONDITIONAL (   condition,
  message 
)
Value:
condition,\
message,\
std::terminate()\
)
#define FCPPT_ASSERT_BASIC_CONDITIONAL_MESSAGE(condition, message, action)
Asserts that a condition is true, with an extra message on failure.
Definition: conditional_message.hpp:27

Calls terminate on a failed assertion, with an extra message on failure.

Calls terminate if condition is false and also prints message.

Parameters
conditionThe condition to check for
messageThe message to print on failure

◆ FCPPT_ASSERT_BASIC_UNCONDITIONAL

#define FCPPT_ASSERT_BASIC_UNCONDITIONAL (   action)    action \

Takes an unconditional action.

Takes the unconditional action action.

Parameters
actionThe action to take

◆ FCPPT_ASSERT_BASIC_UNCONDITIONAL_MESSAGE

#define FCPPT_ASSERT_BASIC_UNCONDITIONAL_MESSAGE (   reason,
  message,
  action 
)
Value:
message,\
reason,\
action \
)
#define FCPPT_ASSERT_BASIC_UNCONDITIONAL(action)
Takes an unconditional action.
Definition: unconditional.hpp:20
#define FCPPT_ASSERT_BASIC_MESSAGE_AND_ACTION(macro, message, reason, action)
Executes a macro with an action and printing of a message.
Definition: message_and_action.hpp:29

Takes an unconditional action, also printing a message.

Takes the unconditional action action, also printing a message with reason and message.

Parameters
reasonThe reason for the assertion to fail
messageThe message to print
actionThe action to take

◆ FCPPT_ASSERT_ERROR

#define FCPPT_ASSERT_ERROR (   condition)
Value:
condition\
)
#define FCPPT_ASSERT_BASIC_TERMINATE_CONDITIONAL(condition)
Calls terminate on a failed assertion.
Definition: terminate_conditional.hpp:23

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.

Parameters
conditionThe condition to check for

◆ FCPPT_ASSERT_ERROR_MESSAGE

#define FCPPT_ASSERT_ERROR_MESSAGE (   condition,
  message 
)
Value:
condition,\
message\
)
#define FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE_CONDITIONAL(condition, message)
Calls terminate on a failed assertion, with an extra message on failure.
Definition: terminate_message_conditional.hpp:27

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.

Parameters
conditionThe condition to check for
messageThe message to print on failure

◆ FCPPT_ASSERT_OPTIONAL_ERROR

#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().

◆ FCPPT_ASSERT_POST

#define FCPPT_ASSERT_POST (   condition,
  exception 
)
Value:
condition,\
exception, \
)
#define FCPPT_ASSERT_POST_MESSAGE(condition, message, exception)
Asserts a post condition of a function, with an extra message on failure.
Definition: post_message.hpp:30
#define FCPPT_ASSERT_BASIC_DEFAULT_MESSAGE
The default assert message.
Definition: default_message.hpp:20

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.

Parameters
conditionThe condition to check for
exceptionThe exception to throw if the condition is false

◆ FCPPT_ASSERT_POST_MESSAGE

#define FCPPT_ASSERT_POST_MESSAGE (   condition,
  message,
  exception 
)
Value:
condition,\
message, \
exception \
)
#define FCPPT_ASSERT_THROW_MESSAGE(condition, exception, message)
Throws an exception on a failed assertion, with an extra message on failure.
Definition: throw_message.hpp:29

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.

Parameters
conditionThe condition to check for
messageThe message to print on failure
exceptionThe exception to throw on failure

◆ FCPPT_ASSERT_PRE

#define FCPPT_ASSERT_PRE (   condition)
Value:
condition\
)
#define FCPPT_ASSERT_BASIC_TERMINATE_CONDITIONAL(condition)
Calls terminate on a failed assertion.
Definition: terminate_conditional.hpp:23

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.

Parameters
conditionThe condition to check for

◆ FCPPT_ASSERT_PRE_MESSAGE

#define FCPPT_ASSERT_PRE_MESSAGE (   condition,
  message 
)
Value:
condition,\
message\
)
#define FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE_CONDITIONAL(condition, message)
Calls terminate on a failed assertion, with an extra message on failure.
Definition: terminate_message_conditional.hpp:27

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.

Parameters
conditionThe condition to check for
messageThe message to print on failure

◆ FCPPT_ASSERT_THROW

#define FCPPT_ASSERT_THROW (   condition,
  exception 
)
Value:
condition,\
exception,\
)
#define FCPPT_ASSERT_BASIC_DEFAULT_MESSAGE
The default assert message.
Definition: default_message.hpp:20
#define FCPPT_ASSERT_THROW_MESSAGE(condition, exception, message)
Throws an exception on a failed assertion, with an extra message on failure.
Definition: throw_message.hpp:29

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.

Parameters
conditionThe condition to check for
exceptionThe exception to throw on failure

◆ FCPPT_ASSERT_THROW_MESSAGE

#define FCPPT_ASSERT_THROW_MESSAGE (   condition,
  exception,
  message 
)
Value:
condition,\
throw exception(\
condition,\
message\
)\
) \
)
#define FCPPT_ASSERT_BASIC_CONDITIONAL(condition, action)
Asserts that a condition is true.
Definition: conditional.hpp:24
#define FCPPT_ASSERT_BASIC_GATHER_INFORMATION(condition_arg, message_arg)
Gathers fcppt::assert_::information at the current file and function.
Definition: gather_information.hpp:34

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.

Parameters
conditionThe condition to check for
exceptionThe exception to throw on failure
messageThe message to print on failure

◆ FCPPT_ASSERT_UNIMPLEMENTED_MESSAGE

#define FCPPT_ASSERT_UNIMPLEMENTED_MESSAGE (   message)
Value:
unimplemented,\
message\
)
#define FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE(reason, message)
Prints a message and terminates the program.
Definition: terminate_message.hpp:27

Terminates the program, also printing a message.

Terminates the program, printing message. This assertion should be used when an unimplemented feature is reached.

Parameters
messageThe message to print

◆ FCPPT_ASSERT_UNREACHABLE

#define FCPPT_ASSERT_UNREACHABLE
Value:
)
#define FCPPT_ASSERT_UNREACHABLE_MESSAGE(message)
Terminates the program, also printing a message.
Definition: unreachable_message.hpp:23
#define FCPPT_ASSERT_BASIC_DEFAULT_MESSAGE
The default assert message.
Definition: default_message.hpp:20

Terminates the program.

This macro should be used when an unreachable code part is executed.

◆ FCPPT_ASSERT_UNREACHABLE_MESSAGE

#define FCPPT_ASSERT_UNREACHABLE_MESSAGE (   message)
Value:
unreachable code,\
message\
)
#define FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE(reason, message)
Prints a message and terminates the program.
Definition: terminate_message.hpp:27

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.

Parameters
messageThe message to print

Function Documentation

◆ make_message()

fcppt::string fcppt::assert_::make_message ( fcppt::assert_::information const &  _info)
inline

Generates a message string from assert information.

Generates a message string from the assert information contained in _info.

Parameters
_infoThe assert information
Returns
The formatted message