Assuming

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

Variables
void(*	ghassanpl::AssumptionFailureHandler )(std::string_view expectation, std::initializer_list< std::pair< std::string_view, std::string > > values, std::string data, source_location loc)
	This function must be provided by your own code, as it is called by an assumption macro with a failing assumption.
#define	ASSUMING_DEBUG
	You can define this macro project-wide to either 0 or 1 to disable or enable checking of assumptions.
#define	ASSUMING_INCLUDE_MAGIC_ENUM
	You can define this macro project-wide to either 1 or 0 to include <magic_enum.hpp> or not, if you want prettier printing of enum names.
#define	ASSUMING_ASSUME(cond)
#define	Assuming(exp, ...)
	The basic Assuming macro. Assumes the expression 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 expression is not (convertible to) a null pointer.
#define	AssumingNotNull(exp, ...)
	Assumes the expression 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 expression is greater than the second.
#define	AssumingLess(a, b, ...)
	Assumes the first expression is less than the second.
#define	AssumingGreaterEqual(a, b, ...)
	Assumes the first expression is greater than or equal to the second.
#define	AssumingLessEqual(a, b, ...)
	Assumes the first expression is less than or equal to the second.
#define	AssumingContainsBits(a, b, ...)
	Assumes the first expression contains the bits in the second expression.
#define	AssumingZero(a, ...)
	Assumes the expression evaluates to 0.
#define	AssumingEmpty(exp, ...)
	Assumes the expression evaluates to an empty container (tested via empty(container))
#define	AssumingNotEmpty(exp, ...)
	Assumes the expression evaluates to an non-empty container (tested via empty(container))
#define	AssumingNullOrEmpty(exp, ...)
	Assumes the expression evaluates to either a null value or an empty string.
#define	AssumingNotNullOrEmpty(exp, ...)
	Assumes the expression does not evaluate to neither a null value nor an empty string.
#define	AssumingValidIndex(_index, _container, ...)
	Assumes the _index expression evaluates to a valid index to the _container expression. This is checked via size(_container)
#define	AssumingValidIterator(_iterator, _container, ...)
	Assumes the _index expression evaluates to a valid iterator to the _container expression. This is checked via end(_container)
#define	AssumingBetween(v, a, b, ...)
	Assumes the v expression evaluates to a value between a and b exclusive.
#define	AssumingBetweenInclusive(v, a, b, ...)
	Assumes the v expression evaluates to a value between a and b inclusive.

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 expression is true. Expression result must be convertible to bool.

Definition at line 87 of file assuming.h.

ASSUMING_ASSUME

#define ASSUMING_ASSUME

(

cond

)

Definition at line 80 of file assuming.h.

ASSUMING_DEBUG

#define ASSUMING_DEBUG

You can define this macro project-wide 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 41 of file assuming.h.

ASSUMING_INCLUDE_MAGIC_ENUM

#define ASSUMING_INCLUDE_MAGIC_ENUM

You can define this macro project-wide 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 50 of file assuming.h.

AssumingBetween

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

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

Definition at line 192 of file assuming.h.

AssumingBetweenInclusive

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

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

Definition at line 200 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 133 of file assuming.h.

AssumingContainsBits

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

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

Definition at line 153 of file assuming.h.

AssumingEmpty

#define AssumingEmpty	(		exp,
			...
	)

Assumes the expression evaluates to an empty container (tested via empty(container))

Definition at line 163 of file assuming.h.

AssumingEqual

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

Assumes the two expressions evaluate equal.

Definition at line 140 of file assuming.h.

AssumingGreater

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

Assumes the first expression is greater than the second.

Definition at line 144 of file assuming.h.

AssumingGreaterEqual

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

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

Definition at line 148 of file assuming.h.

AssumingLess

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

Assumes the first expression is less than the second.

Definition at line 146 of file assuming.h.

AssumingLessEqual

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

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

Definition at line 150 of file assuming.h.

AssumingNotEmpty

#define AssumingNotEmpty	(		exp,
			...
	)

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

Definition at line 167 of file assuming.h.

AssumingNotEqual

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

Assumes the two expressions do not evaluate equal.

Definition at line 142 of file assuming.h.

AssumingNotNull

#define AssumingNotNull	(		exp,
			...
	)

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

Definition at line 129 of file assuming.h.

AssumingNotNullOrEmpty

#define AssumingNotNullOrEmpty	(		exp,
			...
	)

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

Definition at line 175 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 117 of file assuming.h.

AssumingNotReachable

#define AssumingNotReachable

(

...

)

Assumes the point in code is not reachable.

Definition at line 91 of file assuming.h.

AssumingNotRecursive

#define AssumingNotRecursive

(

...

)

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

Definition at line 94 of file assuming.h.

AssumingNull

#define AssumingNull	(		exp,
			...
	)

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

Definition at line 125 of file assuming.h.

AssumingNullOrEmpty

#define AssumingNullOrEmpty	(		exp,
			...
	)

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

Definition at line 171 of file assuming.h.

AssumingOnThread

#define AssumingOnThread	(		thread_to_check,
			...
	)

Assumes the point in code executes on the specified thread.

Definition at line 109 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 101 of file assuming.h.

AssumingValidIndex

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

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

Definition at line 179 of file assuming.h.

AssumingValidIterator

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

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

Definition at line 187 of file assuming.h.

AssumingZero

#define AssumingZero	(		a,
			...
	)

Assumes the expression evaluates to 0.

Definition at line 160 of file assuming.h.

Variable Documentation

AssumptionFailureHandler

void(* ghassanpl::AssumptionFailureHandler) (std::string_view expectation, std::initializer_list< std::pair< std::string_view, std::string > > values, std::string data, source_location loc) ( std::string_view  expectation, std::initializer_list< std::pair< std::string_view, std::string > >  values, std::string  data, source_location  loc  )

inline

This function must be provided by your own code, as it is called by an assumption macro with a failing assumption.

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 333 of file assuming.h.