An in-my-humble-opinion better version of the assert concept. More...

Macros
#define	ASSUMING_DEBUG
	You can define this macro to either 0 or 1 to disable or enable checking of assumptions.
#define	ASSUMING_INCLUDE_MAGIC_ENUM
	You can define this macro to either 1 or 0 to include <magic_enum.hpp> or not, if you want prettier printing of enum names.
#define	ASSUMING_BREAKPOINT
	You can define this macro project-wide (or before including this header) if you want to specify the behavior of the Break option that can be requested by the assumption failure handler.
#define	ASSUMING_USE_STACKTRACE
	You can define this macro to 1 or 0 to include <stacktrace> (if available) or not; if this functionality is available, an std::stacktrace will be given to the assumption failure handler.
#define	Assuming(exp, ...)
	The basic Assuming macro. Assumes the term is true. Expression result must be convertible to bool.
#define	AssumingNotReachable(...)
	Assumes the point in code is not reachable.
#define	AssumingNotRecursive(...)
	Assumes the point in code is not reached via a recursive function call.
#define	AssumingSingleThread(...)
	Assumes the point in code executes in exactly one thread, the same thread over the lifetime of the program.
#define	AssumingOnThread(thread_to_check, ...)
	Assumes the point in code executes on the specified thread.
#define	AssumingNotOnThread(thread_to_check, ...)
	Assumes the point in code DOES NOT execute on the specified thread.
#define	AssumingNull(exp, ...)
	Assumes the term is not (convertible to) a null pointer.
#define	AssumingNotNull(exp, ...)
	Assumes the term is (convertible to) a null pointer.
#define	AssumingBinOp(a, b, op, text, ...)
	Assumes the two expressions a and b are true with regards to the relation op (describen in text). This is an internal macro used by others.
#define	AssumingEqual(a, b, ...)
	Assumes the two expressions evaluate equal.
#define	AssumingNotEqual(a, b, ...)
	Assumes the two expressions do not evaluate equal.
#define	AssumingGreater(a, b, ...)
	Assumes the first term is greater than the second.
#define	AssumingLess(a, b, ...)
	Assumes the first term is less than the second.
#define	AssumingGreaterEqual(a, b, ...)
	Assumes the first term is greater than or equal to the second.
#define	AssumingLessEqual(a, b, ...)
	Assumes the first term is less than or equal to the second.
#define	AssumingContainsBits(a, b, ...)
	Assumes the first term contains the bits in the second term.
#define	AssumingZero(a, ...)
	Assumes the term evaluates to 0.
#define	AssumingEmpty(exp, ...)
	Assumes the term evaluates to an empty container (tested via empty(container)).
#define	AssumingNotEmpty(exp, ...)
	Assumes the term evaluates to an non-empty container (tested via empty(container)).
#define	AssumingNullOrEmpty(exp, ...)
	Assumes the term evaluates to either a null value or an empty string.
#define	AssumingNotNullOrEmpty(exp, ...)
	Assumes the term does not evaluate to neither a null value nor an empty string.
#define	AssumingValidIndex(_index, _container, ...)
	Assumes the _index term evaluates to a valid index to the _container term. This is checked via size(_container).
#define	AssumingContains(_key, _container, ...)
	Assumes the _key term evaluates to a valid index to the _container term. This is checked via .contains().
#define	AssumingValidIterator(_iterator, _container, ...)
	Assumes the _index term evaluates to a valid iterator to the _container term. This is checked via end(_container).
#define	AssumingBetween(v, a, b, ...)
	Assumes the v term evaluates to a value between a and b exclusive.
#define	AssumingBetweenInclusive(v, a, b, ...)
	Assumes the v term evaluates to a value between a and b inclusive.

Variables
auto(*	ghassanpl::AssumptionFailureHandler )(std::string_view expectation, std::initializer_list< std::pair< std::string_view, std::string > > values, std::string data, source_location loc) -> AssumptionHandlerResult=nullptr
	This variable should be set to a handler function by your own code, as it is called by an assumption macro with a failing assumption; if you do not provide it, an exception with an unspecified type will be thrown.

Detailed Description

An in-my-humble-opinion better version of the assert concept.

Copyright: This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.

Pros:

The macro names "Assuming*" suggest that in the following code we are assuming the predicate given to the macro.
The predicate and its parameters are always evaluated exactly once.
A custom, user-provided "assumption failure" function is called on assumption failure.
You can provide additional descriptions and arguments to the assumption failure function, for better debugging.
Includes variants like AssumingEqual(a, b, ...) that assumes arguments are equal; each such variant makes sure to evaluate and stringify the arguments, and give a helpful message, such as: "Assumption Failed: Assuming that a will equal b."
In non-debug compiles, the library instructs the compiler to actually ASSUME its predicate, so it can optimize the code better; keep in mind that the assumption failing is undefined behavior in non-debug compiles.
Better macros to control the behavior of this library.

Cons:

Depends on <format> and <source_location> headers.
Still macro-based (only for stringification of arguments, thankfully.)
Using compiler-specific code for enforcing assumptions.
Slightly non-idiomatic naming conventions as well as some tiny assumptions about the user code-base.

Macro Definition Documentation

◆ Assuming

#define Assuming	(		exp,
			... )

The basic Assuming macro. Assumes the term is true. Expression result must be convertible to bool.

Definition at line 147 of file assuming.h.

◆ ASSUMING_BREAKPOINT

#define ASSUMING_BREAKPOINT

You can define this macro project-wide (or before including this header) if you want to specify the behavior of the Break option that can be requested by the assumption failure handler.

If it's not defined, the default compiler breakpoint facility will be used; if no facility is available, a caught throw 0 can be detected by the compiler in "Break on all exceptions" mode while still being able to continue through the code.

Definition at line 71 of file assuming.h.

◆ ASSUMING_DEBUG

#define ASSUMING_DEBUG

You can define this macro to either 0 or 1 to disable or enable checking of assumptions.

If this macro is not defined, its value is based on the NDEBUG macro.

Definition at line 42 of file assuming.h.

◆ ASSUMING_INCLUDE_MAGIC_ENUM

#define ASSUMING_INCLUDE_MAGIC_ENUM

You can define this macro to either 1 or 0 to include <magic_enum.hpp> or not, if you want prettier printing of enum names.

If you don't define it, it will check for <magic_enum.hpp> and include it if it exists.

Definition at line 51 of file assuming.h.

◆ ASSUMING_USE_STACKTRACE

#define ASSUMING_USE_STACKTRACE

You can define this macro to 1 or 0 to include <stacktrace> (if available) or not; if this functionality is available, an std::stacktrace will be given to the assumption failure handler.

Definition at line 81 of file assuming.h.

◆ AssumingBetween

#define AssumingBetween	(	v,
		a,
		b,
		... )

Assumes the v term evaluates to a value between a and b exclusive.

Definition at line 259 of file assuming.h.

◆ AssumingBetweenInclusive

#define AssumingBetweenInclusive	(	v,
		a,
		b,
		... )

Assumes the v term evaluates to a value between a and b inclusive.

Definition at line 267 of file assuming.h.

◆ AssumingBinOp

#define AssumingBinOp	(	a,
		b,
		op,
		text,
		... )

Assumes the two expressions a and b are true with regards to the relation op (describen in text). This is an internal macro used by others.

Definition at line 193 of file assuming.h.

◆ AssumingContains

#define AssumingContains	(	_key,
		_container,
		... )

Assumes the _key term evaluates to a valid index to the _container term. This is checked via .contains().

Definition at line 247 of file assuming.h.

◆ AssumingContainsBits

#define AssumingContainsBits	(	a,
		b,
		... )

Assumes the first term contains the bits in the second term.

Definition at line 213 of file assuming.h.

◆ AssumingEmpty

#define AssumingEmpty	(		exp,
			... )

Assumes the term evaluates to an empty container (tested via empty(container)).

Definition at line 223 of file assuming.h.

◆ AssumingEqual

#define AssumingEqual	(	a,
		b,
		... )

Assumes the two expressions evaluate equal.

Definition at line 200 of file assuming.h.

◆ AssumingGreater

#define AssumingGreater	(	a,
		b,
		... )

Assumes the first term is greater than the second.

Definition at line 204 of file assuming.h.

◆ AssumingGreaterEqual

#define AssumingGreaterEqual	(	a,
		b,
		... )

Assumes the first term is greater than or equal to the second.

Definition at line 208 of file assuming.h.

◆ AssumingLess

#define AssumingLess	(	a,
		b,
		... )

Assumes the first term is less than the second.

Definition at line 206 of file assuming.h.

◆ AssumingLessEqual

#define AssumingLessEqual	(	a,
		b,
		... )

Assumes the first term is less than or equal to the second.

Definition at line 210 of file assuming.h.

◆ AssumingNotEmpty

#define AssumingNotEmpty	(		exp,
			... )

Assumes the term evaluates to an non-empty container (tested via empty(container)).

Definition at line 227 of file assuming.h.

◆ AssumingNotEqual

#define AssumingNotEqual	(	a,
		b,
		... )

Assumes the two expressions do not evaluate equal.

Definition at line 202 of file assuming.h.

◆ AssumingNotNull

#define AssumingNotNull	(		exp,
			... )

Assumes the term is (convertible to) a null pointer.

Definition at line 189 of file assuming.h.

◆ AssumingNotNullOrEmpty

#define AssumingNotNullOrEmpty	(		exp,
			... )

Assumes the term does not evaluate to neither a null value nor an empty string.

Definition at line 235 of file assuming.h.

◆ AssumingNotOnThread

#define AssumingNotOnThread	(		thread_to_check,
			... )

Assumes the point in code DOES NOT execute on the specified thread.

Definition at line 177 of file assuming.h.

◆ AssumingNotReachable

#define AssumingNotReachable ( ... )

Assumes the point in code is not reachable.

Definition at line 151 of file assuming.h.

◆ AssumingNotRecursive

#define AssumingNotRecursive ( ... )

Assumes the point in code is not reached via a recursive function call.

Definition at line 154 of file assuming.h.

◆ AssumingNull

#define AssumingNull	(		exp,
			... )

Assumes the term is not (convertible to) a null pointer.

Definition at line 185 of file assuming.h.

◆ AssumingNullOrEmpty

#define AssumingNullOrEmpty	(		exp,
			... )

Assumes the term evaluates to either a null value or an empty string.

Definition at line 231 of file assuming.h.

◆ AssumingOnThread

#define AssumingOnThread	(		thread_to_check,
			... )

Assumes the point in code executes on the specified thread.

Definition at line 169 of file assuming.h.

◆ AssumingSingleThread

#define AssumingSingleThread ( ... )

Assumes the point in code executes in exactly one thread, the same thread over the lifetime of the program.

Definition at line 161 of file assuming.h.

◆ AssumingValidIndex

#define AssumingValidIndex	(	_index,
		_container,
		... )

Assumes the _index term evaluates to a valid index to the _container term. This is checked via size(_container).

Definition at line 239 of file assuming.h.

◆ AssumingValidIterator

#define AssumingValidIterator	(	_iterator,
		_container,
		... )

Assumes the _index term evaluates to a valid iterator to the _container term. This is checked via end(_container).

Definition at line 254 of file assuming.h.

◆ AssumingZero

#define AssumingZero	(		a,
			... )

Assumes the term evaluates to 0.

Definition at line 220 of file assuming.h.

Variable Documentation

◆ AssumptionFailureHandler

auto(* ghassanpl::AssumptionFailureHandler) (std::string_view expectation, std::initializer_list< std::pair< std::string_view, std::string > > values, std::string data, source_location loc) -> AssumptionHandlerResult=nullptr	(	std::string_view	expectation,
		std::initializer_list< std::pair< std::string_view, std::string > >	values,
		std::string	data,
		source_location	loc ) -> AssumptionHandlerResult=nullptr

inline

This variable should be set to a handler function by your own code, as it is called by an assumption macro with a failing assumption; if you do not provide it, an exception with an unspecified type will be thrown.

Parameters

expectation	An explanation of which assumption failed
values	The values of the expressions the assumption macro checked
data	Any additional arguments you gave to the macro, std-formatted.
loc

Definition at line 408 of file assuming.h.

Macros

Variables