Assert and errors

Assertions and exceptions. More...

Namespaces
namespace	lagrange
	Main namespace for Lagrange.

Classes
struct	Error
	Base exception for errors thrown by Lagrange functions. More...
struct	BadCastError
	An exception of this type is thrown when a lagrange::safe_cast<> fails. More...
struct	ParsingError
	An exception of this type is thrown when a parsing error occurs. More...

Macros
#define	la_runtime_assert(...)
	Runtime assertion check.
#define	la_debug_assert(...)
	Debug assertion check.

Functions
LA_CORE_API void	set_breakpoint_enabled (bool enabled)
	Sets whether to trigger a debugger breakpoint on assert failure.
LA_CORE_API bool	is_breakpoint_enabled ()
	Returns whether to trigger a debugger breakpoint on assert failure.
LA_CORE_API void	trigger_breakpoint ()
	Call to explicitly trigger a debugger breakpoint.
LA_CORE_API bool	assertion_failed (const char *function, const char *file, unsigned int line, const char *condition, std::string_view message)

Detailed Description

Assertions and exceptions.

A failed assertion will throw an exception lagrange::Error with a specific error message, and can be caught by client code. Lagrange code uses two types of assertions:

• Runtime assertions la_runtime_assert(). Those are used to check the validity of user inputs as a pre-condition to a function. For example, providing a function with an empty, or a mesh with incorrect dimension, could result in such an assertion being raised. A runtime assert is executed even in Release configuration, and indicates a problem with the function input.
• Debug assertions la_debug_assert(). Those are only checked in Debug code (macro NDEBUG is undefined). A debug assert is used to check internal code validity, and should not be triggered under any circumstance by client code. A failed debug assert indicates an error in the programmer's code, and should be fixed accordingly.

Note that assert macros behave as functions, meaning they expand to a void expression and can be used in an expression such as y = (la_debug_assert(true), x).

Finally, our assertion macros can take either 1 or 2 arguments, the second argument being an optional error message. To conveniently format assertion messages with a printf-like syntax, use fmt::format:

#include <lagrange/utils/assert.h>
#include <spdlog/fmt/fmt.h>
 
la_debug_assert(x == 3);
la_debug_assert(x == 3, "Error message");
la_debug_assert(x == 3, fmt::format("Incorrect value of x: {}", x));

Macro Definition Documentation

la_runtime_assert

#define la_runtime_assert

(

...

)

#include <lagrange/utils/assert.h>

Runtime assertion check.

This check is executed for both Debug and Release configurations, and should be used, e.g., to check the validity of user-given inputs.

Parameters

condition	Condition to check at runtime.
message	Optional message argument.

Returns

Void expression.

la_debug_assert

#define la_debug_assert

(

...

)

#include <lagrange/utils/assert.h>

Debug assertion check.

This check is executed only for Debug configurations, and should be used as a sanity check for situations that should never arise in the program's normal execution (e.g., a doubled linked list is malformed).

Parameters

condition	Condition to check at runtime.
message	Optional message argument.

Returns

Void expression.

Function Documentation

set_breakpoint_enabled()

void set_breakpoint_enabled

(

bool

enabled

)

#include <lagrange/utils/assert.h>

Sets whether to trigger a debugger breakpoint on assert failure.

Use this function in unit test, around lines that are supposed to throw, to avoid spurious breakpoints when running unit tests.

Parameters

[in]

enabled

True to enable breakpoint debugging, false to disable.

is_breakpoint_enabled()

bool is_breakpoint_enabled

(

)

#include <lagrange/utils/assert.h>

Returns whether to trigger a debugger breakpoint on assert failure.

Use this function in a unit test to restore previous behavior when explicitly disabling triggering debugger breakpoint.

Returns

True if assert failure triggers a debugger breakpoint, False otherwise.

assertion_failed()

LA_IGNORE_NONVOID_NORETURN_WARNING_BEGIN bool assertion_failed	(	const char *	function,
		const char *	file,
		unsigned int	line,
		const char *	condition,
		std::string_view	message )

#include <lagrange/utils/assert.h>

Called in case of an assertion failure.

@param[in]  function   Function in which the assertion failed.
@param[in]  file       File in which the assertion failed.
@param[in]  line       Line where the assertion failed.
@param[in]  condition  Assert condition that failed.
@param[in]  message    Optional error message associated with the assertion.

@return     Boolean type returned by this function. While this function never returns, the
            return boolean type allows it to be called in an expression such as `foo &&

/ assertion_failed(...)`