fcppt.assert

Description

Macros and functions for assertions.

Introduction Assertion categories Assertion messages Header files

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:

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

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
        FCPPT_ASSERT_PRE(
                _parameter < 10
        );

        bool const some_value(
                other_function()
        );

        // Assert a postcondition with a message
        FCPPT_ASSERT_POST_MESSAGE(
                some_value,
                fcppt::assert_::exception,
                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
        FCPPT_ASSERT_UNREACHABLE;
}

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(
                fcppt::assert_::information const &_info
        )
        :
                info_(
                        _info
                )
        {
        }

        fcppt::assert_::information const &
        info() const
        {
                return info_;
        }
private:
        fcppt::assert_::information info_;
};

void
throwing_function()
{
        // Throw an object of my_exception if other_function returns false
        FCPPT_ASSERT_THROW(
                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.
        fcppt::io::cerr()
                <<
                fcppt::assert_::make_message(
                        _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

condition	The condition to check for
action	The 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

condition	The condition to check for
message	The message to print on failure
action	The 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:

fcppt::assert_::information(\
        fcppt::assert_::file(\
                FCPPT_PP_FILE\
        ),\
        fcppt::assert_::line(\
                __LINE__\
        ),\
        fcppt::assert_::function(\
                FCPPT_PP_FUNCTION\
        ),\
        fcppt::assert_::condition(\
                FCPPT_PP_STRINGIZE(\
                        condition_arg\
                )\
        ),\
        fcppt::assert_::message(\
                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.

Parameters

condition_arg	The condition of the assertion
message_arg	The message of the assertion

FCPPT_ASSERT_BASIC_MESSAGE_AND_ACTION

#define FCPPT_ASSERT_BASIC_MESSAGE_AND_ACTION	(		macro,
			message,
			reason,
			action
	)

Value:

macro(\
        (\
                FCPPT_ASSERT_BASIC_PRINT_MESSAGE(\
                        reason,\
                        message\
                ),\
                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.

Parameters

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

FCPPT_ASSERT_BASIC_PRINT_MESSAGE

#define FCPPT_ASSERT_BASIC_PRINT_MESSAGE	(		condition_arg,
			message_arg
	)

Value:

fcppt::cast::to_void(\
        fcppt::io::cerr() \
                << \
                fcppt::assert_::make_message(\
                        FCPPT_ASSERT_BASIC_GATHER_INFORMATION(\
                                condition_arg,\
                                message_arg\
                        ) \
                ) \
                << FCPPT_TEXT('\n') \
)

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:

FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE_CONDITIONAL(\
        condition,\
        FCPPT_ASSERT_BASIC_DEFAULT_MESSAGE\
)

Calls terminate on a failed assertion.

Calls terminate if condition is false.

Parameters

condition

The condition to check for

FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE

#define FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE	(		reason,
			message
	)

Value:

FCPPT_ASSERT_BASIC_UNCONDITIONAL_MESSAGE(\
        reason,\
        message,\
        std::terminate()\
)

Prints a message and terminates the program.

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

Parameters

reason	The reason for the assertion to fail
message	The message to print

FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE_CONDITIONAL

#define FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE_CONDITIONAL	(		condition,
			message
	)

Value:

FCPPT_ASSERT_BASIC_CONDITIONAL_MESSAGE(\
        condition,\
        message,\
        std::terminate()\
)

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

Calls terminate if condition is false and also prints message.

Parameters

condition	The condition to check for
message	The 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

action

The action to take

FCPPT_ASSERT_BASIC_UNCONDITIONAL_MESSAGE

#define FCPPT_ASSERT_BASIC_UNCONDITIONAL_MESSAGE	(		reason,
			message,
			action
	)

Value:

FCPPT_ASSERT_BASIC_MESSAGE_AND_ACTION(\
        FCPPT_ASSERT_BASIC_UNCONDITIONAL,\
        message,\
        reason,\
        action \
)

Takes an unconditional action, also printing a message.

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

Parameters

reason	The reason for the assertion to fail
message	The message to print
action	The action to take

FCPPT_ASSERT_ERROR

#define FCPPT_ASSERT_ERROR

(

condition

)

Value:

FCPPT_ASSERT_BASIC_TERMINATE_CONDITIONAL(\
        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.

Parameters

condition

The condition to check for

FCPPT_ASSERT_ERROR_MESSAGE

#define FCPPT_ASSERT_ERROR_MESSAGE	(		condition,
			message
	)

Value:

FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE_CONDITIONAL(\
        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.

Parameters

condition	The condition to check for
message	The 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:

FCPPT_ASSERT_POST_MESSAGE(\
        condition,\
        exception, \
        FCPPT_ASSERT_BASIC_DEFAULT_MESSAGE \
)

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

condition	The condition to check for
exception	The exception to throw if the condition is false

FCPPT_ASSERT_POST_MESSAGE

#define FCPPT_ASSERT_POST_MESSAGE	(		condition,
			message,
			exception
	)

Value:

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

Parameters

condition	The condition to check for
message	The message to print on failure
exception	The exception to throw on failure

FCPPT_ASSERT_PRE

#define FCPPT_ASSERT_PRE

(

condition

)

Value:

FCPPT_ASSERT_BASIC_TERMINATE_CONDITIONAL(\
        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.

Parameters

condition

The condition to check for

FCPPT_ASSERT_PRE_MESSAGE

#define FCPPT_ASSERT_PRE_MESSAGE	(		condition,
			message
	)

Value:

FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE_CONDITIONAL(\
        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.

Parameters

condition	The condition to check for
message	The message to print on failure

FCPPT_ASSERT_THROW

#define FCPPT_ASSERT_THROW	(		condition,
			exception
	)

Value:

FCPPT_ASSERT_THROW_MESSAGE(\
        condition,\
        exception,\
        FCPPT_ASSERT_BASIC_DEFAULT_MESSAGE\
)

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

condition	The condition to check for
exception	The exception to throw on failure

FCPPT_ASSERT_THROW_MESSAGE

#define FCPPT_ASSERT_THROW_MESSAGE	(		condition,
			exception,
			message
	)

Value:

FCPPT_ASSERT_BASIC_CONDITIONAL(\
        condition,\
        throw exception(\
                FCPPT_ASSERT_BASIC_GATHER_INFORMATION(\
                        condition,\
                        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.

Parameters

condition	The condition to check for
exception	The exception to throw on failure
message	The message to print on failure

FCPPT_ASSERT_UNIMPLEMENTED_MESSAGE

#define FCPPT_ASSERT_UNIMPLEMENTED_MESSAGE

(

message

)

Value:

FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE(\
        unimplemented,\
        message\
)

Terminates the program, also printing a message.

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

Parameters

message

The message to print

FCPPT_ASSERT_UNREACHABLE

#define FCPPT_ASSERT_UNREACHABLE

Value:

FCPPT_ASSERT_UNREACHABLE_MESSAGE(\
        FCPPT_ASSERT_BASIC_DEFAULT_MESSAGE \
)

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:

FCPPT_ASSERT_BASIC_TERMINATE_MESSAGE(\
        unreachable code,\
        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.

Parameters

message

The 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

_info

The assert information

Returns

The formatted message