Lumiera  0.pre.03
»edit your freedom«
util.hpp File Reference

Go to the source code of this file.

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. There are several extensions and not-so-frequently used supplements packaged into separate headers.
Warning
be sure to understand the ramifications of including anything here...
See also
util-coll.hpp
util-foreach.hpp
util-quant.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...
 
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 * getAddr (X &x)
 extract address but strip any type info
 
template<class X >
const void * getAddr (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 isSameObject (A const &a, B const &b)
 compare plain object identity, bypassing any custom comparison operators.
 
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 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
 
template<typename X >
size_t slotNr (X const *x)
 
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
 
template<class OBJ >
OBJ & unConst (OBJ const &ro)
 
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 483 of file util.hpp.

◆ INSTANCEOF

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

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 68 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 119 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 156 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:

◆ 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 vs. stack allocation

Definition at line 413 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 65 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 93 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::Invalidfor any other text content

Definition at line 107 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 116 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 123 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: