Description

Tiny helper functions and shortcuts to be used everywhere Consider this header to be effectively included in almost every translation unit.

Remarks: The motivation of using these helpers is conciseness and uniformity of expression. Further extensions and not-so-frequently used supplements are packaged into separate headers.

Warning: be sure to understand the ramifications of including anything here...

See also: util-coll.hpp; util-quant.hpp; util-foreach.hpp

Definition in file util.hpp.

#include "include/limits.hpp"
#include "lib/hash-standard.hpp"
#include <string>

Classes
class	allocator< T >
	STL class.

class	set< K >
	STL class.

Typedefs
using	CStr = const char *

Macros
#define	__STRNGFY(TOKEN) #TOKEN

#define	INSTANCEOF(CLASS, EXPR) (dynamic_cast<const CLASS*> (EXPR))
	shortcut for subclass test, intended for assertions only. More...

#define	MAX(A, B) ((A < B) ? (B) : (A))
	the inevitable MAX macro, sometimes still necessary in template code

#define	SIDEEFFECT __attribute__ ((unused));
	suppress "warning: unused variable" on vars, which are introduced into a scope because of some sideeffect, i.e. More...

#define	STRINGIFY(TOKEN) __STRNGFY(TOKEN)
	this macro wraps its parameter into a cstring literal

Functions
template<typename MAP >
MAP::mapped_type const &	access_or_default (MAP &map, typename MAP::key_type const &key, typename MAP::mapped_type const &refDefault)
	expose a reference to a map entry, with fall-back to some default object More...

template<class X >
size_t	addrID (X const &x)
	generate an unique numeric ID based on the referred entity

bool	boolVal (string const &)
	interpret text representation of a boolean value. More...

template<typename MAP >
bool	contains (MAP &map, typename MAP::key_type const &key)
	shortcut for containment test on a map

template<typename T , class CMP , class ALO >
bool	contains (std::set< T, CMP, ALO > const &set, T const &val)
	shortcut for set value containment test

template<typename T >
bool	contains (std::string const &str, const T &val)
	shortcut for string value containment test

template<typename SEQ >
bool	contains (SEQ const &cont, typename SEQ::const_reference val)
	shortcut for brute-force containment test in any sequential container

const char *	cStr (std::string const &)
	convenience shortcut: forced conversion to c-String via string. More...

bool	endsWith (string const &str, string const &suffix)
	check if string ends with the given suffix

bool	endsWith (string const &str, CStr suffix)

template<typename IT , typename V >
IT	find (IT, IT, V const &)

template<class X >
const void *	getAdr (X &x)
	extract address but strip any type info

template<class X >
const void *	getAdr (X *x)

template<typename MAP >
MAP::mapped_type	getValue_or_default (MAP &map, typename MAP::key_type const &key, typename MAP::mapped_type defaultVal)
	fetch value from a Map, or return a default if not found

template<typename A , typename B >
bool	isCloseBy (A &&a, B &&b, size_t consideredNearby=50)
	determine heuristically if two objects are located „close to each other“ in memory. More...

template<typename NUM , typename NB >
bool constexpr	isLimited (NB lowerBound, NUM val, NB upperBound)

template<class CONT >
bool	isnil (const CONT &container)
	a family of util functions providing a "no value whatsoever" test. More...

template<class CONT >
bool	isnil (const CONT *pContainer)

template<class CONT >
bool	isnil (CONT *pContainer)

bool	isnil (CStr charPtr)

bool	isNo (string const &) noexcept
	check if the given text is empty or can be interpreted as rejection (bool `false`)- More...

template<class A , class B >
bool	isSameAdr (A const &a, B const &b)
	compare plain object address identity, disregarding type. More...

template<class A , class B >
bool	isSameObject (A const &a, B const &b)
	compare plain object identity, based directly on the referee's memory identities.

bool	isYes (string const &) noexcept
	check the given text if it can be interpreted as affirmative answer (bool `true`). More...

template<typename NUM , typename NB >
NUM constexpr	limited (NB lowerBound, NUM val, NB upperBound)
	force a numeric to be within bounds, inclusively

template<class IT >
bool	linearSearch (IT iter, typename IT::value_type const &val)
	use (and exhaust) a »Lumiera Forward Iterator« for linear search

template<class N1 , class N2 >
N1 constexpr	max (N1 n1, N2 n2)

template<class N1 , class N2 >
N1 constexpr	min (N1 n1, N2 n2)

template<typename NUM >
NUM constexpr	noneg (NUM val)
	cut a numeric value to be >=0

template<typename UN , typename N2 >
UN constexpr	positiveDiff (N2 newVal, UN refVal)

template<typename IT , typename V >
IT	remove (IT, IT, V const &)

template<class SET , typename FUN >
bool	remove_if (SET &set, FUN test)
	remove all elements fulfilling a given predicate from a (sorted) set. More...

template<typename SEQ >
SEQ::iterator	removeall (SEQ &coll, typename SEQ::value_type const &val)
	shortcut for removing all copies of an Element in any sequential collection

void	removePrefix (string &str, string const &prefix)

void	removeSuffix (string &str, string const &suffix)

std::string	sanitise (string const &org)
	produce an identifier based on the given string. More...

template<class NUM >
int constexpr	sgn (NUM n)

template<typename X >
size_t	slotNr (X const &x)
	the addressable memory »slot« — platform dependent. More...

int	sNum (CStr charPtr)

template<class OBJ >
int	sNum (OBJ const &spec)

bool	startsWith (string const &str, string const &prefix)
	check if string starts with a given prefix

bool	startsWith (string const &str, CStr prefix)

string	trim (string const &org)
	remove leading and trailing whitespace More...

template<class OBJ >
OBJ *	unConst (const OBJ *o)
	shortcut to save some typing when having to define const and non-const variants of member functions More...

template<class OBJ >
OBJ &	unConst (OBJ const &)

uint	uNum (CStr charPtr)
	positive integral number from textual representation More...

template<class OBJ >
uint	uNum (OBJ const &spec)

Macro Definition Documentation

◆ SIDEEFFECT

#define SIDEEFFECT __attribute__ ((unused));

suppress "warning: unused variable" on vars, which are introduced into a scope because of some sideeffect, i.e.

Locking

Definition at line 505 of file util.hpp.

◆ INSTANCEOF

#define INSTANCEOF	(	CLASS,
		EXPR
	)	(dynamic_cast<const CLASS*> (EXPR))

shortcut for subclass test, intended for assertions only.

Note: it is considered bad style to use such in non-assertion code, and we probably will enforce this design rule in future.

Definition at line 514 of file util.hpp.

Referenced by VerbPack< REC, RET, arg_storage >::accessArg(), stage::timeline::anonymous_namespace{clip-widget.cpp}::buildDelegateFor(), Dispatcher< TAR, TOOL >::callTrampoline(), CustomSharedPtr_test::check_type_relations(), ClonedContext::downcast(), PlacementIndexQueryResolver::resolutionFunction(), MockSupport_test::verify_MockJobTicket(), and ElementAccess_test::verify_simpleAccess().

Function Documentation

◆ cStr()

const char* cStr ( std::string const & rendered )

inline

convenience shortcut: forced conversion to c-String via string.

usable for printf with objects providing to-string conversion.

Definition at line 59 of file symbol.hpp.

Referenced by AppState::abort(), Asset::Asset(), TreeDiffMutatorBinding::emu(), HandlingPattern::invoke(), lumiera::error::lumiera_unexpectedException(), AppState::maybeStart(), TreeDiffMutatorBinding::mut(), TestSource::nextResult(), DispatcherLoop::runSessionThread(), UiStyle::setTheme(), MockSys::start(), NotificationService::triggerGuiShutdown(), and MockSys::triggerShutdown().

Here is the caller graph for this function:

◆ uNum()

uint util::uNum ( CStr charPtr )

inline

positive integral number from textual representation

Returns: always a number, 0 in case of unparseable text, limited to 0 <= num <= LUMIERA_MAX_ORDINAL_NUMBER

Definition at line 117 of file util.hpp.

◆ isnil()

bool util::isnil ( const CONT & container )

inline

a family of util functions providing a "no value whatsoever" test.

Works on strings and all STL containers, includes NULL test for pointers

Definition at line 154 of file util.hpp.

◆ access_or_default()

MAP::mapped_type const& util::access_or_default	(	MAP &	map,
		typename MAP::key_type const &	key,
		typename MAP::mapped_type const &	refDefault
	)

inline

expose a reference to a map entry, with fall-back to some default object

Note: exposing a const reference; especially the default needs to reside somewhere at a safe storage location.

See also: lib::NullValue

Definition at line 292 of file util.hpp.

References util::access_or_default().

Referenced by util::access_or_default().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ remove_if()

bool util::remove_if	(	SET &	set,
		FUN	test
	)

remove all elements fulfilling a given predicate from a (sorted) set.

Returns: true if anything has been removed.

Definition at line 319 of file util.hpp.

References util::remove_if().

Referenced by util::remove_if(), and RemoveFromSet_test::test_remove().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unConst()

OBJ * unConst ( const OBJ * o )

inline

shortcut to save some typing when having to define const and non-const variants of member functions

Remarks: the »social contract« when using this function is that the programmer has to ensure effective const correctness!

Definition at line 358 of file util.hpp.

References util::unConst().

Referenced by util::unConst().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ slotNr()

size_t util::slotNr ( X const & x )

inline

the addressable memory »slot« — platform dependent.

Definition at line 400 of file util.hpp.

References util::addrID(), and util::slotNr().

Referenced by util::slotNr().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isSameAdr()

bool util::isSameAdr	(	A const &	a,
		B const &	b
	)

inline

compare plain object address identity, disregarding type.

Note: the pointee is compared when passing pointer(s)

Definition at line 411 of file util.hpp.

References util::isSameAdr().

Referenced by util::isSameAdr(), and UtilIdentity_test::verify_isSameAdr().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isCloseBy()

bool util::isCloseBy	(	A &&	a,
		B &&	b,
		size_t	consideredNearby = `50`
	)

inline

determine heuristically if two objects are located „close to each other“ in memory.

Remarks: can be used to find out about heap versus stack allocation

Warning: relies on platform and implementation-defined observable behaviour

Definition at line 434 of file util.hpp.

References util::isCloseBy().

Referenced by util::isCloseBy().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ sanitise()

string sanitise ( string const & org )

produce an identifier based on the given string.

remove non-standard-chars, reduce sequences of punctuation and whitespace to single underscores. The sanitised string will start with an alphanumeric character.

Example Conversions

   "Word"                             --> "Word"
   "a Sentence"                       --> "a_Sentence"
   "trailing Withespace  \t \n"       --> "trailing_Withespace"
   "with    a   lot  \nof Whitespace" --> "with_a_lot_of_Whitespace"
   "@with\".\'much ($punctuation)[]!" --> "@with.much_($punctuation)"
   "§&Ω%€  leading garbage"           --> "leading_garbage"
   "mixed    Ω   garbage"             --> "mixed_garbage"
   "Bääääh!!"                         --> "Bh"

See also: UtilSanitizedIdentifier_test; lib::meta::sanitisedSymbol()

Definition at line 56 of file util.cpp.

References util::isValid(), and util::sanitise().

Referenced by util::sanitise().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ trim()

string trim ( string const & org )

remove leading and trailing whitespace

Remarks: this function just forwards to boost::algorithm::trim_copy. Use this call when boost header inclusion is an issue, otherwise a direct invocation is likely to perform better, due to inlining.

Returns: a trimmed copy (default locale)

Definition at line 84 of file util.cpp.

References util::trim().

Referenced by util::trim().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ boolVal()

bool boolVal ( string const & )

interpret text representation of a boolean value.

Remarks

this function detects the relevant token rather strict....

yields true for the tokens "true", "True", "TRUE", "yes", "Yes", "YES", "1", "+"
yields false for the tokens "false", "False", "FALSE", "no", "No, "NO", "0", "-"
leading and trailing whitespace is ignored

Exceptions

lumiera::error::Invalid for any other text content

Definition at line 98 of file util.cpp.

References util::boolVal().

Referenced by util::boolVal().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isYes()

bool isYes ( string const & )

noexcept

check the given text if it can be interpreted as affirmative answer (bool true).

Remarks: this function just fishes for the known true tokens and interprets all other content as false, including empty strings. Never throws.

Definition at line 107 of file util.cpp.

References util::isYes().

Referenced by util::isYes().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isNo()

bool isNo ( string const & )

noexcept

check if the given text is empty or can be interpreted as rejection (bool false)-

Remarks: this function fishes for the known false tokens; any other non-empty content counts as not no.

Definition at line 114 of file util.cpp.

References util::isNo().

Referenced by util::isNo().

Here is the call graph for this function:

Here is the caller graph for this function:

Description

Classes

Typedefs

Macros

Functions

Macro Definition Documentation

◆ SIDEEFFECT

◆ INSTANCEOF

Function Documentation

◆ cStr()

◆ uNum()

◆ isnil()

◆ access_or_default()

◆ remove_if()

◆ unConst()

◆ slotNr()

◆ isSameAdr()

◆ isCloseBy()

◆ sanitise()

◆ trim()

◆ boolVal()

◆ isYes()

◆ isNo()