EvoContainers

Evo containers. More...

Classes
class	Array< T, TSize >
	Dynamic array container with similar interface to List. More...
class	AtomicBufferQueue< T, TSize >
	Fast buffer-based queue, implemented with a ring-buffer. More...
class	BitArraySubsetT< TParent >
	A subset of a BitArray. More...
class	BitArrayT< T, TSize >
	Dynamic bit array container with similar interface to Array and List. More...
class	BufferQueue< T, TSize >
	Fast buffer-based queue, implemented with a ring-buffer. More...
class	Capacity
	Optimized container size and capacity calculation. More...
struct	Compare< T >
	Comparison object used with containers that order/sort items. More...
struct	CompareBase< T >
	Base type for comparison types. More...
struct	CompareHash< T >
	Hash object used with containers that hash items. More...
struct	CompareI< T >
	Comparison object used with containers that order/sort items (case-insensitive). More...
struct	CompareIR< T >
	Comparison object used with containers that order/sort items (case-insensitive, reverse). More...
struct	CompareR< T >
	Comparison object used with containers that order/sort items (reverse). More...
struct	DataCompare< T, B1, B2 >
	Data comparison helpers. More...
struct	DataCopy< T, U >
	Optimized data copy helpers. More...
struct	DataEqual< T, B >
	Data equality helper. More...
struct	DataFill< T, U >
	Optimized data fill helpers. More...
struct	DataHash< T, H, B >
	Optimized data hash helpers. More...
struct	DataInit< T, U >
	Optimized data initialization and uninitialization helpers. More...
struct	DataType< T >
	Base data type for optimizated data helpers. More...
class	EnumIterator< T, F, L >
	Iterator template for sequential enum values. More...
struct	EnumMapIterator< T >
	Expanded EnumIterator used with enum traits. More...
class	ExceptionSubStringMapList
	SubStringMapList input ordering verification failed, see Exception. More...
struct	FmtAttribs
	Formatting attributes (used internally). More...
struct	FmtChar
	Explicitly format a repeated character. More...
struct	FmtDump
	Explicitly format a hex dump from buffer. More...
struct	FmtFieldFloat< T >
	This pairs a FmtFloatT type with FmtSetField for output formatting. More...
struct	FmtFieldNum< T >
	This pairs a FmtIntT type with FmtSetField for output formatting. More...
struct	FmtFloatT< T >
	Explicitly format a floating pointer number. More...
struct	FmtIntT< T >
	Explicitly format an integer. More...
struct	FmtPtr
	Explicitly format a pointer. More...
struct	FmtSetField
	Holds field and alignment formatting attributes. More...
struct	FmtSetFloat
	Holds floating point formatting attributes. More...
struct	FmtSetInt
	Holds integer formatting attributes. More...
struct	FmtSetNull
	Holds string to use when formatting null values. More...
struct	FmtString
	Explicitly format a string. More...
struct	FmtStringWrap
struct	FmtTable
	Text table formatter. More...
struct	FmtTableAttribs
	Helper for adjusting FmtTable column attributes. More...
struct	FmtTableOut< T, W >
	Output interface for writing text table to stream/string. More...
class	IteratorBase< T >
	Base iterator (used internally). More...
class	IteratorBi< T >
	Bidirectional iterator. More...
class	IteratorFw< T >
	Forward iterator. More...
class	IteratorRa< T >
	Random access iterator. More...
class	List< T, TSize >
	Sequential list container with random access. More...
class	Map< TKey, TValue, TSize >
	Associative container holding key/value pairs for fast lookup. More...
class	MapHash< TKey, TValue, THash, TSize >
	Map implemented as a hash table. More...
class	MapList< TKey, TValue, TCompare, TSize >
	Map implemented as an ordered list. More...
struct	Pair< TA, TB >
	Stores a key/value pair of independent objects or values. More...
class	PtrList< T, TSize >
	Sequential list of managed pointers with random access. More...
class	Set< TKey, TSize >
	Associative container with unique values for fast lookup. More...
class	SetHash< TKey, THash, TSize >
	Set implemented as a hash table. More...
class	SetList< TKey, TCompare, TSize >
	Set implemented as an ordered sequential array/list. More...
class	String
	String container. More...
struct	StringFlt< T, PADDING >
	String fixed-size buffer for formatting a floating point number. More...
struct	StringInt< T, PADDING >
	String fixed-size buffer for formatting an integer. More...
struct	StrQuoting
	Helpers for determining quoting type to use with string data. More...
struct	SubList< T, TSize >
	Reference and access existing list data. More...
struct	SubString
	Reference and access existing string data. More...
class	SubStringMapList
	References a list of sorted substrings for fast lookup. More...
class	UnicodeString
	Unicode string container using UTF-16. More...
class	Var
	General purpose variable that can hold a basic value (string, number, bool, etc) or children with nested values (object, list). More...
class	VarObject
	Explicit variant of Var used for initializing as an object with an initializer list of key/value pairs (C++11). More...

Macros
#define	EVO_ENUM_CLASS_MAP(ENUM, ...)
	Helper for creating enum class string/value mappers (C++11). More...
#define	EVO_ENUM_CLASS_REMAP(ENUM, REMAP_ARRAY, ...)
	Helper for creating enum class string/value mappers, with unsorted enum remapped to sorted values. More...
#define	EVO_ENUM_CLASS_TRAITS(ENUM, TRAITS, ...)
	Helper for creating enum class trait mappers (C++11). More...
#define	EVO_ENUM_MAP(ENUM, FIRST_VAL, LAST_VAL, UNKNOWN_VAL, ...)
	Helper for creating enum string/value mappers with explicit first/last/unknown values. More...
#define	EVO_ENUM_MAP_PREFIXED(ENUM, PREFIX, ...)   EVO_ENUM_MAP(ENUM, (ENUM)((int)(PREFIX ## UNKNOWN) + 1), (ENUM)((int)(PREFIX ## ENUM_END) - 1), PREFIX ## UNKNOWN, __VA_ARGS__)
	Helper for creating enum string/value mappers with prefixed enum values. More...
#define	EVO_ENUM_REMAP(ENUM, FIRST_VAL, LAST_VAL, UNKNOWN_VAL, REMAP_ARRAY, ...)
	Helper for creating enum string/value mappers with explicit first/last/unknown values, with unsorted enum remapped to sorted values. More...
#define	EVO_ENUM_REMAP_PREFIXED(ENUM, PREFIX, REMAP_ARRAY, ...)   EVO_ENUM_REMAP(ENUM, (ENUM)((int)(PREFIX ## UNKNOWN) + 1), (ENUM)((int)(PREFIX ## ENUM_END) - 1), PREFIX ## UNKNOWN, REMAP_ARRAY, __VA_ARGS__)
	Helper for creating enum string/value mappers with prefixed enum values, with unsorted enum remapped to sorted values. More...
#define	EVO_ENUM_TRAITS(ENUM, TRAITS, START_VAL, ...)
	Helper for creating enum trait mappers. More...
#define	EVO_EXCEPTION_GUARD_END   } catch (...) { abort(); }
	End exception guard, catch and abort(). More...
#define	EVO_EXCEPTION_GUARD_START   try {
	Start exception guard (try block). More...
#define	EVO_FIXED_ARRAY_SIZE(ARRAY)   (sizeof(evo::impl::FixedArraySizeHelper(ARRAY)))
	Get size of fixed-length array at compile-time. More...

Typedefs
typedef BitArrayT	BitArray
	Default dynamic bit array container – see BitArrayT. More...
typedef BitArraySubsetT< BitArray >	BitArraySubset
	Default subset of a BitArray – see BitArraySubsetT. More...
typedef FmtFloatT< float >	FmtFloat
	Explicitly format a floating pointer number. More...
typedef FmtFloatT< double >	FmtFloatD
	Explicitly format a floating pointer number. More...
typedef FmtFloatT< ldouble >	FmtFloatL
	Explicitly format a floating pointer number. More...
typedef FmtIntT< int >	FmtInt
	Explicitly format an integer. More...
typedef FmtIntT< int16 >	FmtInt16
	Explicitly format an integer. More...
typedef FmtIntT< int32 >	FmtInt32
	Explicitly format an integer. More...
typedef FmtIntT< int64 >	FmtInt64
	Explicitly format an integer. More...
typedef FmtIntT< int8 >	FmtInt8
	Explicitly format an integer. More...
typedef FmtIntT< long >	FmtLong
	Explicitly format an integer. More...
typedef FmtIntT< longl >	FmtLongL
	Explicitly format an integer. More...
typedef FmtIntT< short >	FmtShort
	Explicitly format an integer. More...
typedef FmtIntT< uint >	FmtUInt
	Explicitly format an integer. More...
typedef FmtIntT< uint16 >	FmtUInt16
	Explicitly format an integer. More...
typedef FmtIntT< uint32 >	FmtUInt32
	Explicitly format an integer. More...
typedef FmtIntT< uint64 >	FmtUInt64
	Explicitly format an integer. More...
typedef FmtIntT< uint8 >	FmtUInt8
	Explicitly format an integer. More...
typedef FmtIntT< ulong >	FmtULong
	Explicitly format an integer. More...
typedef FmtIntT< ulongl >	FmtULongL
	Explicitly format an integer. More...
typedef FmtIntT< ushort >	FmtUShort
	Explicitly format an integer. More...
typedef MapHash< String, String >	StrHash
	MapHash using String keys and values. More...
typedef String::ListBaseType	StringBase
	Base string typedef. More...
typedef MapList< String, String >	StrMapList
	MapList using String keys and values. More...
typedef SetHash< String >	StrSetHash
	SetHash using String values. More...
typedef SetList< String >	StrSetList
	SetList using String values. More...
typedef Var	VarList
	Alias for Var, useful for explicitly passing a list to a VarObject field value (C++11). More...

Enumerations
enum	CharBreakType {   cbtOTHER = 0, cbtWSPACE, cbtQUOTE, cbtBEGIN,   cbtEND, cbtWORD }
	Character break type returned by ascii_breaktype(). More...
enum	CharType {   ctOTHER = 0, ctWSPACE, ctPUNCT, ctDIGIT,   ctUPPER, ctLOWER }
	Character type returned by ascii_type(). More...
enum	FmtAlign { faCURRENT = 0, fLEFT, fCENTER, fRIGHT }
	Formatting alignment. More...
enum	FmtBase {   fbCURRENT = 0, fbAUTO = 0, fBIN = 2, fOCT = 8,   fDEC = 10, fHEX = 16, fHEXL = 116 }
	Formatting integer base. More...
enum	FmtBasePrefix { fbpCURRENT = 0, fPREFIX0, fPREFIX1, fPREFIX2 }
	Formatting integer base prefix type. More...
enum	FmtPrecision {   fpCURRENT = -2, fPREC_AUTO = -1, fPREC0 = 0, fPREC1,   fPREC2, fPREC3, fPREC4, fPREC5,   fPREC6 }
	Formatting floating point precision type. More...
enum	FmtWidth { fWIDTH0 = 0 }
	Formatting field width. More...
enum	IteratorDir { iterNONE, iterFW, iterRV }
	Iterator direction value. More...
enum	IteratorPos { iterFIRST, iterLAST, iterEND }
	Iterator position value. More...
enum	StringSearchAlg { ssaDEFAULT =0, ssaKMP, ssaBASIC }
	String search algorithm selection. More...
enum	UtfMode { umINCLUDE_INVALID, umREPLACE_INVALID, umSKIP_INVALID, umSTRICT }
	UTF decoding mode used to set how to handle invalid character values. More...

Functions
CharBreakType	ascii_breaktype (char ch)
	Get ASCII character word-break type. More...
char	ascii_tolower (char ch)
	Convert ASCII character to lowercase. More...
char	ascii_toupper (char ch)
	Convert ASCII character to uppercase. More...
CharType	ascii_type (char ch)
	Get ASCII character type. More...
template<class T , uint sz>
static uint	fixed_array_size (T(&)[sz])
	Get size of fixed-length array. More...
template<class T >
FmtTableOut< T, FmtTable::CachedWriter >	fmt_table (T &out, FmtTable &table, FmtTable::Type type=FmtTable::tTEXT)
	Create cached FmtTableOut paired with given string/stream to write to. More...
template<class T >
FmtTableOut< T, FmtTable::Writer >	fmt_table_nocache (T &out, FmtTable &table, FmtTable::Type type=FmtTable::tTEXT)
	Create cached FmtTableOut paired with given string/stream to write to. More...
template<class TMap >
SubString	lookupsub (const TMap &map, const typename TMap::Key &key)
	Lookup (find) map value as SubString for given key. More...
template<class T >
bool	map_contains (const T &map, const typename T::Key &key, const typename T::Value &value)
	Check whether map contains key with matching value. More...
template<class T >
bool	operator!= (const BitArraySubsetT< BitArrayT< T > > &a, const BitArrayT< T > &b)
	Inequality operator. More...
template<class T >
bool	operator== (const BitArraySubsetT< BitArrayT< T > > &a, const BitArrayT< T > &b)
	Equality operator. More...
template<class TMap >
const TMap::mapped_type *	stdlookup (const TMap &map, const typename TMap::key_type &key)
	Lookup (find) STL map value for given key (const). More...
template<class TMap >
TMap::mapped_type *	stdlookupM (TMap &map, const typename TMap::key_type &key)
	Lookup (find) STL map value for given key (mutable). More...
template<class TMap >
SubString	stdlookupsub (const TMap &map, const typename TMap::key_type &key)
	Lookup (find) STL map value as SubString for given key. More...
bool	str_scan_backtickdel (const char *str, const char *end)
	Scan string for a Backtick + DEL pair. More...
template<class T >
const char *	str_scan_decimal (T &num, const char *str, const char *end)
	Scan string pointer for decimal number and return stop pointer. More...
const char *	str_scan_delim (const char *str, const char *end, char delim1, char delim2)
	Scan string pointer for next delimiter and return stop pointer. More...
const char *	str_scan_delim (const char *str, const char *end, const char *delims, uint delim_count)
	Scan string pointer for next delimiter and return stop pointer. More...
const char *	str_scan_delim_r (const char *str, const char *end, char delim1, char delim2)
	Scan string pointer for next delimiter in reverse and return new end after stop pointer. More...
const char *	str_scan_delim_r (const char *str, const char *end, const char *delims, uint delim_count)
	Scan string pointer for next delimiter in reverse and return new end after stop pointer. More...
const char *	str_scan_endq (const char *&startq, const char *&endq, const char *str, const char *end)
	Scan string pointer and extract quoted or unquoted text. More...
const char *	str_scan_endq (const char *&startq, const char *&endq, const char *str, const char *end, char delim)
	Scan string pointer and extract quoted or unquoted text with a delimiter. More...
const char *	str_scan_endq (const char *&startq, const char *&endq, const char *str, const char *end, char delim1, char delim2)
	Scan string pointer and extract quoted or unquoted text with 2 possible delimiters. More...
const char *	str_scan_endq (const char *&startq, const char *&endq, const char *str, const char *end, const char *delims, uint delim_count, char ws_delim=0)
	Scan string pointer and extract quoted or unquoted text with multiple possible delimiters. More...
const char *	str_scan_endq_r (const char *&startq, const char *&endq, const char *str, const char *end, char delim)
	Scan string pointer in reverse and extract quoted or unquoted text with a delimiter and return new end after stop pointer. More...
const char *	str_scan_endq_r (const char *&startq, const char *&endq, const char *str, const char *end, const char *delims, uint delim_count, char ws_delim=0)
	Scan string pointer in reverse and extract quoted or unquoted text with multiple possible delimiters and return new end after stop pointer. More...
template<class T >
const char *	str_scan_hex (T &num, const char *str, const char *end)
	Scan string pointer for hex number and return stop pointer. More...
const char *	str_scan_ndelim (const char *str, const char *end, char delim1, char delim2)
	Scan string pointer for next non-delimiter and return stop pointer. More...
const char *	str_scan_ndelim_r (const char *str, const char *end, char delim1, char delim2)
	Scan string pointer for next non-delimiter in reverse and return new end after stop pointer. More...
const char *	str_scan_nws (const char *str, const char *end)
	Scan string pointer for next non-whitespace character and return stop pointer. More...
const char *	str_scan_nws (const char *str, const char *end, char delim)
	Scan string pointer for next delimiter or non-whitespace character and return stop pointer. More...
const char *	str_scan_nws_r (const char *str, const char *end)
	Scan string pointer for next non-whitespace character in reverse and return new end after stop pointer. More...
const char *	str_scan_nws_r (const char *str, const char *end, char delim)
	Scan string pointer for next delimiter or non-whitespace character and return stop pointer. More...
const char *	str_scan_to (uint maxlen, const char *str, const char *end, char ch)
	Scan string pointer for char and return stop pointer. More...
const char *	str_scan_to (uint maxlen, const char *str, const char *end, char ch1, char ch2)
	Scan string pointer for either of 2 chars and return stop pointer. More...
const char *	string_memrchr (const char *str, char ch, size_t size)
	Evo implementation of memrchr() to search for character in reverse. More...
int	utf16_compare (const wchar16 *str1, ulong len1, const wchar16 *str2, ulong len2)
	Compare two non-terminated UTF-16 strings. More...
int	utf16_compare (const wchar16 *str1, ulong len1, const wchar16 *str2)
	Compare a non-terminated UTF-16 string with a terminated UTF-16 string. More...
int	utf16_compare (const wchar16 *str1, const wchar16 *str2)
	Compare two terminated UTF-16 strings. More...
int	utf16_compare8 (const wchar16 *str1, ulong len1, const char *str2, ulong len2)
	Compare a non-terminated UTF-16 string to a non-terminated UTF-8 string. More...
int	utf16_compare8 (const wchar16 *str1, ulong len1, const char *str2)
	Compare a non-terminated UTF-16 string to a terminated UTF-8 string. More...
int	utf16_compare8 (const wchar16 *str1, const char *str2)
	Compare a terminated UTF-16 string to a terminated UTF-8 string. More...
ulong	utf16_count (const wchar16 *str, const wchar16 *end, UtfMode mode=umREPLACE_INVALID)
	Count Unicode character values in UTF-16 string. More...
const wchar16 *	utf16_min (const wchar16 *str, const wchar16 *end, bool strict=false, uint mincount=1)
	Scan for UTF-16 surrogate pairs, which each require a pair of wchar16 values (4 bytes). More...
const wchar16 *	utf16_scan (wchar32 &code, const wchar16 *str, const wchar16 *end, UtfMode mode=umREPLACE_INVALID)
	Scan for next Unicode character in UTF-16 string. More...
const wchar16 *	utf16_scan_term (wchar32 &code, const wchar16 *str, UtfMode mode=umREPLACE_INVALID)
	Scan for next Unicode character in terminated UTF-16 string. More...
ulong	utf16_strlen (const wchar16 *str)
	Find terminated UTF-16 string length. More...
ulong	utf16_to8 (const wchar16 *&str, const wchar16 *end, char *outbuf=NULL, ulong outsize=0, UtfMode mode=umREPLACE_INVALID)
	Convert UTF-16 string to UTF-8 string. More...
int	utf8_compare (const char *str1, ulong len1, const char *str2, ulong len2)
	Compare two non-terminated UTF-8 strings. More...
int	utf8_compare (const char *str1, ulong len1, const char *str2)
	Compare non-terminated and terminated UTF-8 strings. More...
int	utf8_compare (const char *str1, const char *str2)
	Compare two terminated UTF-8 strings. More...
ulong	utf8_count (const char *str, const char *end, UtfMode mode=umREPLACE_INVALID)
	Count Unicode character values in UTF-8 string. More...
const char *	utf8_min (const char *str, const char *end, bool strict=false, ulong mincount=1, uint minsize=2)
	Scan for UTF-8 multi-byte characters of at least minsize. More...
const char *	utf8_scan (wchar32 &code, const char *str, const char *end, UtfMode mode=umREPLACE_INVALID)
	Scan for next Unicode character in UTF-8 string. More...
const char *	utf8_scan_term (wchar32 &code, const char *str, UtfMode mode=umREPLACE_INVALID)
	Scan for next Unicode character in terminated UTF-8 string. More...
ulong	utf8_to16 (const char *&str, const char *end, wchar16 *outbuf=NULL, ulong outsize=0, UtfMode mode=umREPLACE_INVALID)
	Convert UTF-8 string to UTF-16 string. More...

Variables
static const wchar16	UNICODE_REPLACEMENT_CHAR = 0xFFFD
	Unicode code point for "Replacement Character" used when decoding invalid UTF bytes or values. More...

Detailed Description

Evo containers.

Macro Definition Documentation

EVO_ENUM_CLASS_MAP

#define EVO_ENUM_CLASS_MAP	(		ENUM,
			...
	)

Value:

struct ENUM ## Enum { \
            typedef ENUM Type; \
            typedef EnumMapIterator< ENUM ## Enum > Iter; \
            static const ENUM FIRST = (ENUM)((int)(ENUM::UNKNOWN) + 1); \
            static const ENUM LAST = (ENUM)((int)(ENUM::ENUM_END) - 1); \
            static const evo::SubStringMapList& map() { \
                static const evo::SubString LIST[] = { __VA_ARGS__ }; \
                static const evo::SubStringMapList MAP(LIST, evo::fixed_array_size(LIST)); \
                return MAP; \
            } \
            static ENUM get_enum(const evo::SubString& key) \
                { return map().find_enum_class<ENUM>(key); } \
            static ENUM get_enum(int val) \
                { return (val <= (int)ENUM::UNKNOWN || val >= (int)ENUM::ENUM_END ? ENUM::UNKNOWN : (ENUM)val); } \
            static int get_int(ENUM val) \
                { return (int)val; } \
            static SubString get_string(ENUM val) \
                { return map().get_enum_class_string(val); } \
        }

Helper for creating enum class string/value mappers (C++11).

• #include <evo/enum.h>
• This creates a struct with traits that uses find_enum_class() and get_enum_class_string()
• The created struct type is named after ENUM with suffix "Enum", and has helper functions:
  • static ENUM get_enum(const evo::SubString& key):
    • Map string key to ENUM value
  • static SubString get_string(ENUM value):
    • Map ENUM value to string key, null if unknown
• Caution: The string values must match ENUM and must be sorted
• See example here: Enum Conversion

Parameters

ENUM	Enum type to create mappings for
...	Sorted list of string literals to map to each enum value – ex: "a", "b", "c"

EVO_ENUM_CLASS_REMAP

#define EVO_ENUM_CLASS_REMAP	(		ENUM,
			REMAP_ARRAY,
			...
	)

Value:

struct ENUM ## Enum { \
            typedef ENUM Type; \
            typedef EnumMapIterator< ENUM ## Enum > Iter; \
            static const ENUM FIRST = (ENUM)((int)(ENUM::UNKNOWN) + 1); \
            static const ENUM LAST = (ENUM)((int)(ENUM::ENUM_END) - 1); \
            static const ENUM* get_remap_array() { \
                return REMAP_ARRAY; \
            } \
            static const SizeT* get_reverse_remap_array() { \
                static const SubStringMapList::ReverseRemap< ENUM ## Enum > REVERSE(get_remap_array()); \
                return REVERSE.array; \
            } \
            static const evo::SubStringMapList& map() { \
                static const evo::SubString LIST[] = { __VA_ARGS__ }; \
                static const evo::SubStringMapList MAP(LIST, evo::fixed_array_size(LIST)); \
                return MAP; \
            } \
            static ENUM get_enum(const evo::SubString& key) \
                { return map().find_enum_remap<Type>(get_remap_array(), key, FIRST, LAST, Type::UNKNOWN); } \
            static ENUM get_enum(int val) \
                { return (val <= (int)ENUM::UNKNOWN || val >= (int)ENUM::ENUM_END ? ENUM::UNKNOWN : (ENUM)val); } \
            static int get_int(ENUM val) \
                { return (int)val; } \
            static SubString get_string(ENUM val) \
                { return map().get_enum_string_remap(get_reverse_remap_array(), val, FIRST, LAST); } \
        }

Helper for creating enum class string/value mappers, with unsorted enum remapped to sorted values.

(C++11).

• #include <evo/enum.h>
• This is a variant of EVO_ENUM_CLASS_MAP() for an unsorted enum
• This uses REMAP_ARRAY to map an unsorted enum to sorted values – the data should be constant and static

Parameters

ENUM	Enum type to create mappings for
REMAP_ARRAY	Pointer to array of ENUM values sorted so they match the sorted string literals that follow
...	Sorted list of string literals to map to each enum value – ex: "a", "b", "c"

EVO_ENUM_CLASS_TRAITS

#define EVO_ENUM_CLASS_TRAITS	(		ENUM,
			TRAITS,
			...
	)

Value:

struct ENUM ## EnumTraits { \
            typedef ENUM Type; \
            static const ENUM START = ENUM::UNKNOWN; \
            static const TRAITS& get(ENUM value) { \
                return data()[(int)value - (int)START]; \
            } \
        private: \
            static const TRAITS* data() { \
                static const TRAITS DATA[] = { __VA_ARGS__ }; \
                return DATA; \
            } \
        };

Helper for creating enum class trait mappers (C++11).

• #include <evo/enum.h>
• This creates a struct with a static array of TRAITS values mapped to enum values
• The created struct type is named after ENUM with suffix "EnumTraits", and has the helper function:
  • static const TRAITS& get(ENUM value)
    • Get traits for enum value

• If you want to specify a different starting value use EVO_ENUM_TRAITS(), which works on enum class too
• See: Enum Conversion

Parameters

ENUM	Enum type to create traits for
TRAITS	Traits type to create for each enum value, usually named after ENUM with suffix Traits
...	List of initializers for TRAITS values matching enum class values starting at ENUM::UNKNOWN

EVO_ENUM_MAP

#define EVO_ENUM_MAP	(		ENUM,
			FIRST_VAL,
			LAST_VAL,
			UNKNOWN_VAL,
			...
	)

Value:

struct ENUM ## Enum { \
        typedef ENUM Type; \
        typedef EnumMapIterator< ENUM ## Enum > Iter; \
        static const ENUM FIRST   = FIRST_VAL; \
        static const ENUM LAST    = LAST_VAL; \
        static const ENUM UNKNOWN = UNKNOWN_VAL; \
        static const evo::SubStringMapList& map() { \
            static const evo::SubString LIST[] = { __VA_ARGS__ }; \
            static const evo::SubStringMapList MAP(LIST, evo::fixed_array_size(LIST)); \
            return MAP; \
        } \
        static ENUM get_enum(const evo::SubString& key) \
            { return map().find_enum<ENUM>(key, FIRST, LAST, UNKNOWN); } \
        static ENUM get_enum(int val) \
            { return (val < (int)FIRST || val > (int)LAST ? UNKNOWN : (ENUM)val); } \
        static int get_int(ENUM val) \
            { return (int)val; } \
        static SubString get_string(ENUM val) \
            { return map().get_enum_string(val, FIRST, LAST); } \
    }

Helper for creating enum string/value mappers with explicit first/last/unknown values.

• #include <evo/enum.h>
• See better alternative: EVO_ENUM_MAP_PREFIXED()
• This creates a struct with traits that uses find_enum() and get_enum_string()
• The created struct type is named after ENUM with suffix "Enum", and has helper functions:
  • static ENUM get_enum(const evo::SubString& key):
    • Map string key to ENUM value
  • static SubString get_string(ENUM value):
    • Map ENUM value to string key, null if unknown
• Caution: The string values must match ENUM and must be sorted
• See: Enum Conversion

Parameters

ENUM	Enum type to create traits for
FIRST_VAL	First enum value to map to, maps to first string
LAST_VAL	Last enum value to map to, maps to last string – must be >= first_enum
UNKNOWN_VAL	Unknown enum value to use if key not found or result out of range
...	Sorted list of string literals to map to each enum value – ex: "a", "b", "c"

EVO_ENUM_MAP_PREFIXED

#define EVO_ENUM_MAP_PREFIXED	(		ENUM,
			PREFIX,
			...
	)		EVO_ENUM_MAP(ENUM, (ENUM)((int)(PREFIX ## UNKNOWN) + 1), (ENUM)((int)(PREFIX ## ENUM_END) - 1), PREFIX ## UNKNOWN, __VA_ARGS__)

Helper for creating enum string/value mappers with prefixed enum values.

• #include <evo/enum.h>
• This creates a struct with traits that uses find_enum_class() and get_enum_class_string()
• The created struct type is named after ENUM with suffix "Enum", and has helper functions:
  • static ENUM get_enum(const evo::SubString& key):
    • Map string key to ENUM value
  • static SubString get_string(ENUM value):
    • Map ENUM value to string key, null if unknown
• This requires ENUM type to have the following value names defined, each name beginning with PREFIX:
  • UNKNOWN – must be first
  • ENUM_END – must be last
  • and there must not be any gaps between the above values
• Caution: The string values must match ENUM and must be sorted
• See example here: Enum Conversion
• See also: EVO_ENUM_MAP()

Parameters

ENUM	Enum type to create mappings for
PREFIX	Prefix for enum values, used to find UNKNOWN and ENUM_END values
...	Sorted list of string literals to map to each enum value – ex: "a", "b", "c"

EVO_ENUM_REMAP

#define EVO_ENUM_REMAP	(		ENUM,
			FIRST_VAL,
			LAST_VAL,
			UNKNOWN_VAL,
			REMAP_ARRAY,
			...
	)

Value:

struct ENUM ## Enum { \
        typedef ENUM Type; \
        typedef EnumMapIterator< ENUM ## Enum > Iter; \
        static const ENUM FIRST   = FIRST_VAL; \
        static const ENUM LAST    = LAST_VAL; \
        static const ENUM UNKNOWN = UNKNOWN_VAL; \
        static const ENUM* get_remap_array() { \
            return REMAP_ARRAY; \
        } \
        static const SizeT* get_reverse_remap_array() { \
            static const SubStringMapList::ReverseRemap< ENUM ## Enum > REVERSE(get_remap_array()); \
            return REVERSE.array; \
        } \
        static const evo::SubStringMapList& map() { \
            static const evo::SubString LIST[] = { __VA_ARGS__ }; \
            static const evo::SubStringMapList MAP(LIST, evo::fixed_array_size(LIST)); \
            return MAP; \
        } \
        static ENUM get_enum(const evo::SubString& key) \
            { return map().find_enum_remap<Type>(get_remap_array(), key, FIRST, LAST, UNKNOWN); } \
        static ENUM get_enum(int val) \
            { return (val < (int)FIRST || val > (int)LAST ? UNKNOWN : (ENUM)val); } \
        static int get_int(ENUM val) \
            { return (int)val; } \
        static SubString get_string(ENUM val) \
            { return map().get_enum_string_remap(get_reverse_remap_array(), val, FIRST, LAST); } \
    }

Helper for creating enum string/value mappers with explicit first/last/unknown values, with unsorted enum remapped to sorted values.

• #include <evo/enum.h>
• This is a variant of EVO_ENUM_MAP() for an unsorted enum
• This uses REMAP_ARRAY to map an unsorted enum to sorted values – the data should be constant and static

Parameters

ENUM	Enum type to create traits for
FIRST_VAL	First enum value to map to, maps to first string
LAST_VAL	Last enum value to map to, maps to last string – must be >= first_enum
UNKNOWN_VAL	Unknown enum value to use if key not found or result out of range
REMAP_ARRAY	Pointer to array of ENUM values sorted so they match the sorted string literals that follow
...	Sorted list of string literals to map to each enum value – ex: "a", "b", "c"

EVO_ENUM_REMAP_PREFIXED

#define EVO_ENUM_REMAP_PREFIXED	(		ENUM,
			PREFIX,
			REMAP_ARRAY,
			...
	)		EVO_ENUM_REMAP(ENUM, (ENUM)((int)(PREFIX ## UNKNOWN) + 1), (ENUM)((int)(PREFIX ## ENUM_END) - 1), PREFIX ## UNKNOWN, REMAP_ARRAY, __VA_ARGS__)

Helper for creating enum string/value mappers with prefixed enum values, with unsorted enum remapped to sorted values.

• #include <evo/enum.h>
• This is a variant of EVO_ENUM_MAP_PREFIXED() for an unsorted enum
• This uses REMAP_ARRAY to map an unsorted enum to sorted values – the data should be constant and static

Parameters

ENUM	Enum type to create mappings for
PREFIX	Prefix for enum values, used to find UNKNOWN and ENUM_END values
REMAP_ARRAY	Pointer to array of ENUM values sorted so they match the sorted string literals that follow
...	Sorted list of string literals to map to each enum value – ex: "a", "b", "c"

EVO_ENUM_TRAITS

#define EVO_ENUM_TRAITS	(		ENUM,
			TRAITS,
			START_VAL,
			...
	)

Value:

struct ENUM ## EnumTraits { \
        typedef ENUM Type; \
        static const ENUM START = START_VAL; \
        static const TRAITS& get(ENUM value) { \
            return data()[(int)value - (int)START]; \
        } \
    private: \
        static const TRAITS* data() { \
            static const TRAITS DATA[] = { __VA_ARGS__ }; \
            return DATA; \
        } \
    };

Helper for creating enum trait mappers.

• #include <evo/enum.h>
• This creates a struct with a static array of TRAITS values mapped to enum values
• The created struct type is named after ENUM with suffix "EnumTraits", and has the helper function:
  • static const TRAITS& get(ENUM value)
    • Get traits for enum value

• See: Enum Conversion

Parameters

ENUM	Enum type to create traits for
TRAITS	Traits type to create for each enum value, usually named after ENUM with suffix Traits
START_VAL	Start enum value used as the starting point of enum values – usually this is the "UNKNOWN" enum value
...	List of initializers for TRAITS values matching enum values starting at START_VAL

EVO_EXCEPTION_GUARD_END

#define EVO_EXCEPTION_GUARD_END   } catch (...) { abort(); }

End exception guard, catch and abort().

EVO_EXCEPTION_GUARD_START

#define EVO_EXCEPTION_GUARD_START   try {

Start exception guard (try block).

EVO_FIXED_ARRAY_SIZE

#define EVO_FIXED_ARRAY_SIZE

(

ARRAY

)

(sizeof(evo::impl::FixedArraySizeHelper(ARRAY)))

Get size of fixed-length array at compile-time.

• Same as fixed_array_size(), but resolves to a compile-time constant using sizeof()

Typedef Documentation

BitArray

typedef BitArrayT BitArray

Default dynamic bit array container – see BitArrayT.

BitArraySubset

typedef BitArraySubsetT<BitArray> BitArraySubset

Default subset of a BitArray – see BitArraySubsetT.

FmtFloat

typedef FmtFloatT<float> FmtFloat

Explicitly format a floating pointer number.

• Used with operator<<() on String, Stream, and StreamOut
  • See String Formatting and Stream Formatting
• Don't use FmtFloatT directly, use one of the aliases:
  • FmtFloat, FmtFloatD, FmtFloatL

Example

Example using FmtFloat

#include <evo/string.h>
using namespace evo;

int main() {
    // Format string as: 01.230,4.56
    String str;
    str << FmtFloat(1.23, 3, 6) << ',' << 4.56;

    return 0;
}

FmtFloatD

typedef FmtFloatT<double> FmtFloatD

Explicitly format a floating pointer number.

• Used with operator<<() on String, Stream, and StreamOut
  • See String Formatting and Stream Formatting
• Don't use FmtFloatT directly, use one of the aliases:
  • FmtFloat, FmtFloatD, FmtFloatL

Example

Example using FmtFloat

#include <evo/string.h>
using namespace evo;

int main() {
    // Format string as: 01.230,4.56
    String str;
    str << FmtFloat(1.23, 3, 6) << ',' << 4.56;

    return 0;
}

FmtFloatL

typedef FmtFloatT<ldouble> FmtFloatL

Explicitly format a floating pointer number.

• Used with operator<<() on String, Stream, and StreamOut
  • See String Formatting and Stream Formatting
• Don't use FmtFloatT directly, use one of the aliases:
  • FmtFloat, FmtFloatD, FmtFloatL

Example

Example using FmtFloat

#include <evo/string.h>
using namespace evo;

int main() {
    // Format string as: 01.230,4.56
    String str;
    str << FmtFloat(1.23, 3, 6) << ',' << 4.56;

    return 0;
}

FmtInt

typedef FmtIntT<int> FmtInt

Explicitly format an integer.

• Used with operator<<() on String, Stream, and StreamOut
  • See String Formatting and Stream Formatting
• Don't use FmtIntT directly, use one of the aliases:
  • FmtShort, FmtInt, FmtLong, FmtLongL
  • FmtInt8, FmtInt16, FmtInt32, FmtInt64
  • FmtUShort, FmtUInt, FmtULong, FmtULongL
  • FmtUInt8, FmtUInt16, FmtUInt32, FmtUInt64

Example

Example using FmtInt

#include <evo/string.h>
using namespace evo;

int main() {
    // Format string as: 07B,45,67
    String str;
    str << FmtInt(123, fHEX, 3) << ',' FmtInt(45, fDEC) << ',' 67;

    return 0;
}

FmtInt16

typedef FmtIntT<int16> FmtInt16

Explicitly format an integer.

• Used with operator<<() on String, Stream, and StreamOut
  • See String Formatting and Stream Formatting
• Don't use FmtIntT directly, use one of the aliases:
  • FmtShort, FmtInt, FmtLong, FmtLongL
  • FmtInt8, FmtInt16, FmtInt32, FmtInt64
  • FmtUShort, FmtUInt, FmtULong, FmtULongL
  • FmtUInt8, FmtUInt16, FmtUInt32, FmtUInt64

Example

Example using FmtInt

#include <evo/string.h>
using namespace evo;

int main() {
    // Format string as: 07B,45,67
    String str;
    str << FmtInt(123, fHEX, 3) << ',' FmtInt(45, fDEC) << ',' 67;

    return 0;
}

FmtInt32

typedef FmtIntT<int32> FmtInt32

Explicitly format an integer.

• Used with operator<<() on String, Stream, and StreamOut
  • See String Formatting and Stream Formatting
• Don't use FmtIntT directly, use one of the aliases:
  • FmtShort, FmtInt, FmtLong, FmtLongL
  • FmtInt8, FmtInt16, FmtInt32, FmtInt64
  • FmtUShort, FmtUInt, FmtULong, FmtULongL
  • FmtUInt8, FmtUInt16, FmtUInt32, FmtUInt64

Example

Example using FmtInt

#include <evo/string.h>
using namespace evo;

int main() {
    // Format string as: 07B,45,67
    String str;
    str << FmtInt(123, fHEX, 3) << ',' FmtInt(45, fDEC) << ',' 67;

    return 0;
}

FmtInt64

typedef FmtIntT<int64> FmtInt64

Explicitly format an integer.

• Used with operator<<() on String, Stream, and StreamOut
  • See String Formatting and Stream Formatting
• Don't use FmtIntT directly, use one of the aliases:
  • FmtShort, FmtInt, FmtLong, FmtLongL
  • FmtInt8, FmtInt16, FmtInt32, FmtInt64
  • FmtUShort, FmtUInt, FmtULong, FmtULongL
  • FmtUInt8, FmtUInt16, FmtUInt32, FmtUInt64

Example

Example using FmtInt

#include <evo/string.h>
using namespace evo;

int main() {
    // Format string as: 07B,45,67
    String str;
    str << FmtInt(123, fHEX, 3) << ',' FmtInt(45, fDEC) << ',' 67;

    return 0;
}

FmtInt8

typedef FmtIntT<int8> FmtInt8

Explicitly format an integer.

• Used with operator<<() on String, Stream, and StreamOut
  • See String Formatting and Stream Formatting
• Don't use FmtIntT directly, use one of the aliases:
  • FmtShort, FmtInt, FmtLong, FmtLongL
  • FmtInt8, FmtInt16, FmtInt32, FmtInt64
  • FmtUShort, FmtUInt, FmtULong, FmtULongL
  • FmtUInt8, FmtUInt16, FmtUInt32, FmtUInt64

Example

Example using FmtInt

#include <evo/string.h>
using namespace evo;

int main() {
    // Format string as: 07B,45,67
    String str;
    str << FmtInt(123, fHEX, 3) << ',' FmtInt(45, fDEC) << ',' 67;

    return 0;
}

FmtLong

typedef FmtIntT<long> FmtLong

Explicitly format an integer.

• Used with operator<<() on String, Stream, and StreamOut
  • See String Formatting and Stream Formatting
• Don't use FmtIntT directly, use one of the aliases:
  • FmtShort, FmtInt, FmtLong, FmtLongL
  • FmtInt8, FmtInt16, FmtInt32, FmtInt64
  • FmtUShort, FmtUInt, FmtULong, FmtULongL
  • FmtUInt8, FmtUInt16, FmtUInt32, FmtUInt64

Example

Example using FmtInt

#include <evo/string.h>
using namespace evo;

int main() {
    // Format string as: 07B,45,67
    String str;
    str << FmtInt(123, fHEX, 3) << ',' FmtInt(45, fDEC) << ',' 67;

    return 0;
}

FmtLongL

typedef FmtIntT<longl> FmtLongL

Explicitly format an integer.

• Used with operator<<() on String, Stream, and StreamOut
  • See String Formatting and Stream Formatting
• Don't use FmtIntT directly, use one of the aliases:
  • FmtShort, FmtInt, FmtLong, FmtLongL
  • FmtInt8, FmtInt16, FmtInt32, FmtInt64
  • FmtUShort, FmtUInt, FmtULong, FmtULongL
  • FmtUInt8, FmtUInt16, FmtUInt32, FmtUInt64

Example

Example using FmtInt

#include <evo/string.h>
using namespace evo;

int main() {
    // Format string as: 07B,45,67
    String str;
    str << FmtInt(123, fHEX, 3) << ',' FmtInt(45, fDEC) << ',' 67;

    return 0;
}

FmtShort

typedef FmtIntT<short> FmtShort

Explicitly format an integer.

• Used with operator<<() on String, Stream, and StreamOut
  • See String Formatting and Stream Formatting
• Don't use FmtIntT directly, use one of the aliases:
  • FmtShort, FmtInt, FmtLong, FmtLongL
  • FmtInt8, FmtInt16, FmtInt32, FmtInt64
  • FmtUShort, FmtUInt, FmtULong, FmtULongL
  • FmtUInt8, FmtUInt16, FmtUInt32, FmtUInt64

Example

Example using FmtInt

#include <evo/string.h>
using namespace evo;

int main() {
    // Format string as: 07B,45,67
    String str;
    str << FmtInt(123, fHEX, 3) << ',' FmtInt(45, fDEC) << ',' 67;

    return 0;
}

FmtUInt

typedef FmtIntT<uint> FmtUInt

Explicitly format an integer.

• Used with operator<<() on String, Stream, and StreamOut
  • See String Formatting and Stream Formatting
• Don't use FmtIntT directly, use one of the aliases:
  • FmtShort, FmtInt, FmtLong, FmtLongL
  • FmtInt8, FmtInt16, FmtInt32, FmtInt64
  • FmtUShort, FmtUInt, FmtULong, FmtULongL
  • FmtUInt8, FmtUInt16, FmtUInt32, FmtUInt64

Example

Example using FmtInt

#include <evo/string.h>
using namespace evo;

int main() {
    // Format string as: 07B,45,67
    String str;
    str << FmtInt(123, fHEX, 3) << ',' FmtInt(45, fDEC) << ',' 67;

    return 0;
}

FmtUInt16

typedef FmtIntT<uint16> FmtUInt16

Explicitly format an integer.

• Used with operator<<() on String, Stream, and StreamOut
  • See String Formatting and Stream Formatting
• Don't use FmtIntT directly, use one of the aliases:
  • FmtShort, FmtInt, FmtLong, FmtLongL
  • FmtInt8, FmtInt16, FmtInt32, FmtInt64
  • FmtUShort, FmtUInt, FmtULong, FmtULongL
  • FmtUInt8, FmtUInt16, FmtUInt32, FmtUInt64

Example

Example using FmtInt

#include <evo/string.h>
using namespace evo;

int main() {
    // Format string as: 07B,45,67
    String str;
    str << FmtInt(123, fHEX, 3) << ',' FmtInt(45, fDEC) << ',' 67;

    return 0;
}

FmtUInt32

typedef FmtIntT<uint32> FmtUInt32

Explicitly format an integer.

• Used with operator<<() on String, Stream, and StreamOut
  • See String Formatting and Stream Formatting
• Don't use FmtIntT directly, use one of the aliases:
  • FmtShort, FmtInt, FmtLong, FmtLongL
  • FmtInt8, FmtInt16, FmtInt32, FmtInt64
  • FmtUShort, FmtUInt, FmtULong, FmtULongL
  • FmtUInt8, FmtUInt16, FmtUInt32, FmtUInt64

Example

Example using FmtInt

#include <evo/string.h>
using namespace evo;

int main() {
    // Format string as: 07B,45,67
    String str;
    str << FmtInt(123, fHEX, 3) << ',' FmtInt(45, fDEC) << ',' 67;

    return 0;
}

FmtUInt64

typedef FmtIntT<uint64> FmtUInt64

Explicitly format an integer.

• Used with operator<<() on String, Stream, and StreamOut
  • See String Formatting and Stream Formatting
• Don't use FmtIntT directly, use one of the aliases:
  • FmtShort, FmtInt, FmtLong, FmtLongL
  • FmtInt8, FmtInt16, FmtInt32, FmtInt64
  • FmtUShort, FmtUInt, FmtULong, FmtULongL
  • FmtUInt8, FmtUInt16, FmtUInt32, FmtUInt64

Example

Example using FmtInt

#include <evo/string.h>
using namespace evo;

int main() {
    // Format string as: 07B,45,67
    String str;
    str << FmtInt(123, fHEX, 3) << ',' FmtInt(45, fDEC) << ',' 67;

    return 0;
}

FmtUInt8

typedef FmtIntT<uint8> FmtUInt8

Explicitly format an integer.

• Used with operator<<() on String, Stream, and StreamOut
  • See String Formatting and Stream Formatting
• Don't use FmtIntT directly, use one of the aliases:
  • FmtShort, FmtInt, FmtLong, FmtLongL
  • FmtInt8, FmtInt16, FmtInt32, FmtInt64
  • FmtUShort, FmtUInt, FmtULong, FmtULongL
  • FmtUInt8, FmtUInt16, FmtUInt32, FmtUInt64

Example

Example using FmtInt

#include <evo/string.h>
using namespace evo;

int main() {
    // Format string as: 07B,45,67
    String str;
    str << FmtInt(123, fHEX, 3) << ',' FmtInt(45, fDEC) << ',' 67;

    return 0;
}

FmtULong

typedef FmtIntT<ulong> FmtULong

Explicitly format an integer.

• Used with operator<<() on String, Stream, and StreamOut
  • See String Formatting and Stream Formatting
• Don't use FmtIntT directly, use one of the aliases:
  • FmtShort, FmtInt, FmtLong, FmtLongL
  • FmtInt8, FmtInt16, FmtInt32, FmtInt64
  • FmtUShort, FmtUInt, FmtULong, FmtULongL
  • FmtUInt8, FmtUInt16, FmtUInt32, FmtUInt64

Example

Example using FmtInt

#include <evo/string.h>
using namespace evo;

int main() {
    // Format string as: 07B,45,67
    String str;
    str << FmtInt(123, fHEX, 3) << ',' FmtInt(45, fDEC) << ',' 67;

    return 0;
}

FmtULongL

typedef FmtIntT<ulongl> FmtULongL

Explicitly format an integer.

• Used with operator<<() on String, Stream, and StreamOut
  • See String Formatting and Stream Formatting
• Don't use FmtIntT directly, use one of the aliases:
  • FmtShort, FmtInt, FmtLong, FmtLongL
  • FmtInt8, FmtInt16, FmtInt32, FmtInt64
  • FmtUShort, FmtUInt, FmtULong, FmtULongL
  • FmtUInt8, FmtUInt16, FmtUInt32, FmtUInt64

Example

Example using FmtInt

#include <evo/string.h>
using namespace evo;

int main() {
    // Format string as: 07B,45,67
    String str;
    str << FmtInt(123, fHEX, 3) << ',' FmtInt(45, fDEC) << ',' 67;

    return 0;
}

FmtUShort

typedef FmtIntT<ushort> FmtUShort

Explicitly format an integer.

• Used with operator<<() on String, Stream, and StreamOut
  • See String Formatting and Stream Formatting
• Don't use FmtIntT directly, use one of the aliases:
  • FmtShort, FmtInt, FmtLong, FmtLongL
  • FmtInt8, FmtInt16, FmtInt32, FmtInt64
  • FmtUShort, FmtUInt, FmtULong, FmtULongL
  • FmtUInt8, FmtUInt16, FmtUInt32, FmtUInt64

Example

Example using FmtInt

#include <evo/string.h>
using namespace evo;

int main() {
    // Format string as: 07B,45,67
    String str;
    str << FmtInt(123, fHEX, 3) << ',' FmtInt(45, fDEC) << ',' 67;

    return 0;
}

StrHash

typedef MapHash<String,String> StrHash

MapHash using String keys and values.

• This is an alias to MapHash
• This is only defined if string.h is included before maphash.h

StringBase

typedef String::ListBaseType StringBase

Base string typedef.

• Use to explicitly convert a non-Evo string to a base string type
  • This is actually the base of all Evo string types
  • Use on char* or STL string (if STL compatiblity enabled)
  • Not needed with string literals like: "test"
  • Overhead is minimal (similar to SubString)
• This can solve compiler errors creating a temporary when "too many implicit conversions" are available
  Example:

  std::string stdstr("test");
  evo::String str(evo::StringBase(stdstr));

• See also: SubString, STL Compatibility

StrMapList

typedef MapList<String,String> StrMapList

MapList using String keys and values.

• This is an alias to MapList
• This is only defined if string.h is included before maplist.h

StrSetHash

typedef SetHash<String> StrSetHash

SetHash using String values.

• This is an alias to SetHash
• This is only defined if string.h is included before sethash.h

StrSetList

typedef SetList<String> StrSetList

SetList using String values.

• This is an alias to SetList
• This is only defined if string.h is included before setlist.h

VarList

typedef Var VarList

Alias for Var, useful for explicitly passing a list to a VarObject field value (C++11).

• Only use this with initializer lists – avoid defining a variable or parameter with this type
• See Var examples

Enumeration Type Documentation

CharBreakType

enum CharBreakType

Character break type returned by ascii_breaktype().

Enumerator
cbtOTHER	Other charcater type.
cbtWSPACE	Whitespace character, used between words.
cbtQUOTE	Quote character, break word before or after this depending on whether begin or end quote ('"`)
cbtBEGIN	Punctuation used before a word begins, break words before this ( ([{< )
cbtEND	Punctuation used after a word ends, break words after this ( )]}>!%;,./ )
cbtWORD	Word character (A-Z, a-z, 0-9, _)

CharType

enum CharType

Character type returned by ascii_type().

Enumerator
ctOTHER	Other character type.
ctWSPACE	Whitespace character.
ctPUNCT	Punctuation or symbol character.
ctDIGIT	Numeric digit character (0-9)
ctUPPER	Uppercase alphabetic character (A-Z)
ctLOWER	Lowercase alphabetic character (a-z)

FmtAlign

enum FmtAlign

Formatting alignment.

• Used with FmtSetField and operator<<() on String::Format, Stream, or StreamOut

Enumerator
faCURRENT	Current alignment (i.e. unspecified/default)
fLEFT	Align left by adding filler on right side.
fCENTER	Align center by adding filler on left and right sides.
fRIGHT	Align right by adding filler on left side.

FmtBase

enum FmtBase

Formatting integer base.

• Used with FmtSetInt and operator<<() on String::Format, Stream, or StreamOut

Enumerator
fbCURRENT	Current base (i.e. unspecified/default)
fbAUTO	Auto base detection.
fBIN	Base 2: binary.
fOCT	Base 8: octal.
fDEC	Base 10: decimal (default)
fHEX	Base 16: hexadecimal.
fHEXL	Base 16: hexadecimal (lowercase)

FmtBasePrefix

enum FmtBasePrefix

Formatting integer base prefix type.

• Used with FmtSetInt and operator<<() on String::Format, Stream, or StreamOut

Enumerator
fbpCURRENT	Current prefix (i.e. unspecified/default)
fPREFIX0	No base prefix (default)
fPREFIX1	Single character base prefix (x for hex, o for octal, b for binary)
fPREFIX2	Double character base prefix (0x for hex, 0o for octal, 0b for binary)

FmtPrecision

enum FmtPrecision

Formatting floating point precision type.

• Used with FmtSetFloat and operator<<() on String::Format, Stream, or StreamOut

Enumerator
fpCURRENT	Current floating point precision (i.e. unspecified/default)
fPREC_AUTO	Automatic floating point precision – either normal decimal notation or E notation, whichever is shorter (default)
fPREC0	No floating point precision (whole numbers)
fPREC1	1-digit floating point precision
fPREC2	2-digit floating point precision
fPREC3	3-digit floating point precision
fPREC4	4-digit floating point precision
fPREC5	5-digit floating point precision
fPREC6	6-digit floating point precision

FmtWidth

enum FmtWidth

Formatting field width.

• Used with operator<<() on String::Format or Stream::Format
  • See String Formatting and Stream Formatting

Enumerator
fWIDTH0

IteratorDir

enum IteratorDir

Iterator direction value.

Enumerator
iterNONE	No iterator direction.
iterFW	Forward iterator direction.
iterRV	Reverse iterator direction.

IteratorPos

enum IteratorPos

Iterator position value.

Enumerator
iterFIRST	First item iterator position.
iterLAST	Last item iterator position.
iterEND	End iterator position.

StringSearchAlg

enum StringSearchAlg

String search algorithm selection.

Enumerator
ssaDEFAULT	Default, uses system memmem() if possible (define EVO_NO_MEMMEM to prevent this), otherwise same as ssaKMP.
ssaKMP	Knuth-Morris-Pratt using partial match table.
ssaBASIC	Basic search using memchr() and memcmp()

UtfMode

enum UtfMode

UTF decoding mode used to set how to handle invalid character values.

Enumerator
umINCLUDE_INVALID	Include invalid characters – try to use as-is (dangerous)
umREPLACE_INVALID	Replace invalid characters with UNICODE_REPLACEMENT_CHAR.
umSKIP_INVALID	Skip invalid characters.
umSTRICT	Stop or error on invalid character.

Function Documentation

ascii_breaktype()

CharBreakType evo::ascii_breaktype ( char  ch )

inline

Get ASCII character word-break type.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• This is used to help find a good place to insert a word-break
• This recognizes standard ASCII codes 0-127
• This does not use any locale information

Parameters

ch	Character to check

Returns

Character break type, see CharBreakType

ascii_tolower()

char evo::ascii_tolower ( char  ch )

inline

Convert ASCII character to lowercase.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• This recognizes standard ASCII codes 0-127
• This does not use any locale information

Parameters

ch	Character to check

Returns

Converted character

ascii_toupper()

char evo::ascii_toupper ( char  ch )

inline

Convert ASCII character to uppercase.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• This recognizes standard ASCII codes 0-127
• This does not use any locale information

Parameters

ch	Character to check

Returns

Converted character

ascii_type()

CharType evo::ascii_type ( char  ch )

inline

Get ASCII character type.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• This recognizes standard ASCII codes 0-127
• This does not use any locale information

Parameters

ch	Character to check

Returns

Character type, see CharType

fixed_array_size()

static uint evo::fixed_array_size ( T(&)  [sz] )

static

Get size of fixed-length array.

• Template params and result are inferred from argument type
• This is often used with SubStringMapList
• See also: EVO_FIXED_ARRAY_SIZE()

Example:

#include <evo/type.h>
using namespace evo;

int main() {
    const char* STRLIST[] = {
        "one",
        "two",
        "three"
    };

    const uint size = fixed_array_size(STRLIST);  // set to 3
    return 0;
}

fmt_table()

FmtTableOut<T,FmtTable::CachedWriter> evo::fmt_table ( T &  out, FmtTable &  table, FmtTable::Type  type = FmtTable::tTEXT  )

inline

Create cached FmtTableOut paired with given string/stream to write to.

• Output is cached until either explicitly flushed or the returned object is destroyed
• Caching is used to determine the column widths from row values – this has some overhead so fmt_table_nocache() may be preferred for best performance
• Caution: In some cases flushing to a stream can throw an exception (if enabled) so it's better to flush explicitly with << fFLUSH then to let the destructor flush and possibly throw
• See Additional Formatting

Template Parameters

T	String/Stream type to use, inferred from out argument

Parameters

out	Output string/stream to write to
table	FmtTable instance to use for column information
type	Output type to use – see FmtTable::Type

Returns

FmtTableOut object to use

fmt_table_nocache()

FmtTableOut<T,FmtTable::Writer> evo::fmt_table_nocache ( T &  out, FmtTable &  table, FmtTable::Type  type = FmtTable::tTEXT  )

inline

Create cached FmtTableOut paired with given string/stream to write to.

• Output is written as requested using column information stored in table
• FmtTableAttribs is often used first to update column widths before using this to write output values
• Longer output values will not be aligned correctly if the column information isn't up to date – see FmtTableAttribs
• See Additional Formatting

Template Parameters

T	String/Stream type to use, inferred from out argument

Parameters

out	Output string/stream to write to
table	FmtTable instance to use for column information
type	Output type to use – see FmtTable::Type

Returns

FmtTableOut object to use

lookupsub()

SubString evo::lookupsub ( const TMap &  map, const typename TMap::Key &  key  )

inline

Lookup (find) map value as SubString for given key.

• Useful helper for looking up any string value and converting via SubString
  Example:

  StrMapList map;
  map["key"] = "123";
  Int val = lookupsub(map, "key").num(); // val is null if key not found

Template Parameters

TMap	Evo Map container

Parameters

map	Map to use
key	Key to find

Returns

Found value as SubString, set to null if key not found

See also

stdlookupsub()

map_contains()

bool evo::map_contains ( const T &  map, const typename T::Key &  key, const typename T::Value &  value  )

inline

Check whether map contains key with matching value.

• This requires map value type to implement operator==()

Template Parameters

T	Map type, inferred from arg

Parameters

map	Map to check
key	Key to check
value	Value to check for

Returns

Whether map contains key with matching value

operator!=()

bool evo::operator!= ( const BitArraySubsetT< BitArrayT< T > > &  a, const BitArrayT< T > &  b  )

inline

Inequality operator.

Parameters

a	First subset to compare
b	Second subset to compare

Returns

Whether inequal

operator==()

bool evo::operator== ( const BitArraySubsetT< BitArrayT< T > > &  a, const BitArrayT< T > &  b  )

inline

Equality operator.

Parameters

a	First subset to compare
b	Second subset to compare

Returns

Whether equal

stdlookup()

const TMap::mapped_type* evo::stdlookup ( const TMap &  map, const typename TMap::key_type &  key  )

inline

Lookup (find) STL map value for given key (const).

• Useful for doing STL lookups without messing with STL iterators

Template Parameters

TMap	STL map container

Parameters

map	Map to use
key	Key to find

Returns

Pointer to found value, NULL if not found

See also

stdlookupM(), stdlookupsub()

stdlookupM()

TMap::mapped_type* evo::stdlookupM ( TMap &  map, const typename TMap::key_type &  key  )

inline

Lookup (find) STL map value for given key (mutable).

• Useful for doing STL lookups without messing with STL iterators

Template Parameters

TMap	STL map container

Parameters

map	Map to use
key	Key to find

Returns

Pointer to found value, NULL if not found

See also

stdlookup(), stdlookupsub()

stdlookupsub()

SubString evo::stdlookupsub ( const TMap &  map, const typename TMap::key_type &  key  )

inline

Lookup (find) STL map value as SubString for given key.

• Useful helper for looking up any string value and converting via SubString
  Example:

  std::map<std::string,std::string> map;
  map["key"] = "123";
  Int val = stdlookupsub(map, "key").num(); // val is null if key not found

• Useful for doing STL lookups without messing with STL iterators

Template Parameters

TMap	STL map container

Parameters

map	Map to use
key	Key to find

Returns

Found value as SubString, set to null if key not found

See also

lookupsub(), stdlookup(), stdlookupM()

str_scan_backtickdel()

bool evo::str_scan_backtickdel ( const char *  str, const char *  end  )

inline

Scan string for a Backtick + DEL pair.

• #include <evo/strscan.h>
• A string is invalid text and is not quotable if it contains a backtick + DEL pair, and it contains all other quote types in a way that would confuse a parser
• This is used by StrQuoting::get() methods when falling back to tBACKTICK_DEL::tBACKTICK_DEL
• See Smart Quoting

Parameters

str	String pointer to scan, must not be NULL
end	Pointer to stop scanning, must be >= str

Returns

Whether a backtick + DEL pair was found

str_scan_decimal()

const char* evo::str_scan_decimal ( T &  num, const char *  str, const char *  end  )

inline

Scan string pointer for decimal number and return stop pointer.

• #include <evo/strscan.h>

Parameters

num	Stores parsed number (not reset to 0) [in/out]
str	String pointer to scan, must not be NULL
end	Pointer to stop scanning, must be >= str

Returns

Stop pointer, end if whole string was scanned, NULL if invalid number or too many digits

str_scan_delim() [1/2]

const char* evo::str_scan_delim ( const char *  str, const char *  end, char  delim1, char  delim2  )

inline

Scan string pointer for next delimiter and return stop pointer.

• #include <evo/strscan.h>
• This uses SSE optimization when enabled – see C++ Compilers & Optimization

Parameters

str	String pointer to scan, must not be NULL
end	Pointer to stop scanning, must be >= str
delim1	First delimiter to recognize
delim2	Second delimiter to recognize

Returns

Stop pointer, end if whole string was scanned, otherwise this points to the next delimiter

str_scan_delim() [2/2]

const char* evo::str_scan_delim ( const char *  str, const char *  end, const char *  delims, uint  delim_count  )

inline

Scan string pointer for next delimiter and return stop pointer.

• #include <evo/strscan.h>
• This uses SSE optimization when enabled – see C++ Compilers & Optimization
• Note: SSE optimizations don't apply with delim_count > 16

Parameters

str	String pointer to scan, must not be NULL
end	Pointer to stop scanning, must be >= str
delims	Delimiters to scan for
delim_count	Number of delimiter to scan for, must not be 0

Returns

Stop pointer, end if whole string was scanned, otherwise this points to the next delimiter

str_scan_delim_r() [1/2]

const char* evo::str_scan_delim_r ( const char *  str, const char *  end, char  delim1, char  delim2  )

inline

Scan string pointer for next delimiter in reverse and return new end after stop pointer.

• #include <evo/strscan.h>
• This returns a new end pointer, which points to the character after a delimiter
• This uses SSE optimization when enabled – see C++ Compilers & Optimization

Parameters

str	String pointer to scan, must not be NULL
end	End pointer to stop scanning, must be >= str
delim1	First delimiter to recognize
delim2	Second delimiter to recognize

Returns

New end pointer, str if whole string was scanned, otherwise this points to the next char after a delimiter

str_scan_delim_r() [2/2]

const char* evo::str_scan_delim_r ( const char *  str, const char *  end, const char *  delims, uint  delim_count  )

inline

Scan string pointer for next delimiter in reverse and return new end after stop pointer.

• #include <evo/strscan.h>
• This returns a new end pointer, which points to the character after a delimiter
• This uses SSE optimization when enabled – see C++ Compilers & Optimization
• Note: SSE optimizations don't apply with delim_count > 16

Parameters

str	String pointer to scan, must not be NULL
end	End pointer to stop scanning, must be >= str
delims	Delimiters to scan for
delim_count	Number of delimiter to scan for, must not be 0

Returns

New end pointer, str if whole string was scanned, otherwise this points to the next char after a delimiter

str_scan_endq() [1/4]

const char* evo::str_scan_endq ( const char *&  startq, const char *&  endq, const char *  str, const char *  end  )

inline

Scan string pointer and extract quoted or unquoted text.

• #include <evo/strscan.h>
• This scans for the end of the quoted value and sets out params accordingly
• Caution: This is dangerous if the input wasn't quoted without a delimiter in mind – see StrQuoting::get(const char*,ulong)
  • See also: str_scan_endq(const char*&,const char*&,const char*,const char*,char)
• This supports all the Evo quoting types – see Smart Quoting
• This uses SSE optimization when enabled – see C++ Compilers & Optimization

Parameters

startq	Set to start of quoted text (without quote chars) [out]
endq	Set to end of quoted text (without quote chars) [out]
str	String pointer to scan, must not be null
end	Pointer to stop scanning, must be >= str

Returns

Stop pointer, end if whole string was scanned

str_scan_endq() [2/4]

const char* evo::str_scan_endq ( const char *&  startq, const char *&  endq, const char *  str, const char *  end, char  delim  )

inline

Scan string pointer and extract quoted or unquoted text with a delimiter.

• #include <evo/strscan.h>
• This scans for the end of the quoted value and sets out params accordingly
• The quoted value ends with an end-quote, followed by optional whitespace (space, tab, newlines), followed by a delim or end of input
• This supports all the Evo quoting types – see Smart Quoting
• This uses SSE optimization when enabled – see C++ Compilers & Optimization
• See String::writequoted(), StrQuoting::get(bool&,const char*,ulong,char)

Parameters

startq	Set to start of quoted text (without quote chars), same as str if unquoted [out]
endq	Set to end of quoted text (without quote chars) [out]
str	String pointer to scan, must not be null
end	Pointer to stop scanning, must be >= str
delim	Delimiter that ends the quoted text, may be a whitespace char (space, tab, newline)

Returns

Stop pointer, end if whole string was scanned, otherwise this will point to a delim

str_scan_endq() [3/4]

const char* evo::str_scan_endq ( const char *&  startq, const char *&  endq, const char *  str, const char *  end, char  delim1, char  delim2  )

inline

Scan string pointer and extract quoted or unquoted text with 2 possible delimiters.

• #include <evo/strscan.h>
• This scans for the end of the quoted value and sets out params accordingly
• The quoted value ends with an end-quote, followed by optional whitespace (space, tab, newlines), followed by either delim or end of input
• This supports all the Evo quoting types – see Smart Quoting
• This uses SSE optimization when enabled – see C++ Compilers & Optimization
• See String::writequoted(), StrQuoting::get(bool&,const char*,ulong,char,char)

Parameters

startq	Set to start of quoted text (without quote chars) [out]
endq	Set to end of quoted text (without quote chars) [out]
str	String pointer to scan, must not be null
end	Pointer to stop scanning, must be >= str
delim1	Delimiter that may end the quoted text, must not be a whitespace character (space, tab, newline)
delim2	Another delimiter that may end the quoted text, must not be a whitespace character (space, tab, newline)

Returns

Stop pointer, end if whole string was scanned, otherwise this will point to a delim

str_scan_endq() [4/4]

const char* evo::str_scan_endq ( const char *&  startq, const char *&  endq, const char *  str, const char *  end, const char *  delims, uint  delim_count, char  ws_delim = 0  )

inline

Scan string pointer and extract quoted or unquoted text with multiple possible delimiters.

• #include <evo/strscan.h>
• This scans for the end of the quoted value and sets out params accordingly
• The quoted value ends with an end-quote, followed by optional whitespace (space, tab, newlines), followed by either a delim or end of input
• This supports all the Evo quoting types – see Smart Quoting
• This uses SSE optimization when enabled – see C++ Compilers & Optimization
• Note: SSE optimizations don't apply with delim_count > 16
• See String::writequoted(), StrQuoting::get(bool&,const char*,ulong,char,char)

Parameters

startq	Set to start of quoted text (without quote chars) [out]
endq	Set to end of quoted text (without quote chars) [out]
str	String pointer to scan, must not be null
end	Pointer to stop scanning, must be >= str
delims	Delimiters that may end the quoted text, if this contains a whitespace char (space, tab, newline) then ws_delim must be set too – more than 1 whitespace delimiter is not supported
delim_count	Number of delimiters in delims, must be greater than 0
ws_delim	Use to specify a whitespace delimiter in delims, 0 if no whitespace delim – this is used to handle whitespace correctly between an end-quote and a delimiter

Returns

Stop pointer, end if whole string was scanned, otherwise this will point to a delim

str_scan_endq_r() [1/2]

const char* evo::str_scan_endq_r ( const char *&  startq, const char *&  endq, const char *  str, const char *  end, char  delim  )

inline

Scan string pointer in reverse and extract quoted or unquoted text with a delimiter and return new end after stop pointer.

• #include <evo/strscan.h>
• This scans in reverse (i.e. right to left):
  • This scans for the beginning of the quoted value and sets out params accordingly
  • The quoted value begins with an end-quote, preceded by optional whitespace (space, tab, newlines), preceded by a delim or end of input
  • This returns a new end pointer, which points to the character after a delimiter
• This supports all the Evo quoting types – see Smart Quoting
• This uses SSE optimization when enabled – see C++ Compilers & Optimization
• See String::writequoted(), StrQuoting::get(bool&,const char*,ulong,char)

Parameters

startq	Set to start of quoted text (without quote chars) [out]
endq	Set to end of quoted text (without quote chars), same as end if unquoted [out]
str	String beginning pointer to stop scan, must not be null
end	End pointer to start scanning in reverse, must be >= str
delim	Delimiter that ends the quoted text, may be a whitespace char (space, tab, newline)

Returns

New end pointer, str if whole string was scanned, otherwise this points to the next char after a delimiter

str_scan_endq_r() [2/2]

const char* evo::str_scan_endq_r ( const char *&  startq, const char *&  endq, const char *  str, const char *  end, const char *  delims, uint  delim_count, char  ws_delim = 0  )

inline

Scan string pointer in reverse and extract quoted or unquoted text with multiple possible delimiters and return new end after stop pointer.

• #include <evo/strscan.h>
• This scans in reverse (i.e. right to left):
  • This scans for the beginning of the quoted value and sets out params accordingly
  • The quoted value begins with an end-quote, preceded by optional whitespace (space, tab, newlines), preceded by a delim or end of input
  • This returns a new end pointer, which points to the character after a delimiter
• This supports all the Evo quoting types – see Smart Quoting
• This uses SSE optimization when enabled – see C++ Compilers & Optimization
• Note: SSE optimizations don't apply with delim_count > 16
• See String::writequoted(), StrQuoting::get(bool&,const char*,ulong,char)

Parameters

startq	Set to start of quoted text (without quote chars) [out]
endq	Set to end of quoted text (without quote chars), same as end if unquoted [out]
str	String beginning pointer to stop scan, must not be null
end	End pointer to start scanning in reverse, must be >= str
delims	Delimiters that may end the quoted text, if this contains a whitespace char (space, tab, newline) then ws_delim must be set too – more than 1 whitespace delimiter is not supported
delim_count	Number of delimiters in delims, must be greater than 0
ws_delim	Use to specify a whitespace delimiter in delims, 0 if no whitespace delim – this is used to handle whitespace correctly between an end-quote and a delimiter

Returns

New end pointer, str if whole string was scanned, otherwise this points to the next char after a delimiter

str_scan_hex()

const char* evo::str_scan_hex ( T &  num, const char *  str, const char *  end  )

inline

Scan string pointer for hex number and return stop pointer.

• #include <evo/strscan.h>

Parameters

num	Stores parsed number (not reset to 0) [in/out]
str	String pointer to scan, must not be NULL
end	Pointer to stop scanning, must be >= str

Returns

Stop pointer, end if whole string was scanned, NULL if invalid number or too many digits

str_scan_ndelim()

const char* evo::str_scan_ndelim ( const char *  str, const char *  end, char  delim1, char  delim2  )

inline

Scan string pointer for next non-delimiter and return stop pointer.

• #include <evo/strscan.h>
• This uses SSE optimization when enabled – see C++ Compilers & Optimization

Parameters

str	String pointer to scan, must not be NULL
end	Pointer to stop scanning, must be >= str
delim1	First delimiter to recognize
delim2	Second delimiter to recognize

Returns

Stop pointer, end if whole string was scanned, otherwise this points to the next non-delimiter character

str_scan_ndelim_r()

const char* evo::str_scan_ndelim_r ( const char *  str, const char *  end, char  delim1, char  delim2  )

inline

Scan string pointer for next non-delimiter in reverse and return new end after stop pointer.

• #include <evo/strscan.h>
• This returns a new end pointer, which points to the character after a non-delimiter
• This uses SSE optimization when enabled – see C++ Compilers & Optimization

Parameters

str	String pointer to scan, must not be NULL
end	End pointer to stop scanning, must be >= str
delim1	First delimiter to recognize
delim2	Second delimiter to recognize

Returns

New end pointer, str if whole string was scanned, otherwise this points to the next char after a non-delimiter

str_scan_nws() [1/2]

const char* evo::str_scan_nws ( const char *  str, const char *  end  )

inline

Scan string pointer for next non-whitespace character and return stop pointer.

• #include <evo/strscan.h>
• This uses SSE optimization when enabled – see C++ Compilers & Optimization

Parameters

str	String pointer to scan, must not be NULL
end	Pointer to stop scanning, must be >= str

Returns

Stop pointer, end if whole string was scanned, otherwise this points to the next non-whitespace character

str_scan_nws() [2/2]

const char* evo::str_scan_nws ( const char *  str, const char *  end, char  delim  )

inline

Scan string pointer for next delimiter or non-whitespace character and return stop pointer.

• #include <evo/strscan.h>
• This is similar to str_scan_nws(const char*,const char*) but also works when delim is itself a whitespace character
• This uses SSE optimization when enabled – see C++ Compilers & Optimization

Parameters

str	String pointer to scan, must not be NULL
end	Pointer to stop scanning, must be >= str
delim	Delimiter to stop at, which may be a whitespace character

Returns

Stop pointer, end if whole string was scanned, otherwise this points to the next non-whitespace character

str_scan_nws_r() [1/2]

const char* evo::str_scan_nws_r ( const char *  str, const char *  end  )

inline

Scan string pointer for next non-whitespace character in reverse and return new end after stop pointer.

• #include <evo/strscan.h>
• This returns a new end pointer, which points to the character after a non-whitespace
• This uses SSE optimization when enabled – see C++ Compilers & Optimization

Parameters

str	String pointer to scan, must not be NULL
end	End pointer to stop scanning, must be >= str

Returns

New end pointer, str if whole string was scanned, otherwise this points to the next char after a non-whitespace character

str_scan_nws_r() [2/2]

const char* evo::str_scan_nws_r ( const char *  str, const char *  end, char  delim  )

inline

Scan string pointer for next delimiter or non-whitespace character and return stop pointer.

• #include <evo/strscan.h>
• This is similar to str_scan_nws(const char*,const char*) but also works when delim is itself a whitespace character
• This uses SSE optimization when enabled – see C++ Compilers & Optimization

Parameters

str	String pointer to scan, must not be NULL
end	Pointer to stop scanning, must be >= str
delim	Delimiter to stop at, which may be a whitespace character

Returns

Stop pointer, end if whole string was scanned, otherwise this points to the next non-whitespace character

str_scan_to() [1/2]

const char* evo::str_scan_to ( uint  maxlen, const char *  str, const char *  end, char  ch  )

inline

Scan string pointer for char and return stop pointer.

• #include <evo/strscan.h>

Parameters

maxlen	Max allowed length to scan before returning an error, ignored if 0
str	String pointer to scan, must not be NULL
end	Pointer to stop scanning, must be >= str
ch	Char to scan for

Returns

Stop pointer, end if whole string was scanned, NULL if maxlen exceeded and ch not found within maxlen

str_scan_to() [2/2]

const char* evo::str_scan_to ( uint  maxlen, const char *  str, const char *  end, char  ch1, char  ch2  )

inline

Scan string pointer for either of 2 chars and return stop pointer.

• #include <evo/strscan.h>
• This uses SSE optimization when enabled – see C++ Compilers & Optimization

Parameters

maxlen	Max allowed length to scan before returning an error, ignored if 0
str	String pointer to scan, must not be NULL
end	Pointer to stop scanning, must be >= str
ch1	First char to scan for
ch2	Second char to scan for

Returns

Stop pointer, end if whole string was scanned, NULL if maxlen exceeded

string_memrchr()

const char* evo::string_memrchr ( const char *  str, char  ch, size_t  size  )

inline

Evo implementation of memrchr() to search for character in reverse.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• This searches for a character in reverse and returns a pointer to it, or NULL if not found
• This calls memrchr() (GNU C extension) when possible, otherwise this falls back to an equivalent implementation

Parameters

str	String pointer to search
ch	Character to search for
size	String size to search, search starts at the end

Returns

Pointer to last occurence of ch, NULL if not found

utf16_compare() [1/3]

int evo::utf16_compare ( const wchar16 *  str1, ulong  len1, const wchar16 *  str2, ulong  len2  )

inline

Compare two non-terminated UTF-16 strings.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• See also terminated variants: utf16_compare(const wchar16*,ulong,const wchar16*), utf16_compare(const wchar16*,const wchar16*)

Parameters

str1	First string to compare, must not be NULL
len1	First string length
str2	Second string to compare, must not be NULL
len2	Second string length

Returns

Result (<0 if this is less, 0 if equal, >0 if this is greater)

utf16_compare() [2/3]

int evo::utf16_compare ( const wchar16 *  str1, ulong  len1, const wchar16 *  str2  )

inline

Compare a non-terminated UTF-16 string with a terminated UTF-16 string.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• See also non-terminated variant: utf16_compare(const wchar16*,ulong,const wchar16*,ulong)

Parameters

str1	First string to compare, must not be NULL
len1	First string length
str2	Second string to compare, must be terminated, must not be NULL

Returns

Result (<0 if this is less, 0 if equal, >0 if this is greater)

utf16_compare() [3/3]

int evo::utf16_compare ( const wchar16 *  str1, const wchar16 *  str2  )

inline

Compare two terminated UTF-16 strings.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• See also non-terminated variant: utf16_compare(const wchar16*,ulong,const wchar16*,ulong)

Parameters

str1	First string to compare, must be terminated, must not be NULL
str2	Second string to compare, must be terminated, must not be NULL

Returns

Result (<0 if this is less, 0 if equal, >0 if this is greater)

utf16_compare8() [1/3]

int evo::utf16_compare8 ( const wchar16 *  str1, ulong  len1, const char *  str2, ulong  len2  )

inline

Compare a non-terminated UTF-16 string to a non-terminated UTF-8 string.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• See also terminated variants: utf16_compare(const wchar16*,ulong,const char*), utf16_compare(const wchar16*,const char*)

Parameters

str1	First string to compare, must not be NULL
len1	First string length
str2	Second string to compare, must not be NULL
len2	Second string length

Returns

Result (<0 if this is less, 0 if equal, >0 if this is greater)

utf16_compare8() [2/3]

int evo::utf16_compare8 ( const wchar16 *  str1, ulong  len1, const char *  str2  )

inline

Compare a non-terminated UTF-16 string to a terminated UTF-8 string.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• See also non-terminated and terminated variants: utf16_compare(const wchar16*,ulong,const char*,ulong), utf16_compare(const wchar16*,const char*)

Parameters

str1	First string to compare, must not be NULL
len1	First string length
str2	Second string to compare, must be terminated, must not be NULL

Returns

Result (<0 if this is less, 0 if equal, >0 if this is greater)

utf16_compare8() [3/3]

int evo::utf16_compare8 ( const wchar16 *  str1, const char *  str2  )

inline

Compare a terminated UTF-16 string to a terminated UTF-8 string.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• See also non-terminated variants: utf16_compare(const wchar16*,ulong,const char*,ulong), utf16_compare(const wchar16*,ulong,const char*)

Parameters

str1	First string to compare, must be terminated, must not be NULL
str2	Second string to compare, must be terminated, must not be NULL

Returns

Result (<0 if this is less, 0 if equal, >0 if this is greater)

utf16_count()

ulong evo::utf16_count ( const wchar16 *  str, const wchar16 *  end, UtfMode  mode = umREPLACE_INVALID  )

inline

Count Unicode character values in UTF-16 string.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• Each UTF-16 character may span 1 or 2 16-bit values (2 or 4 bytes), depending on the character
  • 2 byte values are the raw Unicode 16-bit code value
  • 4 byte values are pairs of reserved 16-bit values called surrogate pairs

Parameters

str	Pointer to string to scan, must not be NULL
end	Pointer to end of string to scan, must be >= str
mode	How to handle invalid UTF-16 values: umINCLUDE_INVALID - Invalid UTF-16 values are counted as 1 character each umREPLACE_INVALID - Invalid UTF-16 values are counted as 1 character each (UNICODE_REPLACEMENT_CHAR) umSKIP_INVALID - Invalid UTF-16 values are skipped and not counted umSTRICT - Stop counting on invalid UTF-16 value and return an error

Returns

Number of Unicode characters counted, NONE on error (if mode=umSTRICT)

utf16_min()

const wchar16* evo::utf16_min ( const wchar16 *  str, const wchar16 *  end, bool  strict = false, uint  mincount = 1  )

inline

Scan for UTF-16 surrogate pairs, which each require a pair of wchar16 values (4 bytes).

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• Surrogate pairs are used for Unicode code points 0x10000 to 0x10FFFF, which are less common
• Valid UTF-16 without surrogate pairs is also valid UCS-2 (a precursor to UTF-16)

Parameters

str	Pointer to string to search, must not be NULL
end	Pointer to end of string to scan, must be >= str
strict	Whether to stop counting on invalid UTF-16 value, false to skip/ignore invalid UTF-16 values
mincount	Minimum number of surrogate pairs to look for, must be positive

Returns

Pointer to UTF-16 character that met mincount, NULL if less than mincount surrogate pairs found

utf16_scan()

const wchar16* evo::utf16_scan ( wchar32 &  code, const wchar16 *  str, const wchar16 *  end, UtfMode  mode = umREPLACE_INVALID  )

inline

Scan for next Unicode character in UTF-16 string.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• A UTF-16 character may span 1 or 2 16-bit values (2 or 4 bytes), depending on the character
  • 2 byte values are the raw Unicode 16-bit code value
  • 4 byte values are pairs of reserved 16-bit values called surrogate pairs
• Call this in a loop to iterate through Unicode characters in a UTF-16 string, stop when NULL is returned

Parameters

code	Set to full Unicode character code scanned, or error code on error (see return value) [out]
str	Pointer to string to scan, must not be ULL
end	Pointer to end of string to scan
mode	How to handle invalid UTF-16 values: umINCLUDE_INVALID - Invalid UTF-16 values are each returned as-is (1 character each) umREPLACE_INVALID - Invalid UTF-16 bytes are each replaced with UNICODE_REPLACEMENT_CHAR umSKIP_INVALID - Invalid UTF-16 values are skipped (ignored) umSTRICT - Stop with error on invalid UTF-16 value, return NULL and set code=1

Returns

Pointer after scanned Unicode character, NULL with code=0 if stopped at end of string, NULL with code=1 on error (if mode=umSTRICT)

utf16_scan_term()

const wchar16* evo::utf16_scan_term ( wchar32 &  code, const wchar16 *  str, UtfMode  mode = umREPLACE_INVALID  )

inline

Scan for next Unicode character in terminated UTF-16 string.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• A UTF-16 character may span 1 or 2 16-bit values (2 or 4 bytes), depending on the character
  • 2 byte values are the raw Unicode 16-bit code value
  • 4 byte values are pairs of reserved 16-bit values called surrogate pairs
• Call this in a loop to iterate through Unicode characters in a terminated UTF-16 string, stop when NULL is returned

Parameters

code	Set to full Unicode character code scanned, or error code on error (see return value) [out]
str	Pointer to string to scan, muts be terminated, must not be ULL
mode	How to handle invalid UTF-16 values: umINCLUDE_INVALID - Invalid UTF-16 values are each returned as-is (1 character each) umREPLACE_INVALID - Invalid UTF-16 bytes are each replaced with UNICODE_REPLACEMENT_CHAR umSKIP_INVALID - Invalid UTF-16 values are skipped (ignored) umSTRICT - Stop with error on invalid UTF-16 value, return NULL and set code=1

Returns

Pointer after scanned Unicode character, NULL with code=0 if stopped at end of string, NULL with code=1 on error (if mode=umSTRICT)

utf16_strlen()

ulong evo::utf16_strlen ( const wchar16 *  str )

inline

Find terminated UTF-16 string length.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>

Parameters

str	Pointer to string, must be NULL terminated, NULL for none

Returns

String length in UTF-16 values (not bytes), 0 if str=NULL

utf16_to8()

ulong evo::utf16_to8 ( const wchar16 *&  str, const wchar16 *  end, char *  outbuf = NULL, ulong  outsize = 0, UtfMode  mode = umREPLACE_INVALID  )

inline

Convert UTF-16 string to UTF-8 string.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>

Parameters

str	Pointer to input UTF-16 string to convert, set to stopping point on return, must not be NULL [in/out]
end	Pointer to stop input at (end of input, exclusive), must be >= str
outbuf	Output buffer to write UTF-8 string to, NULL to scan without writing
outsize	Output buffer size in bytes, ignored if outbuf=NULL
mode	How to handle invalid UTF-16 values: umINCLUDE_INVALID - Invalid UTF-16 values are converted as-is (1 character each) umREPLACE_INVALID - Invalid UTF-16 values are each replaced with UNICODE_REPLACEMENT_CHAR umSKIP_INVALID - Invalid UTF-16 values are skipped and ignored umSTRICT - Stop on invalid input with an error

Returns

Count written to outbuf in bytes, END on invalid input (if mode=umSTRICT)

utf8_compare() [1/3]

int evo::utf8_compare ( const char *  str1, ulong  len1, const char *  str2, ulong  len2  )

inline

Compare two non-terminated UTF-8 strings.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• See also terminated variants: utf8_compare(const char*,ulong,const char*), utf16_compare(const char*,const char*)

Parameters

str1	First string to compare, can be NULL
len1	First string length
str2	Second string to compare, can be NULL
len2	Second string length

Returns

Result (<0 if this is less, 0 if equal, >0 if this is greater)

utf8_compare() [2/3]

int evo::utf8_compare ( const char *  str1, ulong  len1, const char *  str2  )

inline

Compare non-terminated and terminated UTF-8 strings.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• See also non-terminated and terminated variants: utf8_compare(const char*,ulong,const char*,ulong), utf16_compare(const char*,const char*)

Parameters

str1	First string to compare, can be NULL
len1	First string length
str2	Second string to compare, must be terminated, can be NULL

Returns

Result (<0 if this is less, 0 if equal, >0 if this is greater)

utf8_compare() [3/3]

int evo::utf8_compare ( const char *  str1, const char *  str2  )

inline

Compare two terminated UTF-8 strings.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• See also non-terminated variants: utf8_compare(const char*,ulong,const char*,ulong), utf16_compare(const char*,ulong,const char*)

Parameters

str1	First string to compare, must be terminated, can be NULL
str2	Second string to compare, must be terminated, can be NULL

Returns

Result (<0 if this is less, 0 if equal, >0 if this is greater)

utf8_count()

ulong evo::utf8_count ( const char *  str, const char *  end, UtfMode  mode = umREPLACE_INVALID  )

inline

Count Unicode character values in UTF-8 string.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• Each UTF-8 character may span 1-4 bytes, depending on the character

Parameters

str	Pointer to string to scan, must not be NULL
end	Pointer to end of string to scan, must be >= str
mode	How to handle invalid UTF-8 bytes: umINCLUDE_INVALID - Invalid UTF-8 values are counted as 1 character each umREPLACE_INVALID - Invalid UTF-8 values are counted as 1 character each (UNICODE_REPLACEMENT_CHAR) umSKIP_INVALID - Invalid UTF-8 values are skipped and not counted umSTRICT - Stop counting on an invalid UTF-8 value and return an error

Returns

Number of Unicode characters counted, NONE on error (if mode=umSTRICT)

utf8_min()

const char* evo::utf8_min ( const char *  str, const char *  end, bool  strict = false, ulong  mincount = 1, uint  minsize = 2  )

inline

Scan for UTF-8 multi-byte characters of at least minsize.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• Multi-byte characters are used for higher Unicode code points
• Valid UTF-8 single-byte characters are also valid ASCII characters
• Use minsize to set the multi-byte characters to stop at – character sizes smaller than this are ignored

Parameters

str	Pointer to string to search, must not be NULL
end	Pointer to end of string to scan, must be >= str
strict	Whether to stop counting on invalid UTF-8 byte, false to skip/ignore invalid UTF-8 bytes
mincount	Minimum number of multi-byte values to look for, must be positive
minsize	Minimum number of bytes to count as multi-byte value, must be 2-4 (inclusive)

Returns

Pointer to UTF-8 character that met mincount, NULL if not enough multi-byte values found

utf8_scan()

const char* evo::utf8_scan ( wchar32 &  code, const char *  str, const char *  end, UtfMode  mode = umREPLACE_INVALID  )

inline

Scan for next Unicode character in UTF-8 string.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• Each UTF-8 character may span 1-4 bytes, depending on the character
• Call this in a loop to iterate through Unicode characters in a UTF-8 string, stop when NULL is returned

Parameters

code	Set to full Unicode character code scanned, or error code on error (see return value) [out]
str	Pointer to string to scan, must not be NULL
end	Pointer to end of string to scan, must be >= str
mode	How to handle invalid UTF-8 bytes: umINCLUDE_INVALID - Invalid UTF-8 bytes are each used as-is (1 byte each) umREPLACE_INVALID - Invalid UTF-8 bytes are each replaced with UNICODE_REPLACEMENT_CHAR umSKIP_INVALID - Invalid UTF-8 values are skipped (ignored) umSTRICT - Stop with error on invalid UTF-8 value, return NULL and set code=1

Returns

Pointer after scanned Unicode character, NULL with code=0 if stopped at end of string, NULL with code=1 on error (if mode=umSTRICT)

utf8_scan_term()

const char* evo::utf8_scan_term ( wchar32 &  code, const char *  str, UtfMode  mode = umREPLACE_INVALID  )

inline

Scan for next Unicode character in terminated UTF-8 string.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>
• Each UTF-8 character may span 1-4 bytes, depending on the character
• Call this in a loop to iterate through Unicode characters in a UTF-8 string, stop when NULL is returned

Parameters

code	Set to full Unicode character code scanned, or error code on error (see return value) [out]
str	Pointer to string to scan, must be terminated, must not be NULL
mode	How to handle invalid UTF-8 bytes: umINCLUDE_INVALID - Invalid UTF-8 bytes are each used as-is (1 byte each) umREPLACE_INVALID - Invalid UTF-8 bytes are each replaced with UNICODE_REPLACEMENT_CHAR umSKIP_INVALID - Invalid UTF-8 values are skipped (ignored) umSTRICT - Stop with error on invalid UTF-8 value, return NULL and set code=1

Returns

Pointer after scanned Unicode character, NULL with code=0 if stopped at end of string, NULL with code=1 on error (if mode=umSTRICT)

utf8_to16()

ulong evo::utf8_to16 ( const char *&  str, const char *  end, wchar16 *  outbuf = NULL, ulong  outsize = 0, UtfMode  mode = umREPLACE_INVALID  )

inline

Convert UTF-8 string to UTF-16 string.

• #include <evo/strscan.h> or <evo/string.h> or <evo/substring.h>

  Parameters

  str	Pointer to input UTF-8 string to convert, set to stopping point on return, must not be NULL [in/out]
  end	Pointer to stop input at (end of input, exclusive)
  outbuf	Output buffer to write UTF-16 string to, NULL to scan without writing
  outsize	Output buffer size as wchar16 count (not bytes), ignored if outbuf=NULL
  mode	How to handle invalid UTF-8 bytes and values that convert to reserved UTF-16 surrogate values: umINCLUDE_INVALID - Invalid UTF-8 bytes are still converted, but invalid UTF-16 surrogate values that can't be represented are skipped umREPLACE_INVALID - Invalid UTF-8 bytes are each replaced with UNICODE_REPLACEMENT_CHAR umSKIP_INVALID - Invalid input is skipped and ignored umSTRICT - Stop on invalid input with an error

  Returns

  Count written to outbuf as wchar16 count (not bytes), END on invalid input (if mode=umSTRICT)

Variable Documentation

UNICODE_REPLACEMENT_CHAR

const wchar16 UNICODE_REPLACEMENT_CHAR = 0xFFFD

static

Unicode code point for "Replacement Character" used when decoding invalid UTF bytes or values.

• This character often shows as a question mark in a box
• Unicode code point: FFFD
• UTF-8: Encoded with 3 bytes as 0xEF 0xBF 0xBD
• UTF-16 & UTF-32: Encoded directly as 0xFFFD