String Class Reference

#include <evo/string.h>

Inheritance diagram for String:

Detailed Description

String container.

Features

• Similar to STL std::string
• Built-in formatting support – see operator<<()
  • Appending/prepending/inserting a string (or SubString or pointer) into itself is supported
• Built-in conversions – see num(), numu(), numf(), boolval()
• Searching and splitting with split() and find() methods
• Not always terminated, call cstr() for terminated string

• Preallocates extra memory when buffer grows – see capacity(), resize(), capacity(Size)
• No memory allocated by new empty string
• Inherits efficiency from List

• Sharing and Slicing make for simple and efficient string parsing
• Caution: Setting from a raw pointer will use Unsafe Pointer Referencing
• See also: SubString, StrTok, UnicodeString

C++11:

• Range-based for loop – see STL Compatibility

  String str;
  for (auto ch : str.asconst()) {
  }

• Initialization lists

  String str = {'a', 'b', 'c'};

• Move semantics
• UTF-16 string literal, see UnicodeString

  String str = u"Hello"; // converts from UTF-16 literal to UTF-8

Iterators

• String::Iter – Read-Only Iterator (IteratorRa)
• String::IterM – Mutable Iterator (IteratorRa)

Constructors

• String()
• String(const String&), ...
• String(const StringBase&,Key,Key)
• String(const char*,Size)
• String(const PtrBase<char>&,Size)
• String(const char*)
• String(const PtrBase<char>&)
• String(const char16_t*,Size,UtfMode) [C++11]
• String(const char16_t*,UtfMode) [C++11]
• String(const std::initializer_list<char>&) [C++11]
• String(String&&) [C++11]

Read Access

• asconst()
• size()
  • null(), empty()
  • capacity()
  • shared()
• cstr(String&) const
• data()
  • item()
  • operator[]()
  • first(), last(), iend()
  • hash()

• split(C&,char) const
• split(char,T1&,T2&) const
  • split(char,T1&) const
  • split(char,ValNull,T2&) const
• splitr(char,T1&,T2&) const
  • splitr(char,T1&) const
  • splitr(char,ValNull,T2&) const
• splitat(Key,T1&,T2&) const
  • splitat(Key,T1&) const
  • splitat(Key,ValNull,T2&) const
• cbegin(), cend()
  • begin() const, end() const
• find(char,Key,Key) const, ...
  • find(const char*,uint,Key,Key) const, ...
  • find(const StringBase&,Key,Key) const, ...
• findr(char,Key,Key) const, ...
  • findr(const char*,uint,Key,Key) const, ...
  • findr(const StringBase&,Key,Key) const, ...
• findany(), findanyr()
  • findanybut(), findanybutr()
• findword(), findwordr()
  • findnonword(), findnonwordr()
• contains(char) const
  • contains(const char*,Size) const
  • contains(const StringBase&) const

• compare(const StringBase&) const, ...
  • operator==(const String&) const, ...
  • operator==(const char*) const
  • operator!=(const String& data) const, ...
  • operator!=(const char*) const
• starts(char) const
  • starts(const char*,Size) const
• ends(char) const
  • ends(const char*,Size) const

• convert()
  • splitmap()
  • toupper(), tolower()
• boolval()
  • getbool() const, getbool(Error&) const
• num(int) const
  • numl(int) const, numll(int) const
  • numu(int) const, numul(int) const, numull(int) const
  • getnum(int) const, getnum(Error&,int) const
• numf()
  • numfd(), numfl()
  • getnumf() const, getnumf(Error&) const

Slicing

• token(), tokenr()
  • token_any(), tokenr_any()
  • token_line(), tokenr_line()
• slice(Key)
  • slice(Key,Size), slice2()
• truncate()
  • triml(), trimr()
• strip()
  • strip(char)
  • stripl(), stripr()
  • stripl(char,Size), stripr(char,Size)
  • stripl(const char*,Size,Size), stripr(const char*,Size,Size)
  • stripl_newlines(), stripr_newlines()
• strip2()
  • stripl2()
  • stripr2()
• strip_newlines()
  • stripl_newlines(), stripl_newlines(Size)
  • stripr_newlines(), stripr_newlines(Size)
• pop(), popq()
• unslice()

Modifiers

• cstr()
• dataM()
  • itemM()
  • operator()()
• begin(), end()
• resize()
  • reserve()
  • capacity(Size)
  • capacitymin(), capacitymax()
  • unshare()
• set()
  • set(const ListType&)
  • set(const StringBase&,Key,Key)
  • set(const char*,Size)
  • set(const PtrBase<char>&,Size)
  • set(const char*)
  • set(const PtrBase<char>&)
  • set2(const StringBase&,Key,Key), ...
  • setn(int,int), setn(uint,int), setn(float,int), ...
  • set_unicode(const wchar16*,Size,UtfMode)
    • set_unicode(const wchar16*,UtfMode)
    • set_unicode(const char16_t*,Size,UtfMode) [C++11]
    • set_unicode(const char16_t*,UtfMode) [C++11]
  • setempty()
  • clear()
  • operator=(const String&), ...
  • operator=(const StringBase&)
  • operator=(String&&) [C++11]
  • operator=(const char16_t*) [C++11]
  • operator=(const char*)
  • operator=(const PtrBase<char>&)
  • operator=(const ValNull&)
  • operator=(const ValEmpty&)
• copy(const ListType&)
  • copy(const StringBase&)
  • copy(const char*,Size)
  • copy(const char*)
• convert_set()
  • convert_add()
  • join()
• add(char)
  • add(char,Size)
  • add(const ListType&), ...
  • add(const char*,Size)
  • add(const char*)
  • addsep()
  • addn(int,int), addn(uint,int), addn(float,int), ...
  • operator<<(bool)
  • operator<<(char)
  • operator<<(const ListType&), ...
  • operator<<(const char*)
  • operator<<(const ValNull&)
  • operator<<(const ValEmpty&)
  • operator<<(const FmtChar&), operator<<(const FmtString&), operator<<(const FmtStringWrap&)
  • operator<<(int), operator<<(uint), operator<<(float), ...
  • operator<<(const FmtInt&), operator<<(const FmtUInt&), operator<<(const FmtFloat&), ...
• prepend(char)
  • prepend(char,Size)
  • prepend(const ListType&), ...
  • prepend(const char*,Size)
  • prepend(const char*)
  • prependsep()
  • prependn(int,int), prependn(uint,int), prependn(float,int), ...
• insert(Key,char)
  • insert(Key,char,Size)
  • insert(Key,const ListType&), ...
  • insert(Key,const char*,Size)
  • insert(Key,const char*)
  • insertn(Key,int,int), insertn(Key,uint,int), insertn(Key,float,int), ...
• replace(Key,Size,const StringBase&)
  • replace(Key,Size,const char*,Size)
  • replace(Key,Size,const char*)
  • fillch()
• findreplace(char,const char*,Size,Size)
  • findreplace(char,const StringBase&,Size)
• findreplace(const char*,Size,const char*,Size,Size)
  • findreplace(const char*,Size,const StringBase&,Size)
  • findreplace(const StringBase&,const StringBase&,Size)
  • findreplace(const char*,Size,const StringBase&,Size)
• remove()
• pop(char&)
  • pop(char&,Key)
  • popq(char&)
• swap()
• reverse()

Helpers

• digits()
• letters()
  • lettersu()
  • lettersl()
• whitespace()

Advanced

• advItem(Key)
• advResize()
• advBuffer(Size)
  • advBuffer()
  • advSize()
• advWrite()
  • advWriteDone()
• advEdit()
  • advEditDone()
• advSwap()

Example

#include <evo/string.h>
#include <evo/io.h>
using namespace evo;
static Console& c = con();

int main() {
    // Create string
    String str("test");

    // operator[] provides read-only (const) access
    char value = str[0];
    //str[0] = 0;       // Error: operator[] is read-only

    // operator() provides write (mutable) access
    str(0) = 'T';

    // Iterate and print characters (read-only)
    for (String::Iter iter(str); iter; ++iter)
        c.out << "Ch: " << *iter << NL;

    // Reformat string
    str.clear() << "foo" << ',' << 123;

    // Split string into 2 substrings
    String sub1, sub2;
    str.split(',', sub1, sub2);

    // Print sub1, and sub2 as number (dereference Int to int)
    c.out << "1: " << sub1 << NL
          << "2: " << *sub2.num() << NL;

    // Print sub1 as terminated string (just for example)
    c.out << sub1.cstr() << NL;

    return 0;
}

Output:

Ch: T
Ch: e
Ch: s
Ch: t
1: foo
2: 123
foo

Classes
struct	Format
	String formatter with state. More...

Public Types
typedef void	EvoContainerType
typedef char	Item
	Item type (same as Value) More...
typedef DataCopy< char >::PassType	ItemVal
	Item type as parameter (POD types passed by value, otherwise by const-ref) More...
typedef IteratorRa< ThisType >::Const	Iter
	Iterator (const) - IteratorRa. More...
typedef IteratorRa< ThisType >	IterM
	Iterator (mutable) - IteratorRa. More...
typedef Size	Key
	Key type (item index) More...
typedef ListBase< char, Size >	ListBaseType
	List base type for any Evo list More...
typedef List< char, StrSizeT >	ListType
	List type. More...
typedef String	Out
	Type returned by write_out() More...
typedef StrSizeT	Size
	List size integer type More...
typedef ListBaseType	StringBase
	Alias for ListBaseType. More...
typedef String	ThisType
	This string type. More...
typedef ListBase< wchar16, Size >	UnicodeStringBase
	Base for UnicodeString. More...
typedef char	Value
	Value type (same as Item) More...

Public Member Functions
	String ()
	Default constructor sets as null. More...
	String (const String &str)
	Copy constructor. More...
	String (const ListType &str)
	Copy constructor. More...
	String (const ListType *str)
	Copy constructor. More...
	String (const ListType &str, Key index, Key size=ALL)
	Extended copy constructor. More...
	String (const StringBase &str, Key index=0, Key size=ALL)
	Constructor to copy substring data. More...
	String (const char *str, Size size)
	Constructor for string pointer. More...
	String (const PtrBase< char > &str, Size size)
	Constructor for managed string pointer. More...
	String (const UnicodeStringBase &str)
	Constructor to convert from UTF-16 string to UTF-8 string. More...
	String (const char *str)
	Constructor for null terminated string. More...
	String (const PtrBase< char > &str)
	Constructor to copy null terminated string from managed pointer. More...
	String (const char16_t *str, Size size, UtfMode mode=umREPLACE_INVALID)
	Constructor to initialize and convert from UTF-16 string literal (using u prefix). More...
	String (const char16_t *str, UtfMode mode=umREPLACE_INVALID)
	Constructor to initialize and convert from terminated UTF-16 string literal (using u prefix). More...
	String (const std::initializer_list< char > &init)
	Sequence constructor (C++11). More...
	String (String &&src)
	Move constructor (C++11). More...
ListType &	add (const Item *data, Size size)
	Append new items copied from data pointer (modifier). More...
String &	add (char ch)
	Append character (modifier). More...
String &	add (char ch, Size count)
	Append copies of the same character (modifier). More...
String &	add (const ListType &str)
	Append from another string (modifier). More...
String &	add (const StringBase &str)
	Append from another string (modifier). More...
String &	add (const char *str, Size size)
	Append from string pointer (modifier). More...
String &	add (const char *str)
	Append null terminated string (modifier). More...
ListType &	addmin (Size minsize)
	Append new items up to a given minimum size (modifier). More...
String &	addn (int num, int base=fDEC)
	Append formatted signed number (modifier). More...
String &	addn (long num, int base=fDEC)
	Append formatted signed number (modifier). More...
String &	addn (longl num, int base=fDEC)
	Append formatted signed number (modifier). More...
String &	addn (uint num, int base=fDEC)
	Append formatted unsigned number (modifier). More...
String &	addn (ulong num, int base=fDEC)
	Append formatted unsigned number (modifier). More...
String &	addn (ulongl num, int base=fDEC)
	Append formatted unsigned number (modifier). More...
String &	addn (float num, int precision=fPREC_AUTO)
	Append formatted floating point number (modifier). More...
String &	addn (double num, int precision=fPREC_AUTO)
	Append formatted floating point number (modifier). More...
String &	addn (ldouble num, int precision=fPREC_AUTO)
	Append formatted floating point number (modifier). More...
ListType &	addnew (Size size=1)
	Append new items (modifier). More...
String &	addsep (char delim=',')
	Append separator/delimiter if needed (modifier). More...
void	advAdd (Size size)
	Advanced: Append new items without initializing (constructing) them. More...
char *	advBuffer (Size size)
	Advanced: Resize and get buffer pointer (modifier). More...
char *	advBuffer ()
	Advanced: Get buffer pointer (modifier). More...
bool	advEdit (Edit &edit, Size minsize, bool inplace=true)
	Advanced: Start optimized in-place/buffer edit. More...
void	advEditDone (Edit &edit)
	Advanced: Finish edit started with advEdit() (modifier). More...
char *	advFirst ()
	Advanced: Get first item (modifier). More...
Key	advInsert (Key index, Size size)
	Advanced: Insert new items without initializing (constructing) them. More...
char &	advItem (Key index)
	Advanced: Get item (mutable). More...
char *	advLast ()
	Advanced: Get last item (modifier). More...
void	advPrepend (Size size)
	Advanced: Prepend new items without initializing (constructing) them. More...
void	advRemove (Key index, Size size)
	Advanced: Remove given items without uninitializing (destructing) them. More...
ListType &	advResize (Size size)
	Advanced: Resize while preserving existing data, POD items not initialized (modifier). More...
String &	advResize (Size size)
	Advanced: Resize while preserving existing data, POD items not initialized (modifier). More...
void	advSize (Size size)
	Advanced: Set new size after writing directly to buffer. More...
void	advSwap (Key index1, Key index2)
	Advanced: Swap given items. More...
char *	advWrite (Size addsize)
	Advanced: Get buffer pointer to write/append (modifier). More...
void	advWriteDone (Size addsize)
	Advanced: Update size added after writing directly to buffer. More...
const String &	asconst () const
	Explicitly use a const reference to this. More...
IterM	begin ()
	Get iterator at first item (mutable). More...
Iter	begin () const
	Get iterator at first item (const). More...
Bool	boolval () const
	Convert to bool value. More...
ListType &	capacity (Size size)
	Set new capacity (modifier). More...
Size	capacity () const
	Get capacity. More...
String &	capacity (Size size)
	Set new capacity (modifier). More...
ListType &	capacitymax (Size max)
	Set maximum capacity (modifier). More...
String &	capacitymax (Size max)
	Set maximum capacity (modifier). More...
ListType &	capacitymin (Size min)
	Set minimum capacity (modifier). More...
String &	capacitymin (Size min)
	Set minimum capacity (modifier). More...
Iter	cbegin () const
	Get iterator at first item (const). More...
Iter	cend () const
	Get iterator at end (const). More...
String &	clear ()
	Clear by removing all items. More...
String &	compact ()
	Reduce capacity to fit current size (modifier). More...
int	compare (const ListBaseType &data) const
	Comparison. More...
template<class T >
int	compare (const ListBase< wchar16, T > &str)
	Comparison against UTF-16 string. More...
bool	contains (const Item *data, Size size) const
	Check if contains given data. More...
bool	contains (char ch) const
	Check whether this contains given character. More...
bool	contains (const char *str, Size size) const
	Check whether this contains given string. More...
bool	contains (const StringBase &str) const
	Check whether contains given string. More...
template<class C >
C	convert () const
	Convert string to value of given type. More...
template<class C >
String &	convert_add (C value)
	Convert value to string, appending to current string. More...
template<class C >
bool	convert_addq (C value, char delim=',')
	Convert value to string with quoting as needed, appending to current string. More...
template<class C >
String &	convert_set (C value)
	Convert value to string, replacing current string. More...
ListType &	copy (const Item *data, Size size)
	Set as full (unshared) copy using data pointer (modifier). More...
String &	copy (const ListType &str)
	Set as full (unshared) copy of another string (modifier). More...
String &	copy (const StringBase &str)
	Set as full (unshared) copy of substring (modifier). More...
String &	copy (const char *str, Size size)
	Set as full (unshared) copy using string pointer (modifier). More...
String &	copy (const char *str)
	Set as full (unshared) copy of null terminated string (modifier). More...
const char *	cstr (String &buffer) const
	Get terminated string pointer, using given string buffer if needed (const). More...
const char *	cstr ()
	Get terminated string pointer (modifier). More...
const char *	cstrM () const
	Get terminated string pointer (modifier). More...
const char *	data () const
	Get string pointer (const). More...
char *	dataM ()
	Get data pointer (mutable). More...
bool	empty () const
	Get whether empty. More...
IterM	end ()
	Get iterator at end. More...
Iter	end () const
	Get iterator at end. More...
bool	ends (const Item *items, Size size) const
	Check if this ends with given items. More...
bool	ends (const ListBaseType &items) const
	Check if this ends with given items. More...
bool	ends (char ch) const
	Check if this ends with given character. More...
ListType &	fill (const Item &item, Key index=0, Size size=ALL)
	Fill using item (modifier). More...
String &	fillch (char ch, Key index=0, Size size=ALL)
	Fill with copies of character (modifier). More...
Key	find (ItemVal item, Key start=0, Key end=END) const
	Find first occurrence of item with forward search. More...
Key	find (char ch) const
	Find first occurrence of character with forward search. More...
Key	find (char ch, Key start, Key end=END) const
	Find first occurrence of character with forward search. More...
Key	find (const char *pattern, uint pattern_size, Key start=0, Key end=END) const
	Find first occurrence of pattern string. More...
Key	find (StringSearchAlg alg, const char *pattern, uint pattern_size, Key start=0, Key end=END) const
	Find first occurrence of pattern string using specified algorithm. More...
Key	find (const StringBase &pattern, Key start=0, Key end=END) const
	Find first occurrence of pattern string. More...
Key	find (StringSearchAlg alg, const StringBase &pattern, Key start=0, Key end=END) const
	Find first occurrence of pattern string using specified algorithm. More...
Key	findany (const Item *items, Size count, Key start=0, Key end=END) const
	Find first occurrence of any given items with forward search. More...
Key	findany (const char *chars, Size count, Key start=0, Key end=END) const
	Find first occurrence of any given characters with forward search. More...
Key	findany (const StringBase &chars, Key start=0, Key end=END) const
	Find first occurrence of any given characters with forward search. More...
Key	findanybut (const char *chars, Size count, Key start=0, Key end=END) const
	Find first occurrence of any character not listed with forward search. More...
Key	findanybut (const StringBase &chars, Key start=0, Key end=END) const
	Find first occurrence of any character not listed with forward search. More...
Key	findanybutr (const char *chars, Size count, Key start=0, Key end=END) const
	Find last occurrence of any character not listed with reverse search. More...
Key	findanybutr (const StringBase &chars, Key start=0, Key end=END) const
	Find last occurrence of any character not listed with reverse search. More...
Key	findanyr (const Item *items, Size count, Key start=0, Key end=END) const
	Find last occurrence of any given items with reverse search. More...
Key	findanyr (const char *chars, Size count, Key start=0, Key end=END) const
	Find last occurrence of any given characters with reverse search. More...
Key	findanyr (const StringBase &chars, Key start=0, Key end=END) const
	Find last occurrence of any given characters with reverse search. More...
Key	findnonword (Key start=0, Key end=END) const
	Find first non-word word character. More...
Key	findnonwordr (Key start=0, Key end=END) const
	Find last non-word character with reverse search. More...
Key	findr (ItemVal item, Key start=0, Key end=END) const
	Find last occurrence of item with reverse search. More...
Key	findr (char ch) const
	Find last occurrence of character with reverse search. More...
Key	findr (char ch, Key start, Key end=END) const
	Find last occurrence of character with reverse search. More...
Key	findr (const char *pattern, uint pattern_size, Key start=0, Key end=END) const
	Find last occurrence of pattern string with reverse search. More...
Key	findr (StringSearchAlg alg, const char *pattern, uint pattern_size, Key start=0, Key end=END) const
	Find last occurrence of pattern string with reverse search. More...
Key	findr (const StringBase &pattern, Key start=0, Key end=END) const
	Find last occurrence of pattern string with reverse search. More...
Key	findr (StringSearchAlg alg, const StringBase &pattern, Key start=0, Key end=END) const
	Find last occurrence of pattern string with reverse search. More...
Size	findreplace (char ch, const char *str, Size size, Size max=ALL)
	Find character and replace with string (modifier). More...
Size	findreplace (char ch, const StringBase &str, Size max=ALL)
	Find character and replace with string (modifier). More...
Size	findreplace (const char *fstr, Size fsize, const char *str, Size size, Size max=ALL)
	Find string and replace with string (modifier). More...
Size	findreplace (const char *fstr, Size fsize, const StringBase &str, Size max=ALL)
	Find string and replace with string (modifier). More...
Size	findreplace (const StringBase &fstr, const StringBase &str, Size max=ALL)
	Find string and replace with string (modifier). More...
Size	findreplace (const StringBase &fstr, const char *str, Size size, Size max=ALL)
	Find string and replace with string (modifier). More...
Key	findword (Key start=0, Key end=END) const
	Find first word character. More...
Key	findwordr (Key start=0, Key end=END) const
	Find last word character with reverse search. More...
const Item *	first () const
	Get first item (const). More...
Item *	firstM ()
	Get first item (mutable). More...
bool	getbool (Error &error) const
	Convert to bool value for given boolean type. More...
template<class T >
T	getbool () const
	Convert to bool value for given boolean type. More...
template<class T >
T	getnum (Error &error, int base=0) const
	Convert to number value for given integer type. More...
template<class T >
T	getnum (int base=0) const
	Convert to number value for given integer type. More...
template<class T >
T	getnumf (Error &error) const
	Convert to floating point number value for given type. More...
template<class T >
T	getnumf () const
	Convert to floating point number value for given type. More...
ulong	hash (ulong seed=0) const
	Get data hash value. More...
Key	iend (Size offset=0) const
	Get index from last item using offset. More...
Size	insert (Key index, const Item *data, Size size)
	Insert new items copied from data pointer (modifier). More...
Size	insert (Key index, const ListBaseType &data)
	Insert new items copied from another list (modifier). More...
Size	insert (Key index, const Item &data)
	Insert new item (modifier). More...
Size	insert (Key index, char ch)
	Insert character (modifier). More...
Size	insert (Key index, char ch, Size count)
	Insert copies of the same character (modifier). More...
Size	insert (Key index, const ListType &str)
	Insert from another string (modifier). More...
Size	insert (Key index, const StringBase &str)
	Insert from another string (modifier). More...
Size	insert (Key index, const char *str, Size size)
	Insert string data (modifier). More...
String &	insert (Key index, const char *str)
	Insert null terminated string (modifier). More...
String &	insertn (Key index, int num, int base=fDEC)
	Insert formatted signed number (modifier). More...
String &	insertn (Key index, long num, int base=fDEC)
	Insert formatted signed number (modifier). More...
String &	insertn (Key index, longl num, int base=fDEC)
	Insert formatted signed number (modifier). More...
String &	insertn (Key index, uint num, int base=fDEC)
	Insert formatted unsigned number (modifier). More...
String &	insertn (Key index, ulong num, int base=fDEC)
	Insert formatted unsigned number (modifier). More...
String &	insertn (Key index, ulongl num, int base=fDEC)
	Insert formatted unsigned number (modifier). More...
String &	insertn (Key index, float num, int precision=fPREC_AUTO)
	Insert formatted floating point number (modifier). More...
String &	insertn (Key index, double num, int precision=fPREC_AUTO)
	Insert formatted floating point number (modifier). More...
String &	insertn (Key index, ldouble num, int precision=fPREC_AUTO)
	Insert formatted floating point number (modifier). More...
Size	insertnew (Key index, Size size=1)
	Insert new items (modifier). More...
const Item &	item (Key index) const
	Get item at position (const). More...
char &	itemM (Key index)
	Get item at position (mutable). More...
template<class C >
String &	join (const C &items, char delim=',')
	Join list items into delimited string. More...
template<class C >
String &	joinmap (const C &map, char delim=',', char kvdelim='=')
	Join map items into delimited string. More...
template<class C >
String &	joinmapq (const C &map, char delim=',', char kvdelim='=')
	Join map items into delimited string, with quoting as needed. More...
template<class C >
String &	joinq (const C &items, char delim=',')
	Join list items into delimited string, with quoting as needed. More...
const Item *	last () const
	Get last item (const). More...
Item *	lastM ()
	Get last item (mutable). More...
void	move (Key dest, Key index)
	Move item to position (modifier). More...
Size	move (Key dest, ListType &src, Key srcindex=0, Size size=ALL)
	Move items from another list. More...
bool	null () const
	Get whether null. More...
Int	num (int base=0) const
	Convert to number value (signed). More...
Float	numf () const
	Convert to number value (floating point). More...
FloatD	numfd () const
	Convert to number value (double floating point). More...
FloatL	numfl () const
	Convert to number value (ldouble floating point). More...
Long	numl (int base=0) const
	Convert to number value (signed long). More...
LongL	numll (int base=0) const
	Convert to number value (signed long-long). More...
UInt	numu (int base=0) const
	Convert to number value (unsigned). More...
ULong	numul (int base=0) const
	Convert to number value (unsigned long). More...
ULongL	numull (int base=0) const
	Convert to number value (unsigned long-long). More...
bool	operator!= (const ListBaseType &data) const
	Inequality operator. More...
bool	operator!= (const String &str) const
	Inequality operator. More...
bool	operator!= (const char *str) const
	Inequality operator. More...
template<class T >
bool	operator!= (const ListBase< wchar16, T > &str)
	Inequality operator to compare against UTF-16 string. More...
char &	operator() (Key index)
	Get item at position (mutable). More...
String &	operator<< (bool val)
	Append operator. More...
String &	operator<< (char ch)
	Append operator. More...
String &	operator<< (const ListType &str)
	Append operator. More...
String &	operator<< (const StringBase &str)
	Append operator. More...
String &	operator<< (const char *str)
	Append operator. More...
String &	operator<< (const ValNull &val)
	Append operator to set as null and empty. More...
String &	operator<< (const ValEmpty &val)
	Append operator to set as empty but not null. More...
String &	operator<< (Newline nl)
	Append operator to append newline. More...
String &	operator<< (Flush)
	Flush output buffer – no-op for string. More...
String &	operator<< (int num)
	Append operator to append formatted number. More...
String &	operator<< (long num)
	Append operator to append formatted number. More...
String &	operator<< (longl num)
	Append operator to append formatted number. More...
String &	operator<< (uint num)
	Append operator to append formatted number. More...
String &	operator<< (ulong num)
	Append operator to append formatted number. More...
String &	operator<< (ulongl num)
	Append operator to append formatted number. More...
String &	operator<< (float num)
	Append operator to append formatted number. More...
String &	operator<< (double num)
	Append operator to append formatted number. More...
String &	operator<< (ldouble num)
	Append operator to append formatted number. More...
String &	operator<< (const FmtChar &fmt)
	Append operator to append formatted character field. More...
String &	operator<< (const FmtString &fmt)
	Append operator to append formatted string field. More...
String &	operator<< (const FmtStringWrap &fmt)
	Append operator to append formatted wrapped string column. More...
String &	operator<< (const FmtShort &fmt)
	Append operator to append formatted number field. More...
String &	operator<< (const FmtInt &fmt)
	Append operator to append formatted number field. More...
String &	operator<< (const FmtLong &fmt)
	Append operator to append formatted number field. More...
String &	operator<< (const FmtLongL &fmt)
	Append operator to append formatted number field. More...
String &	operator<< (const FmtUShort &fmt)
	Append operator to append formatted number field. More...
String &	operator<< (const FmtUInt &fmt)
	Append operator to append formatted number field. More...
String &	operator<< (const FmtULong &fmt)
	Append operator to append formatted number field. More...
String &	operator<< (const FmtULongL &fmt)
	Append operator to append formatted number field. More...
String &	operator<< (const FmtFloat &fmt)
	Append operator to append formatted number field. More...
String &	operator<< (const FmtFloatD &fmt)
	Append operator to append formatted number field. More...
String &	operator<< (const FmtFloatL &fmt)
	Append operator to append formatted number field. More...
template<class T >
String &	operator<< (const FmtFieldNum< T > &fmt)
	Append operator to append formatted number field. More...
template<class T >
String &	operator<< (const FmtFieldFloat< T > &fmt)
	Append operator to append formatted number field. More...
String &	operator<< (const FmtPtr &fmtptr)
	Append operator to append formatted pointer field. More...
String &	operator<< (const FmtDump &fmt)
	Append operator to append data dump. More...
String &	operator= (String &&src)
	Move assignment operator (C++11). More...
String &	operator= (const char16_t *str)
	Assignment operator to set and convert from terminated UTF-16 string. More...
String &	operator= (const String &str)
	Assignment operator. More...
String &	operator= (const ListType &str)
	Assignment operator. More...
String &	operator= (const ListType *str)
	Assignment operator for pointer. More...
String &	operator= (const StringBase &data)
	Assignment operator to copy from base list type. More...
String &	operator= (const char *str)
	Assignment operator for null terminated string. More...
String &	operator= (const PtrBase< char > &str)
	Assignment operator to copy from managed pointer with null terminated string. More...
template<class T >
String &	operator= (const ListBase< wchar16, T > &str)
	Assignment operator to convert from UTF-16 string to UTF-8 string. More...
String &	operator= (const ValNull &)
	Assignment operator to set as null and empty. More...
String &	operator= (const ValEmpty &)
	Assignment operator to set as empty but not null. More...
bool	operator== (const ListBaseType &data) const
	Equality operator. More...
bool	operator== (const String &str) const
	Equality operator. More...
bool	operator== (const char *str) const
	Equality operator. More...
template<class T >
bool	operator== (const ListBase< wchar16, T > &str)
	Equality operator to compare against UTF-16 string. More...
const Item &	operator[] (Key index) const
	Get item at position (const). More...
bool	pop (char &item, Key index)
	Pop a copy of given item (modifier). More...
bool	pop (char &item)
	Pop a copy of last item (stack) (modifier). More...
const Item *	pop ()
	Pop last item (stack). More...
bool	popq (char &item)
	Pop a copy of first item (queue) (modifier). More...
const Item *	popq ()
	Pop first item (queue). More...
ListType &	prepend (const Item *data, Size size)
	Prepend new items copied from data pointer (modifier). More...
String &	prepend (char ch)
	Prepend character (modifier). More...
String &	prepend (char ch, Size count)
	Prepend copies of the same character (modifier). More...
String &	prepend (const ListType &str)
	Prepend from another string (modifier). More...
String &	prepend (const StringBase &str)
	Prepend from another string (modifier). More...
String &	prepend (const char *str, Size size)
	Prepend from string pointer (modifier). More...
String &	prepend (const char *str)
	Prepend null terminated string (modifier). More...
String &	prependn (int num, int base=fDEC)
	Prepend formatted signed number (modifier). More...
String &	prependn (long num, int base=fDEC)
	Prepend formatted signed number (modifier). More...
String &	prependn (longl num, int base=fDEC)
	Prepend formatted signed number (modifier). More...
String &	prependn (uint num, int base=fDEC)
	Prepend formatted unsigned number (modifier). More...
String &	prependn (ulong num, int base=fDEC)
	Prepend formatted unsigned number (modifier). More...
String &	prependn (ulongl num, int base=fDEC)
	Prepend formatted unsigned number (modifier). More...
String &	prependn (float num, int precision=fPREC_AUTO)
	Prepend formatted floating point number (modifier). More...
String &	prependn (double num, int precision=fPREC_AUTO)
	Prepend formatted floating point number (modifier). More...
String &	prependn (ldouble num, int precision=fPREC_AUTO)
	Prepend formatted floating point number (modifier). More...
ListType &	prependnew (Size size=1)
	Prepend new items (modifier). More...
String &	prependsep (char delim=',')
	Prepend separator/delimiter if needed (modifier). More...
Size	remove (Key index, Size size=1)
	Remove items (modifier). More...
ListType &	replace (Key index, Size rsize, const Item *data, Size size)
	Replace items with new data (modifier). More...
String &	replace (Key index, Size rsize, const StringBase &str)
	Replace characters with string (modifier). More...
String &	replace (Key index, Size rsize, const char *str, Size size)
	Replace characters with string (modifier). More...
String &	replace (Key index, Size rsize, const char *str)
	Replace characters with string (modifier). More...
ListType &	reserve (Size size, bool prefer_realloc=false)
	Reserve capacity for additional items (modifier). More...
String &	reserve (Size size, bool prefer_realloc=false)
	Reserve capacity for additional items (modifier). More...
ListType &	resize (Size size)
	Resize while preserving existing data (modifier). More...
String &	resize (Size size)
	Resize while preserving existing data (modifier). More...
String &	reverse ()
	Reverse item order (modifier). More...
ListType &	set (const Item *data, Size size)
	Set from data pointer. More...
ListType &	set (const PtrBase< Item > &data, Size size)
	Set from managed data pointer. More...
ListType &	set (const ListType &data)
	Set from another list. More...
ListType &	set (const ListType &data, Key index, Key size=ALL)
	Set from subset of another list. More...
ListType &	set (const ListBaseType &data, Key index=0, Key size=ALL)
	Set as copy of sublist. More...
String &	set ()
	Set as null and empty. More...
String &	set (const ListType &str)
	Set from another string. More...
String &	set (const ListType &str, Key index, Key size=ALL)
	Set from substring of another string. More...
String &	set (const StringBase &data, Key index=0, Key size=ALL)
	Set as copy of substring. More...
String &	set (const char *str, Size size)
	Set from string pointer. More...
String &	set (const PtrBase< char > &str, Size size)
	Set from managed string pointer. More...
String &	set (const char *str)
	Set from terminated string. More...
String &	set (const PtrBase< char > &str)
	Set as copy of null terminated string from managed pointer. More...
ListType &	set2 (const ListType &data, Key index1, Key index2)
	Set from subset of another list using start/end positions. More...
ListType &	set2 (const ListBaseType &data, Key index1, Key index2)
	Set as copy of sublist using start/end positions. More...
String &	set2 (const ListType &str, Key index1, Key index2)
	Set from substring of another string using start/end positions. More...
String &	set2 (const StringBase &data, Key index1, Key index2)
	Set and reference sublist using start/end positions. More...
bool	set_unicode (const wchar16 *str, Size size, UtfMode mode=umREPLACE_INVALID)
	Set as normal UTF-8 string converted from a raw UTF-16 string. More...
bool	set_unicode (const wchar16 *str, UtfMode mode=umREPLACE_INVALID)
	Set as normal UTF-8 string converted from a raw terminated UTF-16 string. More...
bool	set_unicode (const char16_t *str, Size size, UtfMode mode=umREPLACE_INVALID)
	Set as normal UTF-8 string converted from a raw UTF-16 string. More...
bool	set_unicode (const char16_t *str, UtfMode mode=umREPLACE_INVALID)
	Set as normal UTF-8 string converted from a raw terminated UTF-16 string. More...
String &	set_win32 (const WCHAR *str, int size)
	Set as normal (UTF-8) string converted from a Windows UTF-16 (WCHAR) string (Windows only). More...
String &	set_win32 (const WCHAR *str)
	Set as normal (UTF-8) string converted from a terminated Windows UTF-16 (WCHAR) string (Windows only). More...
String &	setempty ()
	Set as empty but not null. More...
String &	setn (int num, int base=fDEC)
	Set as formatted signed number (modifier). More...
String &	setn (long num, int base=fDEC)
	Set as formatted signed number (modifier). More...
String &	setn (longl num, int base=fDEC)
	Set as formatted signed number (modifier). More...
String &	setn (uint num, int base=fDEC)
	Set as formatted unsigned number (modifier). More...
String &	setn (ulong num, int base=fDEC)
	Set as formatted unsigned number (modifier). More...
String &	setn (ulongl num, int base=fDEC)
	Set as formatted unsigned number (modifier). More...
String &	setn (float num, int precision=fPREC_AUTO)
	Set as formatted floating point number (modifier). More...
String &	setn (double num, int precision=fPREC_AUTO)
	Set as formatted floating point number (modifier). More...
String &	setn (ldouble num, int precision=fPREC_AUTO)
	Set as formatted floating point number (modifier). More...
bool	shared () const
	Get whether shared. More...
Size	size () const
	Get size. More...
ListType &	slice (Key index)
	Slice beginning items. More...
ListType &	slice (Key index, Size size)
	Slice to given sublist. More...
String &	slice (Key index)
	Slice beginning items. More...
String &	slice (Key index, Size size)
	Slice to given sublist. More...
ListType &	slice2 (Key index1, Key index2)
	Slice to given sublist using start/end positions. More...
String &	slice2 (Key index1, Key index2)
	Slice to given sublist using start/end positions. More...
template<class T1 , class T2 >
bool	split (char delim, T1 &left, T2 &right) const
	Split at first occurrence of delimiter into left/right substrings. More...
template<class T1 >
bool	split (char delim, T1 &left) const
	Split at first occurrence of delimiter into left substring. More...
template<class T2 >
bool	split (char delim, ValNull left, T2 &right) const
	Split at first occurrence of delimiter into right substring. More...
template<class Tok , class C >
C::Size	split (C &items, char delim=',') const
	Split delimited string into item list using given tokenizer. More...
bool	splitat (Key index, T1 &left, T2 &right) const
	Split into left/right sublists at index. More...
bool	splitat (Key index, T1 &left) const
	Split into left sublist at index. More...
bool	splitat (Key index, ValNull left, T2 &right) const
	Split into right sublist at index. More...
bool	splitat_setl (Key index)
	Split at index and set as left sublist. More...
bool	splitat_setl (Key index, T2 &right)
	Split at index, set as left sublist, and save right sublist. More...
bool	splitat_setr (Key index)
	Split at index and set as right sublist. More...
bool	splitat_setr (Key index, T1 &left)
	Split at index, set as right sublist, and save left sublist. More...
template<class C >
C::Size	splitmap (C &map, char delim=',', char kvdelim='=') const
	Split delimited string into map key/value items. More...
template<class T1 , class T2 >
bool	splitr (char delim, T1 &left, T2 &right) const
	Split at last occurrence of delimiter into left/right substrings. More...
template<class T1 >
bool	splitr (char delim, T1 &left) const
	Split at last occurrence of delimiter into left substring. More...
template<class T2 >
bool	splitr (char delim, ValNull left, T2 &right) const
	Split at last occurrence of delimiter into right substring. More...
bool	starts (const Item *items, Size size) const
	Check if starts with given items. More...
bool	starts (const ListBaseType &items) const
	Check if this starts with given items. More...
bool	starts (char ch) const
	Check if this starts with given character. More...
String &	strip ()
	Strip left (beginning) and right (ending) whitespace (spaces and tabs). More...
String &	strip (char ch)
	Strip left (beginning) and right (ending) occurences of character. More...
String &	strip2 ()
	Strip left (beginning) and right (ending) whitespace from string, including newlines. More...
String &	strip_newlines ()
	Strip left (beginning) and right (ending) newlines from string. More...
String &	stripl ()
	Strip left (beginning) whitespace (spaces and tabs). More...
String &	stripl (char ch, Size max=ALL)
	Strip left (beginning) occurrences of character. More...
String &	stripl (const char *str, Size strsize, Size max=ALL)
	Strip left (beginning) occurrences of string. More...
String &	stripl2 ()
	Strip left (beginning) whitespace from string, including newlines. More...
String &	stripl_newlines ()
	Strip all left (beginning) newlines from string. More...
String &	stripl_newlines (Size max)
	Strip left (beginning) newlines from string. More...
String &	stripr ()
	Strip right (ending) whitespace (spaces and tabs). More...
String &	stripr (char ch, Size max=ALL)
	Strip right (ending) occurences of character. More...
String &	stripr (const char *str, Size strsize, Size max=ALL)
	Strip right (ending) occurences of string. More...
String &	stripr2 ()
	Strip right (ending) whitespace (including newlines) from string. More...
String &	stripr_newlines ()
	Strip all right (ending) newlines from string. More...
String &	stripr_newlines (Size max)
	Strip right (ending) newlines from string. More...
void	swap (Key index1, Key index2)
	Swap items. More...
void	swap (ListType &list)
	Swap with another list. More...
template<class StringT >
bool	token (StringT &value, char delim)
	Extract next token from string. More...
template<class StringT >
bool	token_any (StringT &value, Char &found_delim, const char *delims, Size count)
	Extract next token from string using any of given delimiters. More...
template<class StringT >
bool	token_line (StringT &line)
	Extract next line from string. More...
template<class StringT >
bool	tokenr (StringT &value, char delim)
	Extract next token from string in reverse (from end of string). More...
template<class StringT >
bool	tokenr_any (StringT &value, Char &found_delim, const char *delims, Size count)
	Extract next token from string in reverse (from end of string) using any of given delimiters. More...
template<class StringT >
bool	tokenr_line (StringT &line)
	Extract next line from string in reverse (from end of string). More...
ThisType &	tolower ()
	Convert all uppercase characters in string to lowercase (modifier). More...
ThisType &	toupper ()
	Convert all lowercase characters in string to uppercase (modifier). More...
ListType &	triml (Size size)
	Trim left (beginning) items. More...
String &	triml (Size size)
	Trim left (beginning) items. More...
ListType &	trimr (Size size)
	Trim right (ending) items. More...
String &	trimr (Size size)
	Trim right (ending) items. More...
ListType &	truncate (Size size=0)
	Truncate to given size. More...
String &	truncate (Size size=0)
	Truncate to given size. More...
String &	unshare ()
	Make data unique by allocating new buffer, if needed (modifier). More...
String &	unslice ()
	Clean and remove hidden items previously removed via slicing (modifier). More...
char *	write_direct (Size size)
	Get pointer for writing directly to buffer to append data. More...
bool	write_direct_finish (Size size)
	Finish writing directly to buffer. More...
char *	write_direct_flush (Size &available, Size written_size, Size reserve_size)
	Flush data written directly to buffer and get pointer for appending more. More...
char *	write_direct_multi (Size &available, Size reserve_size)
	Get pointer for writing directly to buffer to append data and allow multiple passes for larger sizes. More...
Out &	write_out ()
	Get parent output string. More...
Size	writebin (const char *buf, Size size)
	Write (append) to string. More...
Size	writechar (char ch, Size count=1)
	Write (append) repeat character as text output to string. More...
bool	writefmtchar (char ch, Size count, const FmtSetField &field)
	Write (append) formatted and/or repeated character. More...
bool	writefmtdump (const FmtDump &fmt, const char *newline, uint newlinesize)
	Write formatted data dump. More...
bool	writefmtdump (const FmtDump &fmt, Newline nl=NL_SYS)
	Write formatted data dump. More...
template<class TNum >
bool	writefmtnum (TNum num, const FmtSetInt &fmt, const FmtSetField *field=NULL)
	Write (append) formatted signed number with field alignment. More...
template<class TNum >
bool	writefmtnumf (TNum num, const FmtSetFloat &fmt, const FmtSetField *field=NULL)
	Write (append) formatted floating point number with field alignment. More...
template<class TNum >
bool	writefmtnumu (TNum num, const FmtSetInt &fmt, const FmtSetField *field=NULL)
	Write (append) formatted unsigned number with field alignment. More...
bool	writefmtstr (const char *str, Size size, const FmtSetField &field)
	Write (append) text with field alignment. More...
template<class TNum >
bool	writenum (TNum num, int base=fDEC)
	Write (append) formatted signed number. More...
template<class TNum >
bool	writenumf (TNum num, int precision=fPREC_AUTO)
	Write (append) formatted floating-point number. More...
template<class TNum >
bool	writenumu (TNum num, int base=fDEC)
	Write (append) formatted unsigned number. More...
Size	writequoted (const char *buf, Size size, char delim, bool optional=false)
	Write (append) quoted output to string. More...
Size	writetext (const char *buf, Size size)
	Write (append) text output to string. More...

Static Public Member Functions
static const String &	digits ()
	Get string of all ASCII alphanumeric digits with uppercase letters (0-9, A-Z). More...
static const String &	digitsl ()
	Get string of all ASCII alphanumeric digits with lowercase letters (0-9, a-z). More...
static const String &	letters ()
	Get string of ASCII letters (A-z). More...
static const String &	lettersl ()
	Get string of ASCII lowercase letters (a-z). More...
static const String &	lettersu ()
	Get string of ASCII uppercase letters (A-Z). More...
static const String &	whitespace ()
	Get string of ASCII whitespace characters (space, tab). More...

Public Attributes
char *	data_
	Data pointer, NULL if null. More...
StrSizeT	size_
	Data size as item count, 0 if empty or null. More...

Protected Member Functions
void	ref (const ListType &data)
	Set as reference to another list. More...
void	ref (const ListType &data, Size index, Size size)
	Set as sliced reference to another list. More...
void	ref (const Item *data, Size size, bool term=false)
	Set as reference to given data. More...

Protected Attributes
Buf	buf_
	List buffer. More...

Member Typedef Documentation

EvoContainerType

typedef void EvoContainerType

inherited

Item

typedef char Item

inherited

Item type (same as Value)

ItemVal

typedef DataCopy<char >::PassType ItemVal

inherited

Item type as parameter (POD types passed by value, otherwise by const-ref)

Iter

typedef IteratorRa<ThisType>::Const Iter

inherited

Iterator (const) - IteratorRa.

IterM

typedef IteratorRa<ThisType> IterM

inherited

Iterator (mutable) - IteratorRa.

Key

typedef Size Key

inherited

Key type (item index)

ListBaseType

typedef ListBase<char ,Size> ListBaseType

inherited

List base type for any Evo list

ListType

typedef List<char,StrSizeT> ListType

List type.

Out

typedef String Out

Type returned by write_out()

Size

typedef StrSizeT Size

inherited

List size integer type

StringBase

typedef ListBaseType StringBase

Alias for ListBaseType.

ThisType

typedef String ThisType

This string type.

UnicodeStringBase

typedef ListBase<wchar16,Size> UnicodeStringBase

Base for UnicodeString.

Value

typedef char Value

inherited

Value type (same as Item)

Constructor & Destructor Documentation

String() [1/15]

String ( )

inline

Default constructor sets as null.

String() [2/15]

String ( const String &  str )

inline

Copy constructor.

• Makes shared copy if possible – see Sharing

Parameters

str	String to copy

String() [3/15]

String ( const ListType &  str )

inline

Copy constructor.

• Makes shared copy if possible – see Sharing

Parameters

str	String to copy

String() [4/15]

String ( const ListType *  str )

inline

Copy constructor.

• Makes shared copy if possible – see Sharing

Parameters

str	String pointer to copy from, ignored if null

String() [5/15]

String ( const ListType &  str, Key  index, Key  size = ALL  )

inline

Extended copy constructor.

• Makes shared copy if possible – see Sharing

Parameters

str	String to copy
index	Start index of string to copy, END to set as empty
size	Size as character count, ALL for all from index

String() [6/15]

String ( const StringBase &  str, Key  index = 0, Key  size = ALL  )

inline

Constructor to copy substring data.

• This always makes an unshared copy
• For best performance (and less safety) reference substring instead with String(const char*,Size)

Parameters

str	SubString to copy
index	Start index of string to copy, END to set as empty
size	Size as character count, ALL for all from index

String() [7/15]

String ( const char *  str, Size  size  )

inline

Constructor for string pointer.

• Caution: Uses Unsafe Pointer Referencing
• See String(const PtrBase<char>&,Size) for best safety, use Ptr<char> to wrap raw pointer

Parameters

str	String pointer to use
size	String size as character count

String() [8/15]

String ( const PtrBase< char > &  str, Size  size  )

inline

Constructor for managed string pointer.

• This always makes an unshared copy
• For best performance (and less safety) reference substring instead with String(const char*,Size)
• Use Ptr<char> to wrap raw pointer

Parameters

str	String pointer, calls set() if null
size	String size as character count

String() [9/15]

String ( const UnicodeStringBase &  str )

inline

Constructor to convert from UTF-16 string to UTF-8 string.

• This calls set_unicode()

Parameters

str	UTF-16 string to convert from

Returns

This

String() [10/15]

String ( const char *  str )

inline

Constructor for null terminated string.

• Caution: Uses Unsafe Pointer Referencing
• See String(const PtrBase<char>&) for best safety, use Ptr<char> to wrap raw pointer

Parameters

str	String pointer, calls set() if null – must be terminated

String() [11/15]

String ( const PtrBase< char > &  str )

inline

Constructor to copy null terminated string from managed pointer.

• This always makes an unshared copy
• For best performance (and less safety) reference substring instead with String(const char*)
• Use Ptr<char> to wrap raw pointer

Parameters

str	String pointer, calls set() if null – must be terminated

String() [12/15]

String ( const char16_t *  str, Size  size, UtfMode  mode = umREPLACE_INVALID  )

inline

Constructor to initialize and convert from UTF-16 string literal (using u prefix).

• This calls set_unicode(const char16_t*,Size,UtfMode)

Parameters

str	String literal, NULL to set as null
size	String size in UTF-16 chars
mode	How to handle invalid UTF-16 values, see set_unicode()

String() [13/15]

String ( const char16_t *  str, UtfMode  mode = umREPLACE_INVALID  )

inline

Constructor to initialize and convert from terminated UTF-16 string literal (using u prefix).

• This calls set_unicode(const char16_t*,UtfMode)

Parameters

str	UTF-16 string, NULL to set as null, otherwise must be terminated
mode	How to handle invalid UTF-16 values, see set_unicode()

String() [14/15]

String ( const std::initializer_list< char > &  init )

inline

Sequence constructor (C++11).

Parameters

init	Initializer list, passed as comma-separated values in braces { }

String() [15/15]

String ( String &&  src )

inline

Move constructor (C++11).

Parameters

src	Source to move

Member Function Documentation

add() [1/7]

ListType& add ( const Item *  data, Size  size  )

inlineinherited

Append new items copied from data pointer (modifier).

• Effectively calls unshare()
• Removes items sliced from end – see unslice()

Parameters

data	Data to append
size	Size as item count to append

Returns

This

add() [2/7]

String& add ( char  ch )

inline

Append character (modifier).

Parameters

ch	Character to append

Returns

This

add() [3/7]

String& add ( char  ch, Size  count  )

inline

Append copies of the same character (modifier).

Parameters

ch	Character to append
count	Character copies to append

Returns

This

add() [4/7]

String& add ( const ListType &  str )

inline

Append from another string (modifier).

• For best performance use set(const String&) when this is empty

Parameters

str	String to append

Returns

This

add() [5/7]

String& add ( const StringBase &  str )

inline

Append from another string (modifier).

• For best performance use set(const String&) when this is empty

Parameters

str	String to append

Returns

This

add() [6/7]

String& add ( const char *  str, Size  size  )

inline

Append from string pointer (modifier).

• For best performance use set(const char*,Size) when this is empty

Parameters

str	String to append
size	String size as character count to append

Returns

This

add() [7/7]

String& add ( const char *  str )

inline

Append null terminated string (modifier).

• For best performance use set(const char*) when this is empty

Parameters

str	String to append – must be terminated

Returns

This

addmin()

ListType& addmin ( Size  minsize )

inlineinherited

Append new items up to a given minimum size (modifier).

• This calls addnew() to add items as needed to reach given minimum size

Parameters

minsize

Minimum list size

Returns

This

addn() [1/9]

String& addn ( int  num, int  base = fDEC  )

inline

Append formatted signed number (modifier).

Parameters

num	Number to append
base	Base to use for formatting

Returns

This

addn() [2/9]

String& addn ( long  num, int  base = fDEC  )

inline

Append formatted signed number (modifier).

Parameters

num	Number to append
base	Base to use for formatting

Returns

This

addn() [3/9]

String& addn ( longl  num, int  base = fDEC  )

inline

Append formatted signed number (modifier).

Parameters

num	Number to append
base	Base to use for formatting

Returns

This

addn() [4/9]

String& addn ( uint  num, int  base = fDEC  )

inline

Append formatted unsigned number (modifier).

Parameters

num	Number to append
base	Base to use for formatting

Returns

This

addn() [5/9]

String& addn ( ulong  num, int  base = fDEC  )

inline

Append formatted unsigned number (modifier).

Parameters

num	Number to append
base	Base to use for formatting

Returns

This

addn() [6/9]

String& addn ( ulongl  num, int  base = fDEC  )

inline

Append formatted unsigned number (modifier).

Parameters

num	Number to append
base	Base to use for formatting

Returns

This

addn() [7/9]

String& addn ( float  num, int  precision = fPREC_AUTO  )

inline

Append formatted floating point number (modifier).

Parameters

num	Number to append
precision	Formatting precision (number of fractional digits), 0 for none, fPREC_AUTO for automatic

Returns

This

addn() [8/9]

String& addn ( double  num, int  precision = fPREC_AUTO  )

inline

Append formatted floating point number (modifier).

Parameters

num	Number to append
precision	Formatting precision (number of fractional digits), 0 for none, fPREC_AUTO for automatic

Returns

This

addn() [9/9]

String& addn ( ldouble  num, int  precision = fPREC_AUTO  )

inline

Append formatted floating point number (modifier).

Parameters

num	Number to append
precision	Formatting precision (number of fractional digits), 0 for none, fPREC_AUTO for automatic

Returns

This

addnew()

ListType& addnew ( Size  size = 1 )

inlineinherited

Append new items (modifier).

• Effectively calls unshare()
• Removes items sliced from end – see unslice()

Parameters

size	Size as item count to append

Returns

This

addsep()

String& addsep ( char  delim = ',' )

inline

Append separator/delimiter if needed (modifier).

• This will only append given delim if not empty and not already ending with delim

Parameters

delim

Delimiter to append

Returns

This

advAdd()

void advAdd ( Size  size )

inlineinherited

Advanced: Append new items without initializing (constructing) them.

• Caution: Data must be unique (not shared) or results are undefined
• Caution: The new items must be initialized with DataInit::init_safe() or removed with advRemove() before items are accessed, modified, or list is destroyed
• Caution: Results are undefined if new items are left uninitialized

Parameters

size	Size to append

advBuffer() [1/2]

char * advBuffer ( Size  size )

inlineinherited

Advanced: Resize and get buffer pointer (modifier).

• Used for writing directly to buffer – this calls advResize() first to make room
• For best performance call clear() first
• Call advSize() after writing to adjust size, if needed
• Caution: Results are undefined if buffer is accessed after size
• Caution: For non-POD type results are undefined if don't initialize new items or uninitialize removed items correctly

Parameters

size	Size to resize to

Returns

Buffer pointer

advBuffer() [2/2]

char * advBuffer ( )

inlineinherited

Advanced: Get buffer pointer (modifier).

• Used for writing directly to buffer
• Buffer must be resized first to make room – see advBuffer(Size), advResize(), resize()
• Call advSize() after writing to adjust size, if needed
• Caution: Data must be unique (not shared) when writing or results are undefined
• Caution: Results are undefined if buffer is accessed out of bounds
• Caution: For non-POD type results are undefined if don't initialize new items or uninitialize removed items correctly

Returns

Buffer pointer, NULL for none

advEdit()

bool advEdit ( Edit &  edit, Size  minsize, bool  inplace = true  )

inlineinherited

Advanced: Start optimized in-place/buffer edit.

• This approach optimizes by selecting the best case for editing (in-place or new buffer), and the caller must handle each case correctly
• For easier approach use advBuffer(Size) and always edit in-place – but is less efficient in certain cases, like when buffer grows
• If the current buffer is unique and big enough (and beginning isn't sliced, and inplace flag is set):
  • This sets 'edit.ptr' and 'edit.size' to current buffer and size, and returns true to edit in-place
  • Modify buffer as needed via 'edit.ptr', update 'edit.size'
  • Call advEditDone() when done to adjust to new size
  • Note: If you don't call advEditDone() then in-place edits will still remain and the previous size will be used
• Otherwise a new empty buffer is created:
  • This sets 'edit.ptr' to a new buffer and 'edit.size' to 0, and returns false
  • Write to buffer in 'edit.ptr' as needed, copy from data() or use edit.write() methods if needed, update 'edit.size'
  • Call advEditDone() when done to use new buffer and new size
  • Note: If you don't call advEditDone() then Edit destructor will still free the new buffer (no memory leak)
• This is mainly intended for POD types
• Caution: Results are undefined if another modifier method is used during an edit
• Caution: Results are undefined if edit buffer is accessed after minsize
• Caution: For non-POD type, results are undefined if you don't initialize new items or don't uninitialize removed items correctly

Parameters

edit	Edit buffer data, use 'edit.ptr'
minsize	Minimum buffer size needed, must be positive
inplace	Whether to try in-place edit, false to always use new buffer

Returns

Whether editing in-place, false if a new empty buffer was created

advEditDone()

void advEditDone ( Edit &  edit )

inlineinherited

Advanced: Finish edit started with advEdit() (modifier).

• Must call advEdit() first to start edit
• This applies the pending edit and makes it permanent

Parameters

edit	Edit data set from advEdit()

advFirst()

char * advFirst ( )

inlineinherited

Advanced: Get first item (modifier).

• Caution: This does not call unshare() – results are undefined if in a shared state

Returns

First item pointer, NULL if empty

advInsert()

Key advInsert ( Key  index, Size  size  )

inlineinherited

Advanced: Insert new items without initializing (constructing) them.

• Caution: Data must be unique (not shared) or results are undefined
• Caution: The new items must be initialized with DataInit::init_safe() or removed with advRemove() before items are accessed, modified, or list is destroyed
• Caution: Results are undefined if new items are left uninitialized

Parameters

index	Insert index (END for end of list)
size	Insert data size

Returns

Actual insert index

advItem()

char & advItem ( Key  index )

inlineinherited

Advanced: Get item (mutable).

• Caution: Data must be unique (not shared) or results are undefined
• Caution: Results are undefined if index is out of bounds – though index is checked with assert()

Parameters

index

Item index

Returns

Given item

advLast()

char * advLast ( )

inlineinherited

Advanced: Get last item (modifier).

• Caution: This does not call unshare() – results are undefined if in a shared state

Returns

Last item pointer, NULL if empty

advPrepend()

void advPrepend ( Size  size )

inlineinherited

Advanced: Prepend new items without initializing (constructing) them.

• Caution: Data must be unique (not shared) or results are undefined
• Caution: The new items must be initialized with DataInit::init_safe() or removed with advRemove() before items are accessed, modified, or list is destroyed
• Caution: Results are undefined if new items are left uninitialized

Parameters

size	Size to prepend

advRemove()

void advRemove ( Key  index, Size  size  )

inlineinherited

Advanced: Remove given items without uninitializing (destructing) them.

• Caution: Use only to remove uninitialized items – use DataInit::uninit() to uninitialize items that have been initialized
• Caution: Data must be unique (not shared) or results are undefined
• Caution: Uninitialized items must be initialized with DataInit::init_safe() or removed with advRemove() before items are accessed, modified, or list is destroyed

Parameters

index	Remove index
size	Remove size as item count, ALL for all from index

advResize() [1/2]

ListType& advResize ( Size  size )

inlineinherited

Advanced: Resize while preserving existing data, POD items not initialized (modifier).

• This is a slightly modified version of resize():
  • No difference on non POD item types
  • For POD item type: New items created here will not be initialized/zeroed
  • This gives a slight performance increase in some cases but will leave uninitialized garbage data for POD items
  • In most cases resize() is preferred since it's safer and the performance difference is usually negligible
• This adds/removes items as needed until given size is reached
• Effectively calls unshare()
• Advanced: See advBuffer() for getting writable pointer to buffer

Parameters

size	New size as item count

Returns

This

advResize() [2/2]

String& advResize ( Size  size )

inline

Advanced: Resize while preserving existing data, POD items not initialized (modifier).

• This is a slightly modified version of resize():
  • No difference on non POD item types
  • For POD item type: New items created here will not be initialized/zeroed
  • This gives a slight performance increase in some cases but will leave uninitialized garbage data for POD items
  • In most cases resize() is preferred since it's safer and the performance difference is usually negligible
• This adds/removes items as needed until given size is reached
• Effectively calls unshare()
• Advanced: See advBuffer() for getting writable pointer to buffer

Parameters

size	New size as item count

Returns

This

advSize()

void advSize ( Size  size )

inlineinherited

Advanced: Set new size after writing directly to buffer.

• Used after calling advBuffer() and writing to buffer
• Caution: Using this on non POD list can create/leave uninitialized items and undefined results
• Caution: Data must be unique (not shared) when writing or results are undefined
• Caution: No bounds checking is used on new size

Parameters

size

New size

advSwap()

void advSwap ( Key  index1, Key  index2  )

inlineinherited

Advanced: Swap given items.

• A faster version of swap() without bounds checking
• Caution: Data must be unique (not shared) and indexes must be valid or results are undefined

Parameters

index1	Index of first item to swap
index2	Index of second item to swap

advWrite()

char * advWrite ( Size  addsize )

inlineinherited

Advanced: Get buffer pointer to write/append (modifier).

• Used for appending by writing directly to buffer – this calls unslice() and resrve() first to make room
• Call advWriteDone() after writing to adjust actual size used, skip if nothing written
• Caution: Results are undefined if buffer is accessed after addsize
• Caution: For non-POD type results are undefined if don't initialize new items items correctly

Parameters

addsize

Max size to write/append, must be at least 1

Returns

Pointer to buffer to write to (after existing data)

advWriteDone()

void advWriteDone ( Size  addsize )

inlineinherited

Advanced: Update size added after writing directly to buffer.

• Used after calling advWrite() and writing to buffer
  • No need to call this if nothing written
• Caution: Using this on non POD list can create uninitialized items and undefined results
• Caution: Data must be unique (not shared) when writing or results are undefined – advWrite() covers this
• Caution: No bounds checking is used on addsize

Parameters

addsize

Actual size written

asconst()

const String& asconst ( ) const

inline

Explicitly use a const reference to this.

• This is useful to force using this as const without casting

Returns

This

begin() [1/2]

IterM begin ( )

inline

Get iterator at first item (mutable).

• This allows compatibility with range-based for loops and other libraries, otherwise use container Iter directly
• cbegin() is more efficient, since this effectively calls unshare() to make chars mutable

Returns

Iterator at first item, or at end position if empty

See also

IterM, end(), cbegin(), cend()

begin() [2/2]

Iter begin ( ) const

inline

Get iterator at first item (const).

• This allows compatibility with range-based for loops and other libraries, otherwise use container Iter directly

Returns

Iterator at first item, or at end position if empty

See also

end() const, cbegin()

boolval()

Bool boolval ( ) const

inline

Convert to bool value.

Fails on bad format, empty, or number overflow.

Format: [WHITESPACE] ["on"|"off"|"yes"|"no"|"true"|"false"|"t"|"f"|DIGITS] [WHITESPACE]

• Result is true if non-zero number – checked using getnum(Error&,int) with T=long, base=0
• Case insensitive

Returns

Converted value, set to null on failure

capacity() [1/3]

ListType& capacity ( Size  size )

inlineinherited

Set new capacity (modifier).

• Consider using reserve() instead to allocate additional capacity in advance
• Items that don't fit new capacity are removed, even if buffer isn't used
• Effectively calls unshare() if buffer is shared
• May still reference external data even though buffer is allocated
• Use unshare() to force data to buffer

Parameters

size	New capacity

Returns

This

capacity() [2/3]

Size capacity ( ) const

inline

Get capacity.

• This gets the total size of currently allocated buffer
• Data still may be referenced without a buffer so this could return less than size()
• Buffer may be allocated (by previous use) even though not currently used

Returns

Capacity as item count, 0 if no buffer allocated

capacity() [3/3]

String& capacity ( Size  size )

inline

Set new capacity (modifier).

• Consider using reserve() instead to allocate additional capacity in advance
• Items that don't fit new capacity are removed, even if buffer isn't used
• Effectively calls unshare() if buffer is shared
• May still reference external data even though buffer is allocated
• Use unshare() to force data to buffer

Parameters

size	New capacity

Returns

This

capacitymax() [1/2]

ListType& capacitymax ( Size  max )

inlineinherited

Set maximum capacity (modifier).

• This reduces capacity to given maximum if it's greater
• Items that don't fit new capacity are removed, even if buffer isn't used
• Effectively calls unshare() if capacity changes and buffer is shared
• May still reference external data even though buffer is allocated
• Use unshare() to force data to buffer

Parameters

max	Maximum capacity

Returns

This

capacitymax() [2/2]

String& capacitymax ( Size  max )

inline

Set maximum capacity (modifier).

• This reduces capacity to given maximum if it's greater
• Items that don't fit new capacity are removed, even if buffer isn't used
• Effectively calls unshare() if capacity changes and buffer is shared
• May still reference external data even though buffer is allocated
• Use unshare() to force data to buffer

Parameters

max	Maximum capacity

Returns

This

capacitymin() [1/2]

ListType& capacitymin ( Size  min )

inlineinherited

Set minimum capacity (modifier).

• This increases capacity to given minimum if it's less
• Effectively calls unshare() if capacity changes and buffer is shared
• May still reference external data even though buffer is allocated
• Use unshare() to force data to buffer

Parameters

min	Minimum capacity

Returns

This

capacitymin() [2/2]

String& capacitymin ( Size  min )

inline

Set minimum capacity (modifier).

• This increases capacity to given minimum if it's less
• Effectively calls unshare() if capacity changes and buffer is shared
• May still reference external data even though buffer is allocated
• Use unshare() to force data to buffer

Parameters

min	Minimum capacity

Returns

This

cbegin()

Iter cbegin ( ) const

inline

Get iterator at first item (const).

• This allows compatibility with range-based for loops and other libraries, otherwise use container Iter directly

Returns

Iterator at first item, or at end position if empty

See also

Iter, cend(), begin(), end()

cend()

Iter cend ( ) const

inline

Get iterator at end (const).

• This allows compatibility with range-based for loops and other libraries, otherwise use container Iter directly
• This really just creates an empty iterator

Returns

Iterator at end position

See also

Iter, cbegin(), begin(), end()

clear()

String& clear ( )

inline

Clear by removing all items.

• Does not set as null – null status is unchanged
• Append operators can be chained
  Example:

  // Clear character list and append two characters
  list.clear() << 'a' << 'b';

Returns

This

compact()

String& compact ( )

inline

Reduce capacity to fit current size (modifier).

• Call to save memory when done expanding size
• Ignored if shared, may want to call unshare() first

Returns

This

compare() [1/2]

int compare ( const ListBaseType &  data ) const

inlineinherited

Comparison.

Parameters

data	Data to compare to

Returns

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

compare() [2/2]

int compare ( const ListBase< wchar16, T > &  str )

inline

Comparison against UTF-16 string.

Template Parameters

T	Inferred from argument

Parameters

str	String to compare to

Returns

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

contains() [1/4]

bool contains ( const Item *  data, Size  size  ) const

inlineinherited

Check if contains given data.

• This does a simple linear search for given array of items, using item operator==() for comparisons

Parameters

data	Data to check for
size	Size as item count to check for

Returns

Whether data was found

contains() [2/4]

bool contains ( char  ch ) const

inline

Check whether this contains given character.

Parameters

ch	Character to check for

Returns

Whether character was found

contains() [3/4]

bool contains ( const char *  str, Size  size  ) const

inline

Check whether this contains given string.

Parameters

str	Pointer to string to check for
size	String size in bytes

Returns

Whether string was found

contains() [4/4]

bool contains ( const StringBase &  str ) const

inline

Check whether contains given string.

Parameters

str	String to check for

Returns

Whether string was found

convert()

C convert ( ) const

inline

Convert string to value of given type.

• Advanced: Custom conversions can be defined by specializing a template instance of Convert – see Custom String Conversion/Formatting

Template Parameters

C	Type to convert to

Returns

Converted value

convert_add()

String& convert_add ( C  value )

inline

Convert value to string, appending to current string.

• Advanced: Custom conversions can be defined by specializing a template instance of Convert – see Custom String Conversion/Formatting

Template Parameters

C	Type to convert from, inferred from argument

Parameters

value

Value to convert

convert_addq()

bool convert_addq ( C  value, char  delim = ','  )

inline

Convert value to string with quoting as needed, appending to current string.

• Advanced: Custom conversions can be defined by specializing a template instance of Convert – see Custom String Conversion/Formatting

Template Parameters

C	Type to convert from, inferred from argument

Parameters

value	Value to convert
delim	Delimiter to use to determine quoting needed – this is not added to string

Returns

Whether successful, false if input is a string and is not quotable (invalid text)

convert_set()

String& convert_set ( C  value )

inline

Convert value to string, replacing current string.

• Advanced: Custom conversions can be defined by specializing a template instance of Convert – see Custom String Conversion/Formatting

Template Parameters

C	Type to convert from, inferred from argument

Parameters

value

Value to convert

copy() [1/5]

ListType& copy ( const Item *  data, Size  size  )

inlineinherited

Set as full (unshared) copy using data pointer (modifier).

• Effectively calls unshare()

Parameters

data	Data to copy
size	Data size as item count

Returns

This

copy() [2/5]

String& copy ( const ListType &  str )

inline

Set as full (unshared) copy of another string (modifier).

Parameters

str	String to copy

Returns

This

copy() [3/5]

String& copy ( const StringBase &  str )

inline

Set as full (unshared) copy of substring (modifier).

Parameters

str	String to copy

Returns

This

copy() [4/5]

String& copy ( const char *  str, Size  size  )

inline

Set as full (unshared) copy using string pointer (modifier).

Parameters

str	String to copy
size	String size as character count

Returns

This

copy() [5/5]

String& copy ( const char *  str )

inline

Set as full (unshared) copy of null terminated string (modifier).

Parameters

str	String to copy – must be terminated

Returns

This

cstr() [1/2]

const char* cstr ( String &  buffer ) const

inline

Get terminated string pointer, using given string buffer if needed (const).

• This is useful when a temporary terminated string pointer is needed
• Same as data() when already internally terminated, otherwise provided buffer is used to store terminated string
• Caution: Calling any modifier/mutable method like unshare() after this may (will) invalidate the returned pointer
• Caution: Modifying the buffer also may (will) invalidate the returned pointer
• Example:

  void print(const String& str1, const String& str2) {
      String temp;
      printf("String1: '%s'\n", str1.cstr(temp));
      printf("String2: '%s'\n", str2.cstr(temp));
  }

• BAD Example – results undefined:

  void bad_print(const String& str1, const String& str2) {
      String temp;
      // Error: Undefined results: pointer from str1.cstr() is likely invalidated by str2.cstr()!
      printf("String1: '%s'\nString2: '%s'\n", str1.cstr(temp), str2.cstr(temp));
  }

Parameters

buffer

Buffer to use, if needed

Returns

Terminated string pointer

cstr() [2/2]

const char* cstr ( )

inline

Get terminated string pointer (modifier).

• Use cstr(String&) instead for const instance
• This effectively calls unshare() and adds an internal null terminator, if needed
• Caution: Calling any modifier method like add(char) after this may (will) invalidate the returned pointer

Returns

Terminated string pointer

cstrM()

const char* cstrM ( ) const

inline

Get terminated string pointer (modifier).

• This is potentially unsafe and should be avoided if possible, use cstr() or cstr(String&) instead
• Caution: This defeats "const" and may reallocate or modify the buffer if needed
• Caution: Calling any modifier method like add(char) after this may (will) invalidate the returned pointer

data()

const char* data ( ) const

inline

Get string pointer (const).

• In some cases string may already be terminated but DO NOT expect this – use cstr() to get terminated string
• Caution: Calling any modifier/mutable method like unshare() after this may (will) invalidate the returned pointer

Returns

String pointer as read-only, NULL if null, may be invalid if string empty (const)

dataM()

char * dataM ( )

inlineinherited

Get data pointer (mutable).

• Calls unshare()
• Caution: Calling any modifier method like add() after this may (will) invalidate the returned pointer
• For best performance, reuse returned pointer for repeated access, or use data() instead for read-only access

Returns

Data pointer (mutable).

digits()

static const String& digits ( )

inlinestatic

Get string of all ASCII alphanumeric digits with uppercase letters (0-9, A-Z).

Returns

String of digits

digitsl()

static const String& digitsl ( )

inlinestatic

Get string of all ASCII alphanumeric digits with lowercase letters (0-9, a-z).

Returns

String of digits

empty()

bool empty ( ) const

inlineinherited

Get whether empty.

• Empty when size() is 0

Returns

Whether empty

end() [1/2]

IterM end ( )

inline

Get iterator at end.

• This allows compatibility with range-based for loops and other libraries, otherwise use container Iter directly
• This really just creates an empty iterator

Returns

Iterator at end position

See also

IterM, begin(), cbegin(), cend()

end() [2/2]

Iter end ( ) const

inline

Get iterator at end.

• This allows compatibility with range-based for loops and other libraries, otherwise use container Iter directly
• This really just creates an empty iterator

Returns

Iterator at end position

See also

begin() const, cend()

ends() [1/3]

bool ends ( const Item *  items, Size  size  ) const

inlineinherited

Check if this ends with given items.

• Uses item operator==() for comparisons

Parameters

items	Items to check
size	Item count to check

Returns

Whether ends with items

ends() [2/3]

bool ends ( const ListBaseType &  items ) const

inlineinherited

Check if this ends with given items.

• Uses item operator==() for comparisons

Parameters

items

Items to check

Returns

Whether ends with items

ends() [3/3]

bool ends ( char  ch ) const

inline

Check if this ends with given character.

Parameters

ch	Character to check

Returns

Whether ends with character

fill()

ListType& fill ( const Item &  item, Key  index = 0, Size  size = ALL  )

inlineinherited

Fill using item (modifier).

• Calls unshare() if any filling done
• Resizes to fill new items if needed

Parameters

item	Item to fill with
index	Start index, END to start at end and append
size	Size to fill as item count from index, ALL for all items from index, 0 to do nothing

fillch()

String& fillch ( char  ch, Key  index = 0, Size  size = ALL  )

inline

Fill with copies of character (modifier).

Parameters

ch	Character to fill with
index	Start index, END to start at end and append
size	Size to fill as character count from index, ALL for all items from index, 0 to do nothing

find() [1/7]

Key find ( ItemVal  item, Key  start = 0, Key  end = END  ) const

inlineinherited

Find first occurrence of item with forward search.

• This searches for given item, using item operator==() for comparisons
• Search stops before reaching end index or end of list
• Item at end index is not checked

Parameters

item	Item to find
start	Starting index for search
end	End index for search, END for end of list

Returns

Found item index or NONE if not found

find() [2/7]

Key find ( char  ch ) const

inline

Find first occurrence of character with forward search.

Parameters

ch	Character to find

Returns

Found character index, NONE if not found

find() [3/7]

Key find ( char  ch, Key  start, Key  end = END  ) const

inline

Find first occurrence of character with forward search.

• Search stops before reaching end index or end of string
• Character at end index is not checked

Parameters

ch	Character to find
start	Starting index for search
end	End index for search, END for end of string

Returns

Found character index, NONE if not found

find() [4/7]

Key find ( const char *  pattern, uint  pattern_size, Key  start = 0, Key  end = END  ) const

inline

Find first occurrence of pattern string.

• Search stops before reaching end index or end of string
• Character at end index is not checked
• Specify search algorithm with: find(StringSearchAlg,const char*,uint,Key,Key) const

Parameters

pattern	Pointer to pattern to look for, must not be NULL
pattern_size	Pattern size in bytes
start	Starting index for search
end	End index for search, END for end of string

Returns

Found pattern index, NONE if not found or if pattern_size=0

find() [5/7]

Key find ( StringSearchAlg  alg, const char *  pattern, uint  pattern_size, Key  start = 0, Key  end = END  ) const

inline

Find first occurrence of pattern string using specified algorithm.

• Search stops before reaching end index or end of string
• Character at end index is not checked

Parameters

alg	Search algorithm to use, see StringSearchAlg
pattern	Pointer to pattern to look for, must not be NULL
pattern_size	Pattern size in bytes
start	Starting index for search
end	End index for search, END for end of string

Returns

Found pattern index, NONE if not found or if pattern_size=0

find() [6/7]

Key find ( const StringBase &  pattern, Key  start = 0, Key  end = END  ) const

inline

Find first occurrence of pattern string.

• Search stops before reaching end index or end of string
• Character at end index is not checked
• Specify search algorithm with: find(StringSearchAlg,const StringBase&,Key,Key) const

Parameters

pattern	Pattern to look for
start	Starting index for search
end	End index for search, END for end of string

Returns

Found pattern index, NONE if not found or if pattern is empty

find() [7/7]

Key find ( StringSearchAlg  alg, const StringBase &  pattern, Key  start = 0, Key  end = END  ) const

inline

Find first occurrence of pattern string using specified algorithm.

• Search stops before reaching end index or end of string
• Character at end index is not checked

Parameters

alg	Search algorithm to use, see StringSearchAlg
pattern	Pattern to look for
start	Starting index for search
end	End index for search, END for end of string

Returns

Found pattern index, NONE if not found or if pattern_size=0

findany() [1/3]

Key findany ( const Item *  items, Size  count, Key  start = 0, Key  end = END  ) const

inlineinherited

Find first occurrence of any given items with forward search.

• This searches for any of given items, using item operator==() for comparisons
• Search stops before reaching end index or end of list

Parameters

items	Items to search for
count	Count of items to search for
start	Starting index for search
end	End index for search, END for end of list

Returns

Found item index or NONE if not found

findany() [2/3]

Key findany ( const char *  chars, Size  count, Key  start = 0, Key  end = END  ) const

inline

Find first occurrence of any given characters with forward search.

• This searches for any one of the given characters
• Search stops before reaching end index or end of string
• Character at end index is not checked

Parameters

chars	Characters to search for, must not contain multi-byte chars
count	Character count to search for
start	Starting index for search
end	End index for search, END for end of list

Returns

Found character index , NONE if not found or if count=0

findany() [3/3]

Key findany ( const StringBase &  chars, Key  start = 0, Key  end = END  ) const

inline

Find first occurrence of any given characters with forward search.

• This searches for any one of the given characters
• Search stops before reaching end index or end of string
• Character at end index is not checked

Parameters

chars	Characters to search for, must not contain multi-byte chars
start	Starting index for search
end	End index for search, END for end of list

Returns

Found character index, NONE if not found or if chars is empty

findanybut() [1/2]

Key findanybut ( const char *  chars, Size  count, Key  start = 0, Key  end = END  ) const

inline

Find first occurrence of any character not listed with forward search.

• This searches for any character not in chars
• Search stops before reaching end index or end of string
• Character at end index is not checked

Parameters

chars	Excluded characters, must not contain multi-byte chars
count	Excluded character count
start	Starting index for search
end	End index for search, END for end of list

Returns

Found character index, NONE if not found

findanybut() [2/2]

Key findanybut ( const StringBase &  chars, Key  start = 0, Key  end = END  ) const

inline

Find first occurrence of any character not listed with forward search.

• This searches for any character not in chars
• Search stops before reaching end index or end of string
• Character at end index is not checked

Parameters

chars	Excluded characters, must not contain multi-byte chars
start	Starting index for search
end	End index for search, END for end of list

Returns

Found character index, NONE if not found

findanybutr() [1/2]

Key findanybutr ( const char *  chars, Size  count, Key  start = 0, Key  end = END  ) const

inline

Find last occurrence of any character not listed with reverse search.

• This searches for any character not in chars
• This does a reverse search starting right before end index
• Character at end index is not checked

Parameters

chars	Excluded characters, must not contain multi-byte chars
count	Excluded character count
start	Starting index for search range – last character checked in reverse search
end	End index for search range (reverse search starting point), END for end of list

Returns

Found character index, NONE if not found

findanybutr() [2/2]

Key findanybutr ( const StringBase &  chars, Key  start = 0, Key  end = END  ) const

inline

Find last occurrence of any character not listed with reverse search.

• This searches for any character not in chars
• This does a reverse search starting right before end index
• Character at end index is not checked

Parameters

chars	Excluded characters, must not contain multi-byte chars
start	Starting index for search range – last character checked in reverse search
end	End index for search range (reverse search starting point), END for end of list

Returns

Found character index, NONE if not found

findanyr() [1/3]

Key findanyr ( const Item *  items, Size  count, Key  start = 0, Key  end = END  ) const

inlineinherited

Find last occurrence of any given items with reverse search.

• This searches for any of given items, using item operator==() for comparisons
• Same as findany() but does reverse search starting right before end index or at last item if end of list
• As with findany(), item at end index is not checked

Parameters

items	Items to search for
count	Count of items to search for
start	Starting index for search range – last item checked in reverse search
end	End index for search range (reverse search starting point), END for end of list

Returns

Found item index or NONE if not found

findanyr() [2/3]

Key findanyr ( const char *  chars, Size  count, Key  start = 0, Key  end = END  ) const

inline

Find last occurrence of any given characters with reverse search.

• This searches for any one of the given characters
• This does a reverse search starting right before end index
• Character at end index is not checked

Parameters

chars	Characters to search for, must not contain multi-byte chars
count	Character count to search for
start	Starting index for search range – last character checked in reverse search
end	End index for search range (reverse search starting point), END for end of list

Returns

Found character index, NONE if not found or if count=0

findanyr() [3/3]

Key findanyr ( const StringBase &  chars, Key  start = 0, Key  end = END  ) const

inline

Find last occurrence of any given characters with reverse search.

• This searches for any one of the given characters
• This does a reverse search starting right before end index
• Character at end index is not checked

Parameters

chars	Characters to search for, must not contain multi-byte chars
start	Starting index for search range – last character checked in reverse search
end	End index for search range (reverse search starting point), END for end of list

Returns

Found character index, NONE if not found or if chars is empty

findnonword()

Key findnonword ( Key  start = 0, Key  end = END  ) const

inline

Find first non-word word character.

• This finds the first character that is NOT a word character
• A word character is a letter, number, or underscore – see cbtWORD

Parameters

start	Starting index for search
end	End index for search, END for end of list

Returns

Found character index, NONE if not found

findnonwordr()

Key findnonwordr ( Key  start = 0, Key  end = END  ) const

inline

Find last non-word character with reverse search.

• This finds the last character that is NOT a word character (with reverse search)
• A word character is a letter, number, or underscore – see cbtWORD

Parameters

start	Starting index for search range – last character checked in reverse search
end	End index for search range (reverse search starting point), END for end of list

Returns

Found character index, NONE if not found

findr() [1/7]

Key findr ( ItemVal  item, Key  start = 0, Key  end = END  ) const

inlineinherited

Find last occurrence of item with reverse search.

• This searches for given item, using item operator==() for comparisons
• This does a reverse search starting right before end index
• Item at end index is not checked

Parameters

item	Item to find
start	Starting index for search range – last item checked in reverse search
end	End index for search range (reverse search starting point), END for end of list

Returns

Found item index or NONE if not found

findr() [2/7]

Key findr ( char  ch ) const

inline

Find last occurrence of character with reverse search.

• This does a reverse search starting right before end index
• Character at end index is not checked

Parameters

ch	Character to find

Returns

Found character index, NONE if not found

findr() [3/7]

Key findr ( char  ch, Key  start, Key  end = END  ) const

inline

Find last occurrence of character with reverse search.

• This does a reverse search starting right before end index
• Character at end index is not checked

Parameters

ch	Character to find
start	Starting index for search range – last character checked in reverse search
end	End index for search range (reverse search starting point), END for end of string

Returns

Found character index or NONE if not found

findr() [4/7]

Key findr ( const char *  pattern, uint  pattern_size, Key  start = 0, Key  end = END  ) const

inline

Find last occurrence of pattern string with reverse search.

• This does a reverse search starting right before end index
• Character at end index is not checked
• Specify search algorithm with: findr(StringSearchAlg,const char*,uint,Key,Key) const

Parameters

pattern	Pointer to pattern to look for, must not be NULL
pattern_size	Pattern size in bytes
start	Starting index for search
end	End index for search, END for end of string

Returns

Found pattern index, NONE if not found or if pattern is empty

findr() [5/7]

Key findr ( StringSearchAlg  alg, const char *  pattern, uint  pattern_size, Key  start = 0, Key  end = END  ) const

inline

Find last occurrence of pattern string with reverse search.

• This does a reverse search starting right before end index
• Character at end index is not checked

Parameters

alg	Search algorithm to use, see StringSearchAlg
pattern	Pointer to pattern to look for, must not be NULL
pattern_size	Pattern size in bytes
start	Starting index for search
end	End index for search, END for end of string

Returns

Found pattern index, NONE if not found or if pattern is empty

findr() [6/7]

Key findr ( const StringBase &  pattern, Key  start = 0, Key  end = END  ) const

inline

Find last occurrence of pattern string with reverse search.

• This does a reverse search starting right before end index
• Character at end index is not checked
• Specify search algorithm with: findr(StringSearchAlg,const StringBase&,Key,Key) const

Parameters

pattern	Pattern to look for
start	Starting index for search
end	End index for search, END for end of string

Returns

Found pattern index, NONE if not found or if pattern is empty

findr() [7/7]

Key findr ( StringSearchAlg  alg, const StringBase &  pattern, Key  start = 0, Key  end = END  ) const

inline

Find last occurrence of pattern string with reverse search.

• This does a reverse search starting right before end index
• Character at end index is not checked

Parameters

alg	Search algorithm to use, see StringSearchAlg
pattern	Pattern to look for
start	Starting index for search
end	End index for search, END for end of string

Returns

Found pattern index, NONE if not found or if pattern is empty

findreplace() [1/6]

Size findreplace ( char  ch, const char *  str, Size  size, Size  max = ALL  )

inline

Find character and replace with string (modifier).

Parameters

ch	Character to find
str	Replacement string pointer
size	Replacement string size
max	Max occurrences to find and replace, ALL for all

Returns

Number of replacements made, 0 if none

findreplace() [2/6]

Size findreplace ( char  ch, const StringBase &  str, Size  max = ALL  )

inline

Find character and replace with string (modifier).

Parameters

ch	Character to find
str	Replacement string
max	Max occurrences to find and replace, ALL for all

Returns

Number of replacements made, 0 if none

findreplace() [3/6]

Size findreplace ( const char *  fstr, Size  fsize, const char *  str, Size  size, Size  max = ALL  )

inline

Find string and replace with string (modifier).

Parameters

fstr	Pointer to string to find and replace
fsize	String size to find and replace
str	Replacement string pointer
size	Replacement string size
max	Max occurrences to find and replace, ALL for all

Returns

Number of replacements made, 0 if none

findreplace() [4/6]

Size findreplace ( const char *  fstr, Size  fsize, const StringBase &  str, Size  max = ALL  )

inline

Find string and replace with string (modifier).

Parameters

fstr	Pointer to string to find and replace
fsize	String size to find and replace
str	Replacement string
max	Max occurrences to find and replace, ALL for all

Returns

Number of replacements made, 0 if none

findreplace() [5/6]

Size findreplace ( const StringBase &  fstr, const StringBase &  str, Size  max = ALL  )

inline

Find string and replace with string (modifier).

Parameters

fstr	String to find and replace
str	Replacement string
max	Max occurrences to find and replace, ALL for all

Returns

Number of replacements made, 0 if none

findreplace() [6/6]

Size findreplace ( const StringBase &  fstr, const char *  str, Size  size, Size  max = ALL  )

inline

Find string and replace with string (modifier).

Parameters

fstr	String to find and replace
str	Replacement string pointer
size	Replacement string size
max	Max occurrences to find and replace, ALL for all

Returns

Number of replacements made, 0 if none

findword()

Key findword ( Key  start = 0, Key  end = END  ) const

inline

Find first word character.

• A word character is a letter, number, or underscore – see cbtWORD

Parameters

start	Starting index for search
end	End index for search, END for end of list

Returns

Found character index, NONE if not found

findwordr()

Key findwordr ( Key  start = 0, Key  end = END  ) const

inline

Find last word character with reverse search.

• A word character is a letter, number, or underscore – see cbtWORD

Parameters

start	Starting index for search range – last character checked in reverse search
end	End index for search range (reverse search starting point), END for end of list

Returns

Found character index, NONE if not found

first()

const Item* first ( ) const

inlineinherited

Get first item (const).

Returns

First item pointer, NULL if empty

firstM()

Item* firstM ( )

inlineinherited

Get first item (mutable).

• Calls unshare(), use advFirst() to skip this

Returns

First item pointer, NULL if empty

getbool() [1/2]

bool getbool ( Error &  error ) const

inline

Convert to bool value for given boolean type.

Fails on bad format, empty, or number overflow.

Format: [WHITESPACE] ["on"|"off"|"yes"|"no"|"true"|"false"|"t"|"f"|DIGITS] [WHITESPACE]

• Result is true if non-zero number – checked using getnum(Error&,int) with T=long, base=0
• Case insensitive

Error codes:

• ENone: success
• EInval: bad format, invalid character, or no digits
• EOutOfBounds: number overflow

Parameters

error

Stores conversion error code, ENone on success [out]

Returns

Converted value on success, partially converted value or 0 on failure

getbool() [2/2]

T getbool ( ) const

inline

Convert to bool value for given boolean type.

Fails on bad format, empty, or number overflow

Format: [WHITESPACE] ["on"|"off"|"yes"|"no"|"true"|"false"|"t"|"f"|DIGITS] [WHITESPACE]

• Result is true if non-zero number – checked using getnum(Error&,int) with T=long, base=0
• Case insensitive

Template Parameters

T	Boolean type to convert to – can be Bool or bool

Returns

Converted value on success, Bool set as null on failure, primitive is false on failure

getnum() [1/2]

T getnum ( Error &  error, int  base = 0  ) const

inline

Convert to number value for given integer type.

Fails on bad format, no digits, or overflow.

Format: [WHITESPACE] ["+"|"-"] ["0x"|"0X"|"x"|"0"] DIGITS [WHITESPACE]

• Base 2-36 supported – Base 0 autodetects hex or octal based on prefix, defaults to decimal
• Base 16 (hex) may use "0x", "0X", or "x" prefix
• Base 8 (octal) may use "0" prefix
• Letters in digits are not case sensitive

Error codes:

• ENone: success
• EInval: bad format, invalid character, or no digits
• EOutOfBounds: number overflow

Template Parameters

T	Basic integer type to convert to – must be primitive like: int32, int, long, uint32, uint, ulong, etc

Parameters

error	Stores conversion error code, ENone on success [out]
base	Conversion base, 0 for autodetect

Returns

Converted value on success, partially converted value or 0 on failure

getnum() [2/2]

T getnum ( int  base = 0 ) const

inline

Convert to number value for given integer type.

Fails on bad format, no digits, or overflow.

Format: [WHITESPACE] ["+"|"-"] ["0x"|"0X"|"x"|"0"] DIGITS [WHITESPACE]

• Base 2-36 supported – Base 0 autodetects hex or octal based on prefix, defaults to decimal
• Base 16 (hex) may use "0x", "0X", or "x" prefix
• Base 8 (octal) may use "0" prefix
• Letters in digits are not case sensitive

Template Parameters

T	Integer type to convert to – can be IntegerT type like Int32, Int, ULong, etc or primitive like int32, int, ulong, etc

Parameters

base	Conversion base, 0 for autodetect

Returns

Converted value on success, IntegerT set as null on failure, primitive is 0 on failure

getnumf() [1/2]

T getnumf ( Error &  error ) const

inline

Convert to floating point number value for given type.

Fails on bad format or no digits.

Format: [WHITESPACE] ("nan" | NUMBER) [WHITESPACE]

• NUMBER: ["+"|"-"] ("inf" | DIGITS ["." DIGITS] [EXPONENT])
  
• EXPONENT: ["+"|"-"] ("e"|"E") DIGITS
• Only decimal (base 10) digits supported
• Not-A-Number ("nan") and infinite ("inf") values are case insensitive

Error codes:

• ENone: success
• EInval: bad format, invalid character, or no digits

Template Parameters

T	Basic floating point type to convert to – must be primitive like: float, double, ldouble

Parameters

error

Stores conversion error code, ENone on success [out]

Returns

Converted value, partially converted value or 0 on failure

getnumf() [2/2]

T getnumf ( ) const

inline

Convert to floating point number value for given type.

Fails on bad format or no digits.

Format: [WHITESPACE] ("nan" | NUMBER) [WHITESPACE]

• NUMBER: ["+"|"-"] ("inf" | DIGITS ["." DIGITS] [EXPONENT])
  
• EXPONENT: ["+"|"-"] ("e"|"E") DIGITS
• Only decimal (base 10) digits supported
• Not-A-Number ("nan") and infinite ("inf") values are case insensitive

Template Parameters

T	Floating point type to convert to – can be FloatT type like Float, FloatD, etc or primitive like float, double, etc

Returns

Converted value on success, FloatT set as null on failure, primitive is 0 on failure

hash()

ulong hash ( ulong  seed = 0 ) const

inlineinherited

Get data hash value.

Parameters

seed	Seed value for hashing multiple values, 0 if none

Returns

Hash value

iend()

Key iend ( Size  offset = 0 ) const

inlineinherited

Get index from last item using offset.

• This simplifies math when computing an index from last item
• This uses the formula: iend = size - 1 - offset

Parameters

offset

Offset from end, 0 for last item, 1 for second-last, etc

Returns

Resulting index, END if offset out of bounds

insert() [1/9]

Size insert ( Key  index, const Item *  data, Size  size  )

inlineinherited

Insert new items copied from data pointer (modifier).

Parameters

index	Insert index, END to append
data	Data to insert
size	Size as item count to insert

Returns

Inserted index

insert() [2/9]

Size insert ( Key  index, const ListBaseType &  data  )

inlineinherited

Insert new items copied from another list (modifier).

Parameters

index	Insert index, END to append
data	Data to insert

Returns

Inserted index

insert() [3/9]

Size insert ( Key  index, const Item &  data  )

inlineinherited

Insert new item (modifier).

Parameters

index	Insert index, END to append
data	Data to insert

Returns

Inserted index

insert() [4/9]

Size insert ( Key  index, char  ch  )

inline

Insert character (modifier).

Parameters

index	Insert index, END to append
ch	Character to insert

Returns

Inserted index

insert() [5/9]

Size insert ( Key  index, char  ch, Size  count  )

inline

Insert copies of the same character (modifier).

Parameters

index	Insert index, END to append
ch	Character to insert
count	Character copies to insert

Returns

Inserted index

insert() [6/9]

Size insert ( Key  index, const ListType &  str  )

inline

Insert from another string (modifier).

Parameters

index	Insert index, END to append
str	String to insert

Returns

Inserted index

insert() [7/9]

Size insert ( Key  index, const StringBase &  str  )

inline

Insert from another string (modifier).

Parameters

index	Insert index, END to append
str	String to insert

Returns

Inserted index

insert() [8/9]

Size insert ( Key  index, const char *  str, Size  size  )

inline

Insert string data (modifier).

Parameters

index	Insert index, END to append
str	String to insert
size	String size as character count to insert

Returns

Inserted index

insert() [9/9]

String& insert ( Key  index, const char *  str  )

inline

Insert null terminated string (modifier).

Parameters

index	Insert index, END to append
str	String to insert – must be terminated

Returns

This

insertn() [1/9]

String& insertn ( Key  index, int  num, int  base = fDEC  )

inline

Insert formatted signed number (modifier).

Parameters

index	Insert index, END to append
num	Number to insert
base	Base to use for formatting

Returns

This

insertn() [2/9]

String& insertn ( Key  index, long  num, int  base = fDEC  )

inline

Insert formatted signed number (modifier).

Parameters

index	Insert index, END to append
num	Number to insert
base	Base to use for formatting

Returns

This

insertn() [3/9]

String& insertn ( Key  index, longl  num, int  base = fDEC  )

inline

Insert formatted signed number (modifier).

Parameters

index	Insert index, END to append
num	Number to insert
base	Base to use for formatting

Returns

This

insertn() [4/9]

String& insertn ( Key  index, uint  num, int  base = fDEC  )

inline

Insert formatted unsigned number (modifier).

Parameters

index	Insert index, END to append
num	Number to insert
base	Base to use for formatting

Returns

This

insertn() [5/9]

String& insertn ( Key  index, ulong  num, int  base = fDEC  )

inline

Insert formatted unsigned number (modifier).

Parameters

index	Insert index, END to append
num	Number to insert
base	Base to use for formatting

Returns

This

insertn() [6/9]

String& insertn ( Key  index, ulongl  num, int  base = fDEC  )

inline

Insert formatted unsigned number (modifier).

Parameters

index	Insert index, END to append
num	Number to insert
base	Base to use for formatting

Returns

This

insertn() [7/9]

String& insertn ( Key  index, float  num, int  precision = fPREC_AUTO  )

inline

Insert formatted floating point number (modifier).

Parameters

index	Insert index, END to append
num	Number to insert
precision	Formatting precision (number of fractional digits), 0 for none, fPREC_AUTO for automatic

Returns

This

insertn() [8/9]

String& insertn ( Key  index, double  num, int  precision = fPREC_AUTO  )

inline

Insert formatted floating point number (modifier).

Parameters

index	Insert index, END to append
num	Number to insert
precision	Formatting precision (number of fractional digits), 0 for none, fPREC_AUTO for automatic

Returns

This

insertn() [9/9]

String& insertn ( Key  index, ldouble  num, int  precision = fPREC_AUTO  )

inline

Insert formatted floating point number (modifier).

Parameters

index	Insert index, END to append
num	Number to insert
precision	Formatting precision (number of fractional digits), 0 for none, fPREC_AUTO for automatic

Returns

This

insertnew()

Size insertnew ( Key  index, Size  size = 1  )

inlineinherited

Insert new items (modifier).

Parameters

index	Insert index, END to append
size	Size as item count to insert

Returns

Inserted index

item()

const Item& item ( Key  index ) const

inlineinherited

Get item at position (const).

• Caution: Results are undefined if index is out of bounds

Parameters

index

Item index

Returns

Given item as read-only (const)

itemM()

char & itemM ( Key  index )

inlineinherited

Get item at position (mutable).

• Calls unshare()
• For best performance, use operator[]() or item() instead for read-only access, or dataM() to get mutable pointer for repeated access
• Caution: Results are undefined if index is out of bounds – though index is checked with assert()

Parameters

index

Item index

Returns

Given item (mutable)

join()

String& join ( const C &  items, char  delim = ','  )

inline

Join list items into delimited string.

• This adds each item to string with delimiters, effectively using convert_add() for conversion
• Delimiter is added before each item except the first
• List item type must be convertible to String via convert_add()

Parameters

items	List items to join
delim	Delimiter to use

joinmap()

String& joinmap ( const C &  map, char  delim = ',', char  kvdelim = '='  )

inline

Join map items into delimited string.

• This adds each item to string with delimiters, using convert_add() for conversion
• Item delimiter is added before each item except the first, Key/Value delimiter is added between keys and values
• Map item key and types must be convertible to String via convert_add()

Parameters

map	Map to join
delim	Item delimiter to use
kvdelim	Key/Value delimiter to use

joinmapq()

String& joinmapq ( const C &  map, char  delim = ',', char  kvdelim = '='  )

inline

Join map items into delimited string, with quoting as needed.

• This adds each item to string with delimiters, using convert_addq() for conversion – key and value are converted separately, and either may be quoted
• Item delimiter is added before each item except the first, Key/Value delimiter is added between keys and values
• Map item key and types must be convertible to String via convert_add()

Parameters

map	Map to join
delim	Item delimiter to use
kvdelim	Key/Value delimiter to use

joinq()

String& joinq ( const C &  items, char  delim = ','  )

inline

Join list items into delimited string, with quoting as needed.

• This adds each item to string with delimiters, effectively using convert_addq() for conversion
• Delimiter is added before each item except the first
• List item type must be convertible to String via convert_addq()
• This analyzes string values to determine the type of quoting needed (if any) so can be slightly slower than join()

Parameters

items	List items to join
delim	Delimiter to use

last()

const Item* last ( ) const

inlineinherited

Get last item (const).

Returns

Last item pointer, NULL if empty

lastM()

Item* lastM ( )

inlineinherited

Get last item (mutable).

• Calls unshare(), use advLast() to skip this

Returns

Last item pointer, NULL if empty

letters()

static const String& letters ( )

inlinestatic

Get string of ASCII letters (A-z).

Returns

String of letters

lettersl()

static const String& lettersl ( )

inlinestatic

Get string of ASCII lowercase letters (a-z).

Returns

String of letters

lettersu()

static const String& lettersu ( )

inlinestatic

Get string of ASCII uppercase letters (A-Z).

Returns

String of letters

move() [1/2]

void move ( Key  dest, Key  index  )

inlineinherited

Move item to position (modifier).

• This will remove item at index and insert it at dest, shifting items in between as needed
• If item is moved left it will be inserted before item at dest
• If item is moved right it will be inserted after item at dest, since items are shifted before insert

Parameters

dest	Destination index to move item to, END to move to end
index	Item index to move from

move() [2/2]

Size move ( Key  dest, ListType &  src, Key  srcindex = 0, Size  size = ALL  )

inlineinherited

Move items from another list.

• Effectively calls unshare() on both this and src, if any items moved

Parameters

dest	Destination index to insert moved items, END for append
src	Source to move from
srcindex	Source index to move items from
size	Size as item count to move from source

null()

bool null ( ) const

inlineinherited

Get whether null.

• Always empty when null

Returns

Whether null

num()

Int num ( int  base = 0 ) const

inline

Convert to number value (signed).

Fails on bad format, no digits, or overflow.

Format: [WHITESPACE] ["+"|"-"] ["0x"|"0X"|"x"|"0"] DIGITS [WHITESPACE]

• Base 2-36 supported – Base 0 autodetects hex or octal based on prefix, defaults to decimal
• Base 16 (hex) may use "0x", "0X", or "x" prefix
• Base 8 (octal) may use "0" prefix
• Letters in digits are not case sensitive

Parameters

base	Conversion base, 0 for autodetect

Returns

Converted value, set as null on failure

numf()

Float numf ( ) const

inline

Convert to number value (floating point).

Fails on bad format or no digits.

Format: [WHITESPACE] ("nan" | NUMBER) [WHITESPACE]

• NUMBER: ["+"|"-"] ("inf" | DIGITS ["." DIGITS] [EXPONENT])
  
• EXPONENT: ["+"|"-"] ("e"|"E") DIGITS
• Only decimal (base 10) digits supported
• Not-A-Number ("nan") and infinite ("inf") values are case insensitive

Returns

Converted value, set as null on failure

numfd()

FloatD numfd ( ) const

inline

Convert to number value (double floating point).

Fails on bad format or no digits.

Format: [WHITESPACE] ("nan" | NUMBER) [WHITESPACE]

• NUMBER: ["+"|"-"] ("inf" | DIGITS ["." DIGITS] [EXPONENT])
  
• EXPONENT: ["+"|"-"] ("e"|"E") DIGITS
• Only decimal (base 10) digits supported
• Not-A-Number ("nan") and infinite ("inf") values are case insensitive

Returns

Converted value, set as null on failure

numfl()

FloatL numfl ( ) const

inline

Convert to number value (ldouble floating point).

Fails on bad format or no digits.

Format: [WHITESPACE] ("nan" | NUMBER) [WHITESPACE]

• NUMBER: ["+"|"-"] ("inf" | DIGITS ["." DIGITS] [EXPONENT])
  
• EXPONENT: ["+"|"-"] ("e"|"E") DIGITS
• Only decimal (base 10) digits supported
• Not-A-Number ("nan") and infinite ("inf") values are case insensitive

Returns

Converted value, set as null on failure

numl()

Long numl ( int  base = 0 ) const

inline

Convert to number value (signed long).

Fails on bad format, no digits, or overflow.

Format: [WHITESPACE] ["+"|"-"] ["0x"|"0X"|"x"|"0"] DIGITS [WHITESPACE]

• Base 2-36 supported – Base 0 autodetects hex or octal based on prefix, defaults to decimal
• Base 16 (hex) may use "0x", "0X", or "x" prefix
• Base 8 (octal) may use "0" prefix
• Letters in digits are not case sensitive

Parameters

base	Conversion base, 0 for autodetect

Returns

Converted value, set as null on failure

numll()

LongL numll ( int  base = 0 ) const

inline

Convert to number value (signed long-long).

Fails on bad format, no digits, or overflow.

Format: [WHITESPACE] ["+"|"-"] ["0x"|"0X"|"x"|"0"] DIGITS [WHITESPACE]

• Base 2-36 supported – Base 0 autodetects hex or octal based on prefix, defaults to decimal
• Base 16 (hex) may use "0x", "0X", or "x" prefix
• Base 8 (octal) may use "0" prefix
• Letters in digits are not case sensitive

Parameters

base	Conversion base, 0 for autodetect

Returns

Converted value, set as null on failure

numu()

UInt numu ( int  base = 0 ) const

inline

Convert to number value (unsigned).

Fails on bad format, no digits, or overflow.

Format: [WHITESPACE] ["+"|"-"] ["0x"|"0X"|"x"|"0"] DIGITS [WHITESPACE]

• Base 2-36 supported – Base 0 autodetects hex or octal based on prefix, defaults to decimal
• Base 16 (hex) may use "0x", "0X", or "x" prefix
• Base 8 (octal) may use "0" prefix
• Letters in digits are not case sensitive
• Negative values are converted to unsigned equivalent

Parameters

base	Conversion base, 0 for autodetect

Returns

Converted value, set as null on failure

numul()

ULong numul ( int  base = 0 ) const

inline

Convert to number value (unsigned long).

Fails on bad format, no digits, or overflow.

Format: [WHITESPACE] ["+"|"-"] ["0x"|"0X"|"x"|"0"] DIGITS [WHITESPACE]

• Base 2-36 supported – Base 0 autodetects hex or octal based on prefix, defaults to decimal
• Base 16 (hex) may use "0x", "0X", or "x" prefix
• Base 8 (octal) may use "0" prefix
• Letters in digits are not case sensitive
• Negative values are converted to unsigned equivalent

Parameters

base	Conversion base, 0 for autodetect

Returns

Converted value, set as null on failure

numull()

ULongL numull ( int  base = 0 ) const

inline

Convert to number value (unsigned long-long).

Fails on bad format, no digits, or overflow.

Format: [WHITESPACE] ["+"|"-"] ["0x"|"0X"|"x"|"0"] DIGITS [WHITESPACE]

• Base 2-36 supported – Base 0 autodetects hex or octal based on prefix, defaults to decimal
• Base 16 (hex) may use "0x", "0X", or "x" prefix
• Base 8 (octal) may use "0" prefix
• Letters in digits are not case sensitive
• Negative values are converted to unsigned equivalent

Parameters

base	Conversion base, 0 for autodetect

Returns

Converted value, set as null on failure

operator!=() [1/4]

bool operator!= ( const ListBaseType &  data ) const

inlineinherited

Inequality operator.

Parameters

data	Data to compare to

Returns

Whether inequal

operator!=() [2/4]

bool operator!= ( const String &  str ) const

inline

Inequality operator.

Parameters

str	String to compare to

Returns

Whether inequal

operator!=() [3/4]

bool operator!= ( const char *  str ) const

inline

Inequality operator.

Parameters

str	String to compare to – must be null terminated

Returns

Whether inequal

operator!=() [4/4]

bool operator!= ( const ListBase< wchar16, T > &  str )

inline

Inequality operator to compare against UTF-16 string.

Template Parameters

T	Inferred from argument

Parameters

str	String to compare to

Returns

Whether inequal

operator()()

char & operator() ( Key  index )

inlineinherited

Get item at position (mutable).

• Calls unshare()
• For best performance, use operator[]() or item() instead for read-only access, or dataM() to get mutable pointer for repeated access
• Caution: Results are undefined if index is out of bounds – though index is checked with assert()

Parameters

index

Item index

Returns

Given item (mutable)

operator<<() [1/36]

String& operator<< ( bool  val )

inline

Append operator.

• Bool value is formatted as either "true" or "false" (without quotes)

Parameters

val	Bool value to append

Returns

This

operator<<() [2/36]

String& operator<< ( char  ch )

inline

Append operator.

• Same as add(char)
• Append operators can be chained
  Example:

  // Clear string and append two characters
  str << vEMPTY << 'a' << 'b';

Parameters

ch	Character to append

Returns

This

operator<<() [3/36]

String& operator<< ( const ListType &  str )

inline

Append operator.

• Same as add(const ListType&)
• Append operators can be chained
  Example:

  // Clear string and append two strings
  str << vEMPTY << str1 << str2;

Parameters

str	String to append

Returns

This

operator<<() [4/36]

String& operator<< ( const StringBase &  str )

inline

Append operator.

• Same as add(const StringBase&)
• Append operators can be chained
  Example:

  // Clear string and append two strings
  str << vEMPTY << str1 << str2;

Parameters

str	String to append

Returns

This

operator<<() [5/36]

String& operator<< ( const char *  str )

inline

Append operator.

• Same as add(const char*)
• Append operators can be chained
  Example:

  // Clear string and append two strings
  str << vEMPTY << "foo" << "bar";

Parameters

str	String pointer to append – must be null terminated

Returns

This

operator<<() [6/36]

String& operator<< ( const ValNull &  val )

inline

Append operator to set as null and empty.

• Same as set()
• Append operators can be chained
  Example:

  // Clear string and append two strings
  str << vNULL << "foo" << "bar";

Parameters

val

vNULL

Returns

This

operator<<() [7/36]

String& operator<< ( const ValEmpty &  val )

inline

Append operator to set as empty but not null.

• Same as setempty()
• Append operators can be chained
  Example:

  // Clear string and append two strings
  str << vEMPTY << "foo" << "bar";

Parameters

val

vEMPTY

Returns

This

operator<<() [8/36]

String& operator<< ( Newline  nl )

inline

Append operator to append newline.

• Append operators can be chained
  Example:

  // Clear string and append string and newline
  str << vEMPTY << "foo" << NL;

Parameters

nl	Newline type, NL for system newline

Returns

This

operator<<() [9/36]

String& operator<< ( Flush  )

inline

Flush output buffer – no-op for string.

• Use param: fFLUSH

Returns

This

operator<<() [10/36]

String& operator<< ( int  num )

inline

Append operator to append formatted number.

• Same as addn(int,int) with base=fDEC
• Append operators can be chained
  Example:

  // Clear string and append a number
  str << vEMPTY << 123;

Parameters

num	Number to format and append

Returns

This

operator<<() [11/36]

String& operator<< ( long  num )

inline

Append operator to append formatted number.

• Same as addn(long,int) with base=fDEC
• Append operators can be chained
  Example:

  // Clear string and append a number
  str << vEMPTY << 123;

Parameters

num	Number to format and append

Returns

This

operator<<() [12/36]

String& operator<< ( longl  num )

inline

Append operator to append formatted number.

• Same as addn(longl,int) with base=fDEC
• Append operators can be chained
  Example:

  // Clear string and append a number
  str << vEMPTY << 123;

Parameters

num	Number to format and append

Returns

This

operator<<() [13/36]

String& operator<< ( uint  num )

inline

Append operator to append formatted number.

• Same as addn(uint,int) with base=fDEC
• Append operators can be chained
  Example:

  // Clear string and append a number
  str << vEMPTY << 123;

Parameters

num	Number to format and append

Returns

This

operator<<() [14/36]

String& operator<< ( ulong  num )

inline

Append operator to append formatted number.

• Same as addn(ulong,int) with base=fDEC
• Append operators can be chained
  Example:

  // Clear string and append a number
  str << vEMPTY << 123;

Parameters

num	Number to format and append

Returns

This

operator<<() [15/36]

String& operator<< ( ulongl  num )

inline

Append operator to append formatted number.

• Same as addn(ulongl,int) with base=fDEC
• Append operators can be chained
  Example:

  // Clear string and append a number
  str << vEMPTY << 123;

Parameters

num	Number to format and append

Returns

This

operator<<() [16/36]

String& operator<< ( float  num )

inline

Append operator to append formatted number.

• Same as addn(float,int) with precision=fPREC_AUTO
• Append operators can be chained
  Example:

  // Clear string and append a number
  str << vEMPTY << 123.4;

Parameters

num	Number to format and append

Returns

This

operator<<() [17/36]

String& operator<< ( double  num )

inline

Append operator to append formatted number.

• Same as addn(double,int) with precision=fPREC_AUTO
• Append operators can be chained
  Example:

  // Clear string and append a number
  str << vEMPTY << 123.4;

Parameters

num	Number to format and append

Returns

This

operator<<() [18/36]

String& operator<< ( ldouble  num )

inline

Append operator to append formatted number.

• Same as addn(ldouble,int) with precision=fPREC_AUTO
• Append operators can be chained
  Example:

  // Clear string and append a number
  str << vEMPTY << 123.4;

Parameters

num	Number to format and append

Returns

This

operator<<() [19/36]

String& operator<< ( const FmtChar &  fmt )

inline

Append operator to append formatted character field.

Parameters

fmt	Character info

Returns

This

operator<<() [20/36]

String& operator<< ( const FmtString &  fmt )

inline

Append operator to append formatted string field.

Parameters

fmt	String formatting info

Returns

This

operator<<() [21/36]

String& operator<< ( const FmtStringWrap &  fmt )

inline

Append operator to append formatted wrapped string column.

Parameters

fmt	String formatting info

Returns

This

operator<<() [22/36]

String& operator<< ( const FmtShort &  fmt )

inline

Append operator to append formatted number field.

Parameters

fmt	Number info

Returns

This

operator<<() [23/36]

String& operator<< ( const FmtInt &  fmt )

inline

Append operator to append formatted number field.

Parameters

fmt	Number info

Returns

This

operator<<() [24/36]

String& operator<< ( const FmtLong &  fmt )

inline

Append operator to append formatted number field.

Parameters

fmt	Number info

Returns

This

operator<<() [25/36]

String& operator<< ( const FmtLongL &  fmt )

inline

Append operator to append formatted number field.

Parameters

fmt	Number info

Returns

This

operator<<() [26/36]

String& operator<< ( const FmtUShort &  fmt )

inline

Append operator to append formatted number field.

Parameters

fmt	Number info

Returns

This

operator<<() [27/36]

String& operator<< ( const FmtUInt &  fmt )

inline

Append operator to append formatted number field.

Parameters

fmt	Number info

Returns

This

operator<<() [28/36]

String& operator<< ( const FmtULong &  fmt )

inline

Append operator to append formatted number field.

Parameters

fmt	Number info

Returns

This

operator<<() [29/36]

String& operator<< ( const FmtULongL &  fmt )

inline

Append operator to append formatted number field.

Parameters

fmt	Number info

Returns

This

operator<<() [30/36]

String& operator<< ( const FmtFloat &  fmt )

inline

Append operator to append formatted number field.

Parameters

fmt	Number info

Returns

This

operator<<() [31/36]

String& operator<< ( const FmtFloatD &  fmt )

inline

Append operator to append formatted number field.

Parameters

fmt	Number info

Returns

This

operator<<() [32/36]

String& operator<< ( const FmtFloatL &  fmt )

inline

Append operator to append formatted number field.

Parameters

fmt	Number info

Returns

This

operator<<() [33/36]

String& operator<< ( const FmtFieldNum< T > &  fmt )

inline

Append operator to append formatted number field.

Parameters

fmt	Number info

Returns

This

operator<<() [34/36]

String& operator<< ( const FmtFieldFloat< T > &  fmt )

inline

Append operator to append formatted number field.

Parameters

fmt	Number info

Returns

This

operator<<() [35/36]

String& operator<< ( const FmtPtr &  fmtptr )

inline

Append operator to append formatted pointer field.

Parameters

fmtptr

Pointer info

Returns

This

operator<<() [36/36]

String& operator<< ( const FmtDump &  fmt )

inline

Append operator to append data dump.

Parameters

fmt

Dump info

Returns

This

operator=() [1/11]

String& operator= ( String &&  src )

inline

Move assignment operator (C++11).

Parameters

src	Source to move

Returns

This

operator=() [2/11]

String& operator= ( const char16_t *  str )

inline

Assignment operator to set and convert from terminated UTF-16 string.

• This calls set_unicode(const char16_t*,UtfMode)

Parameters

str	UTF-16 string, NULL to set as null

Returns

This

operator=() [3/11]

String& operator= ( const String &  str )

inline

Assignment operator.

• Makes shared copy if possible – see Sharing

Parameters

str	String to copy

Returns

This

operator=() [4/11]

String& operator= ( const ListType &  str )

inline

Assignment operator.

• Makes shared copy if possible – see Sharing

Parameters

str	String to copy

Returns

This

operator=() [5/11]

String& operator= ( const ListType *  str )

inline

Assignment operator for pointer.

• Makes shared copy if possible – see Sharing

Parameters

str	String pointer to copy from, calls set() if null

Returns

This

operator=() [6/11]

String& operator= ( const StringBase &  data )

inline

Assignment operator to copy from base list type.

• This always makes an unshared copy
• For best performance (and less safety) reference substring instead with set(const char*,Size)

Parameters

data	Data to copy

Returns

This

operator=() [7/11]

String& operator= ( const char *  str )

inline

Assignment operator for null terminated string.

• Caution: Uses Unsafe Pointer Referencing
• See operator=(const PtrBase<char>&) for best safety, use Ptr<char> to wrap raw pointer

Parameters

str	String pointer, calls set() if null – must be terminated

Returns

This

operator=() [8/11]

String& operator= ( const PtrBase< char > &  str )

inline

Assignment operator to copy from managed pointer with null terminated string.

• This always makes an unshared copy
• For best performance (and less safety) reference substring instead with operator=(const char*)
• Use Ptr<char> to wrap raw pointer

Parameters

str	String pointer, calls set() if null – must be terminated

Returns

This

operator=() [9/11]

String& operator= ( const ListBase< wchar16, T > &  str )

inline

Assignment operator to convert from UTF-16 string to UTF-8 string.

• This calls set_unicode()

Parameters

str	UTF-16 string to convert from

Returns

This

operator=() [10/11]

String& operator= ( const ValNull &  )

inline

Assignment operator to set as null and empty.

• Same as set()

Example:

str = vNULL;

Returns

This

operator=() [11/11]

String& operator= ( const ValEmpty &  )

inline

Assignment operator to set as empty but not null.

• Same as setempty()

Example:

str = vEMPTY;

Returns

This

operator==() [1/4]

bool operator== ( const ListBaseType &  data ) const

inlineinherited

Equality operator.

Parameters

data	Data to compare to

Returns

Whether equal

operator==() [2/4]

bool operator== ( const String &  str ) const

inline

Equality operator.

Parameters

str	String to compare to

Returns

Whether equal

operator==() [3/4]

bool operator== ( const char *  str ) const

inline

Equality operator.

Parameters

str	String to compare to – must be null terminated

Returns

Whether equal

operator==() [4/4]

bool operator== ( const ListBase< wchar16, T > &  str )

inline

Equality operator to compare against UTF-16 string.

Template Parameters

T	Inferred from argument

Parameters

str	String to compare to

Returns

Whether equal

operator[]()

const Item& operator[] ( Key  index ) const

inlineinherited

Get item at position (const).

• Caution: Results are undefined if index is out of bounds

Parameters

index

Item index

Returns

Given item as read-only (const)

pop() [1/3]

bool pop ( char &  item, Key  index  )

inlineinherited

Pop a copy of given item (modifier).

• This copies given item then removes the original

Parameters

item	Stores popped item [out]
index	Index to pop

Returns

Whether successful, false if empty or bad index

pop() [2/3]

bool pop ( char &  item )

inlineinherited

Pop a copy of last item (stack) (modifier).

• This copies last item then removes the original
• For best performance use pop() to avoid the copy operation

Parameters

item	Stores popped item [out]

Returns

Whether successful, false if empty

pop() [3/3]

const Item* pop ( )

inlineinherited

Pop last item (stack).

• This slices out and pops the last item
• Caution: Removing sliced item will invalidate the returned pointer – see unslice() and unshare()

Returns

Popped item pointer (const), NULL if empty

popq() [1/2]

bool popq ( char &  item )

inlineinherited

Pop a copy of first item (queue) (modifier).

• This copies first item then removes the original
• For best performance use popq() to avoid the copy operation

Parameters

item	Stores popped item [out]

Returns

Whether successful, false if empty

popq() [2/2]

const Item* popq ( )

inlineinherited

Pop first item (queue).

• This slices out and pops the first item
• Caution: Removing sliced item will invalidate the returned pointer – see unslice() and unshare()

Returns

Popped item pointer (const), NULL if empty

prepend() [1/7]

ListType& prepend ( const Item *  data, Size  size  )

inlineinherited

Prepend new items copied from data pointer (modifier).

• Effectively calls unshare()
• Removes items sliced from beginning – see unslice()

Parameters

data	Data to prepend
size	Size as item count to prepend

Returns

This

prepend() [2/7]

String& prepend ( char  ch )

inline

Prepend character (modifier).

Parameters

ch	Character to prepend

Returns

This

prepend() [3/7]

String& prepend ( char  ch, Size  count  )

inline

Prepend copies of the same character (modifier).

Parameters

ch	Character to prepend
count	Character copies to prepend

Returns

This

prepend() [4/7]

String& prepend ( const ListType &  str )

inline

Prepend from another string (modifier).

Parameters

str	String to prepend

Returns

This

prepend() [5/7]

String& prepend ( const StringBase &  str )

inline

Prepend from another string (modifier).

Parameters

str	String to prepend

Returns

This

prepend() [6/7]

String& prepend ( const char *  str, Size  size  )

inline

Prepend from string pointer (modifier).

Parameters

str	String to prepend
size	String size as character count to prepend

Returns

This

prepend() [7/7]

String& prepend ( const char *  str )

inline

Prepend null terminated string (modifier).

Parameters

str	String to prepend – must be terminated

Returns

This

prependn() [1/9]

String& prependn ( int  num, int  base = fDEC  )

inline

Prepend formatted signed number (modifier).

Parameters

num	Number to prepend
base	Base to use for formatting

Returns

This

prependn() [2/9]

String& prependn ( long  num, int  base = fDEC  )

inline

Prepend formatted signed number (modifier).

Parameters

num	Number to prepend
base	Base to use for formatting

Returns

This

prependn() [3/9]

String& prependn ( longl  num, int  base = fDEC  )

inline

Prepend formatted signed number (modifier).

Parameters

num	Number to prepend
base	Base to use for formatting

Returns

This

prependn() [4/9]

String& prependn ( uint  num, int  base = fDEC  )

inline

Prepend formatted unsigned number (modifier).

Parameters

num	Number to prepend
base	Base to use for formatting

Returns

This

prependn() [5/9]

String& prependn ( ulong  num, int  base = fDEC  )

inline

Prepend formatted unsigned number (modifier).

Parameters

num	Number to prepend
base	Base to use for formatting

Returns

This

prependn() [6/9]

String& prependn ( ulongl  num, int  base = fDEC  )

inline

Prepend formatted unsigned number (modifier).

Parameters

num	Number to prepend
base	Base to use for formatting

Returns

This

prependn() [7/9]

String& prependn ( float  num, int  precision = fPREC_AUTO  )

inline

Prepend formatted floating point number (modifier).

Parameters

num	Number to prepend
precision	Formatting precision (number of fractional digits), 0 for none, fPREC_AUTO for automatic

Returns

This

prependn() [8/9]

String& prependn ( double  num, int  precision = fPREC_AUTO  )

inline

Prepend formatted floating point number (modifier).

Parameters

num	Number to prepend
precision	Formatting precision (number of fractional digits), 0 for none, fPREC_AUTO for automatic

Returns

This

prependn() [9/9]

String& prependn ( ldouble  num, int  precision = fPREC_AUTO  )

inline

Prepend formatted floating point number (modifier).

Parameters

num	Number to prepend
precision	Formatting precision (number of fractional digits), 0 for none, fPREC_AUTO for automatic

Returns

This

prependnew()

ListType& prependnew ( Size  size = 1 )

inlineinherited

Prepend new items (modifier).

• Effectively calls unshare()
• Removes items sliced from beginning – see unslice()

Parameters

size	Size as item count to prepend

Returns

This

prependsep()

String& prependsep ( char  delim = ',' )

inline

Prepend separator/delimiter if needed (modifier).

• This will only prepend given delim if not empty and not already starting with delim

Parameters

delim

Delimiter to prepend

Returns

This

ref() [1/3]

void ref ( const ListType &  data )

inlineprotectedinherited

Set as reference to another list.

Parameters

data	Data to reference

ref() [2/3]

void ref ( const ListType &  data, Size  index, Size  size  )

inlineprotectedinherited

Set as sliced reference to another list.

Parameters

data	Data to reference
index	Start index of data, END to set as empty
size	Size as item count, ALL for all from index

ref() [3/3]

void ref ( const Item *  data, Size  size, bool  term = false  )

inlineprotectedinherited

Set as reference to given data.

Parameters

data	Data to reference
size	Data size
term	Whether referenced data is terminated

remove()

Size remove ( Key  index, Size  size = 1  )

inlineinherited

Remove items (modifier).

Parameters

index	Remove index
size	Remove size, ALL for all items from index

Returns

Number of items removed

replace() [1/4]

ListType& replace ( Key  index, Size  rsize, const Item *  data, Size  size  )

inlineinherited

Replace items with new data (modifier).

Parameters

index	Start index to replace
rsize	Size as item count from index to replace, ALL for all items from index
data	Replacement data to copy
size	Replacement data size as item count

Returns

This

replace() [2/4]

String& replace ( Key  index, Size  rsize, const StringBase &  str  )

inline

Replace characters with string (modifier).

Parameters

index	Start index to replace
rsize	Size as item count from index to replace, ALL for all items from index
str	Replacement string to copy – which may refer to a substring of this, as long as it doesn't overlap with the part being replaced

Returns

This

replace() [3/4]

String& replace ( Key  index, Size  rsize, const char *  str, Size  size  )

inline

Replace characters with string (modifier).

Parameters

index	Start index to replace
rsize	Size as item count from index to replace, ALL for all items from index
str	Replacement string to copy – which may refer to a substring of this, as long as it doesn't overlap with the part being replaced
size	Replacement string size as character count

Returns

This

replace() [4/4]

String& replace ( Key  index, Size  rsize, const char *  str  )

inline

Replace characters with string (modifier).

Parameters

index	Start index to replace
rsize	Size as item count from index to replace, ALL for all items from index
str	Replacement string to copy – must be terminated

Returns

This

reserve() [1/2]

ListType& reserve ( Size  size, bool  prefer_realloc = false  )

inlineinherited

Reserve capacity for additional items (modifier).

• Use to make buffer unique (not shared) and writable while reserving extra space
• This effectively calls unshare(), though may still be sliced if prefer_realloc is true

Parameters

size	Size as item count to reserve
prefer_realloc	Advanced: True to prefer realloc for certain conditition where would otherwise unslice via alloc and move to new buffer

Returns

This

reserve() [2/2]

String& reserve ( Size  size, bool  prefer_realloc = false  )

inline

Reserve capacity for additional items (modifier).

• Use to make buffer unique (not shared) and writable while reserving extra space
• This effectively calls unshare(), though may still be sliced if prefer_realloc is true

Parameters

size	Size as item count to reserve
prefer_realloc	Advanced: True to prefer realloc for certain conditition where would otherwise unslice via alloc and move to new buffer

Returns

This

resize() [1/2]

ListType& resize ( Size  size )

inlineinherited

Resize while preserving existing data (modifier).

• This adds/removes items as needed until given size is reached
• Effectively calls unshare()
• Advanced: See advBuffer() for getting writable pointer to buffer
• Advanced: See advResize() for best performance in certain POD cases

Parameters

size	New size as item count

Returns

This

resize() [2/2]

String& resize ( Size  size )

inline

Resize while preserving existing data (modifier).

• This adds/removes items as needed until given size is reached
• Effectively calls unshare()
• Advanced: See advBuffer() for getting writable pointer to buffer
• Advanced: See advResize() for best performance in certain POD cases

Parameters

size	New size as item count

Returns

This

reverse()

String& reverse ( )

inline

Reverse item order (modifier).

• Calls unshare()

Returns

This

set() [1/13]

ListType& set ( const Item *  data, Size  size  )

inlineinherited

Set from data pointer.

• Caution: Uses Unsafe Pointer Referencing

Parameters

data	Data pointer to use
size	Data size as item count

Returns

This

set() [2/13]

ListType& set ( const PtrBase< Item > &  data, Size  size  )

inlineinherited

Set from managed data pointer.

• Caution: Uses Unsafe Pointer Referencing

Parameters

data	Data pointer to copy
size	Data size as item count

set() [3/13]

ListType& set ( const ListType &  data )

inlineinherited

Set from another list.

• Makes shared copy if possible – see Sharing

Parameters

data	Data to copy

Returns

This

set() [4/13]

ListType& set ( const ListType &  data, Key  index, Key  size = ALL  )

inlineinherited

Set from subset of another list.

• Makes shared copy if possible – see Sharing

Parameters

data	Data to copy
index	Start index of data, END to set as empty
size	Data size as item count, ALL for all from index

Returns

This

set() [5/13]

ListType& set ( const ListBaseType &  data, Key  index = 0, Key  size = ALL  )

inlineinherited

Set as copy of sublist.

• For best performance (and less safety) reference sublist instead with set(const Item*,Size)

Parameters

data	Data to copy
index	Start index of sublist data, END to set as empty
size	Data size as item count, ALL for all from index

Returns

This

set() [6/13]

String& set ( )

inline

Set as null and empty.

• Append operators can be chained
  Example:

  // Clear string and append two characters
  str.set() << 'a' << 'b';

Returns

This

set() [7/13]

String& set ( const ListType &  str )

inline

Set from another string.

• Makes shared copy if possible – see Sharing

Parameters

str	String to copy

Returns

This

set() [8/13]

String& set ( const ListType &  str, Key  index, Key  size = ALL  )

inline

Set from substring of another string.

• Makes shared copy if possible – see Sharing

Parameters

str	String to copy
index	Start index of data, END to set as empty
size	Data size as item count, ALL for all from index

Returns

This

set() [9/13]

String& set ( const StringBase &  data, Key  index = 0, Key  size = ALL  )

inline

Set as copy of substring.

• This always makes an unshared copy
• For best performance (and less safety) reference substring instead with set(const char*,Size)

Parameters

data	Data to copy
index	Start index of substring data, END to set as empty
size	Data size as item count, ALL for all from index

Returns

This

set() [10/13]

String& set ( const char *  str, Size  size  )

inline

Set from string pointer.

• Caution: Uses Unsafe Pointer Referencing
• For best safety use copy(const char*,Size)

Parameters

str	String pointer, calls set() if null
size	String size as character count

Returns

This

set() [11/13]

String& set ( const PtrBase< char > &  str, Size  size  )

inline

Set from managed string pointer.

• This always makes an unshared copy
• For best performance (and less safety) reference substring instead with set(const char*,Size)
• Use Ptr<char> to wrap raw pointer

Parameters

str	String pointer, calls set() if null
size	String size as character count

set() [12/13]

String& set ( const char *  str )

inline

Set from terminated string.

• Caution: Uses Unsafe Pointer Referencing
• For best safety use set(const PtrBase<char>&,Size) or use Ptr<char> to wrap raw pointer

Parameters

str	String pointer, calls set() if null – must be terminated

Returns

This

set() [13/13]

String& set ( const PtrBase< char > &  str )

inline

Set as copy of null terminated string from managed pointer.

• This always makes an unshared copy
• For best performance (and less safety) reference substring instead with set(const char*)
• Use Ptr<char> to wrap raw pointer

Parameters

str	String pointer, calls set() if null – must be terminated

set2() [1/4]

ListType& set2 ( const ListType &  data, Key  index1, Key  index2  )

inlineinherited

Set from subset of another list using start/end positions.

• Makes shared copy if possible – see Sharing
• If index2 < index1 then index2 will be set to index1 (empty sublist)

Parameters

data	Data to copy
index1	Start index of new slice, END to slice all items from beginning
index2	End index of new slice (this item not included), END for all after index1

Returns

This

set2() [2/4]

ListType& set2 ( const ListBaseType &  data, Key  index1, Key  index2  )

inlineinherited

Set as copy of sublist using start/end positions.

• For best performance (and less safety) reference sublist instead with set(const Item*,Size)

Parameters

data	Data to copy
index1	Start index of sublist data, END to set as empty
index2	End index of sublist data (this item not included), END for all after index1

Returns

This

set2() [3/4]

String& set2 ( const ListType &  str, Key  index1, Key  index2  )

inline

Set from substring of another string using start/end positions.

• Makes shared copy if possible – see Sharing
• If index2 < index1 then index2 will be set to index1 (empty sublist)
• Use unshare() afterwards to make a full (unshared) copy

Parameters

str	String to copy
index1	Start index of data, END to set as empty
index2	End index of data (this item not included), END for all after index1

Returns

This

set2() [4/4]

String& set2 ( const StringBase &  data, Key  index1, Key  index2  )

inline

Set and reference sublist using start/end positions.

• Caution: This will reference the same pointer as given sublist, so pointer must remain valid
• Use unshare() afterwards to make a full (unshared) copy

Parameters

data	Data to reference
index1	Start index of sublist data, END to set as empty
index2	End index of sublist data (this item not included), END for all after index1

Returns

This

set_unicode() [1/4]

bool set_unicode ( const wchar16 *  str, Size  size, UtfMode  mode = umREPLACE_INVALID  )

inline

Set as normal UTF-8 string converted from a raw UTF-16 string.

• Windows: See also: set_win32(const WCHAR*,int)

Parameters

str	Pointer to UTF-16 string to convert from, NULL to set as null
size	String size to convert from, as wchar16 length (not bytes), ignored if str is 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 the Unicode Replacement Character (code: 0xFFFD) umSKIP_INVALID - Invalid UTF-16 values are skipped and ignored umSTRICT - Stop on invalid input with an error

Returns

Whether successful, false if stopped on invalid input with umSTRICT

set_unicode() [2/4]

bool set_unicode ( const wchar16 *  str, UtfMode  mode = umREPLACE_INVALID  )

inline

Set as normal UTF-8 string converted from a raw terminated UTF-16 string.

• Windows: See also: set_win32(const WCHAR*)

Parameters

str	Pointer to UTF-16 string to convert from, NULL to set as null, otherwise must be terminated
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 the Unicode Replacement Character (code: 0xFFFD) umSKIP_INVALID - Invalid UTF-16 values are skipped and ignored umSTRICT - Stop on invalid input with an error

Returns

Whether successful, false if stopped on invalid input with umSTRICT

set_unicode() [3/4]

bool set_unicode ( const char16_t *  str, Size  size, UtfMode  mode = umREPLACE_INVALID  )

inline

Set as normal UTF-8 string converted from a raw UTF-16 string.

• Windows: See also: set_win32(const WCHAR*,int)

Parameters

str	Pointer to UTF-16 string to convert from, NULL to set as null
size	String size to convert from, as wchar16 length (not bytes), ignored if str is 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 the Unicode Replacement Character (code: 0xFFFD) umSKIP_INVALID - Invalid UTF-16 values are skipped and ignored umSTRICT - Stop on invalid input with an error

Returns

Whether successful, false if stopped on invalid input with umSTRICT

set_unicode() [4/4]

bool set_unicode ( const char16_t *  str, UtfMode  mode = umREPLACE_INVALID  )

inline

Set as normal UTF-8 string converted from a raw terminated UTF-16 string.

• Windows: See also: set_win32(const WCHAR*)

Parameters

str	Pointer to UTF-16 string to convert from, NULL to set as null, otherwise must be terminated
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 the Unicode Replacement Character (code: 0xFFFD) umSKIP_INVALID - Invalid UTF-16 values are skipped and ignored umSTRICT - Stop on invalid input with an error

Returns

Whether successful, false if stopped on invalid input with umSTRICT

set_win32() [1/2]

String& set_win32 ( const WCHAR *  str, int  size  )

inline

Set as normal (UTF-8) string converted from a Windows UTF-16 (WCHAR) string (Windows only).

• This uses the Win32 API to do the conversion
• Invalid UTF-16 values are replaced with UNICODE_REPLACEMENT_CHAR
• For terminated UTF-16 strings see: set_win32(const WCHAR*)

Parameters

str	UTF-16 string to convert, NULL to set as null
size	String size in wide chars, 0 for empty

Returns

This

set_win32() [2/2]

String& set_win32 ( const WCHAR *  str )

inline

Set as normal (UTF-8) string converted from a terminated Windows UTF-16 (WCHAR) string (Windows only).

• This uses the Win32 API to do the conversion, and so is only supported in Windows
• Invalid UTF-16 values are replaced with UNICODE_REPLACEMENT_CHAR
• For non-terminated UTF-16 strings see: set_win32(const WCHAR*,int)

Parameters

str	UTF-16 string to convert (must be terminated), NULL to set as null

Returns

This

setempty()

String& setempty ( )

inline

Set as empty but not null.

• Append operators can be chained
  Example:

  // Set as empty then append two characters
  str.setempty() << 'a' << 'b';

Returns

This

setn() [1/9]

String& setn ( int  num, int  base = fDEC  )

inline

Set as formatted signed number (modifier).

Parameters

num	Number to set
base	Base to use for formatting

Returns

This

setn() [2/9]

String& setn ( long  num, int  base = fDEC  )

inline

Set as formatted signed number (modifier).

Parameters

num	Number to set
base	Base to use for formatting

Returns

This

setn() [3/9]

String& setn ( longl  num, int  base = fDEC  )

inline

Set as formatted signed number (modifier).

Parameters

num	Number to set
base	Base to use for formatting

Returns

This

setn() [4/9]

String& setn ( uint  num, int  base = fDEC  )

inline

Set as formatted unsigned number (modifier).

Parameters

num	Number to set
base	Base to use for formatting

Returns

This

setn() [5/9]

String& setn ( ulong  num, int  base = fDEC  )

inline

Set as formatted unsigned number (modifier).

Parameters

num	Number to set
base	Base to use for formatting

Returns

This

setn() [6/9]

String& setn ( ulongl  num, int  base = fDEC  )

inline

Set as formatted unsigned number (modifier).

Parameters

num	Number to set
base	Base to use for formatting

Returns

This

setn() [7/9]

String& setn ( float  num, int  precision = fPREC_AUTO  )

inline

Set as formatted floating point number (modifier).

Parameters

num	Number to set
precision	Formatting precision (number of fractional digits), 0 for none, fPREC_AUTO for automatic

Returns

This

setn() [8/9]

String& setn ( double  num, int  precision = fPREC_AUTO  )

inline

Set as formatted floating point number (modifier).

Parameters

num	Number to set
precision	Formatting precision (number of fractional digits), 0 for none, fPREC_AUTO for automatic

Returns

This

setn() [9/9]

String& setn ( ldouble  num, int  precision = fPREC_AUTO  )

inline

Set as formatted floating point number (modifier).

Parameters

num	Number to set
precision	Formatting precision (number of fractional digits), 0 for none, fPREC_AUTO for automatic

Returns

This

shared()

bool shared ( ) const

inlineinherited

Get whether shared.

• Data is shared when referencing external data or buffer is allocated and shared (reference count > 1)

Returns

Whether shared

size()

Size size ( ) const

inlineinherited

Get size.

Returns

Size as item count

slice() [1/4]

ListType& slice ( Key  index )

inlineinherited

Slice beginning items.

• This non-destructively trims beginning items

Parameters

index

Start index of new slice, END to slice (remove) all items from beginning

Returns

This

slice() [2/4]

ListType& slice ( Key  index, Size  size  )

inlineinherited

Slice to given sublist.

• This non-destructively trims beginning and/or ending items

Parameters

index	Start index of new slice, END to slice (remove) all items from beginning
size	Slice size as item count, ALL for all from index

Returns

This

slice() [3/4]

String& slice ( Key  index )

inline

Slice beginning items.

• This non-destructively trims beginning items

Parameters

index

Start index of new slice, END to slice (remove) all items from beginning

Returns

This

slice() [4/4]

String& slice ( Key  index, Size  size  )

inline

Slice to given sublist.

• This non-destructively trims beginning and/or ending items

Parameters

index	Start index of new slice, END to slice (remove) all items from beginning
size	Slice size as item count, ALL for all from index

Returns

This

slice2() [1/2]

ListType& slice2 ( Key  index1, Key  index2  )

inlineinherited

Slice to given sublist using start/end positions.

• This non-destructively trims beginning and/or ending items
• If index2 < index1 then index2 will be set to index1 (empty sublist)

Parameters

index1	Start index of new slice, END to slice all items from beginning
index2	End index of new slice (this item not included), END for all after index1

Returns

This

slice2() [2/2]

String& slice2 ( Key  index1, Key  index2  )

inline

Slice to given sublist using start/end positions.

• This non-destructively trims beginning and/or ending items
• If index2 < index1 then index2 will be set to index1 (empty sublist)

Parameters

index1	Start index of new slice, END to slice all items from beginning
index2	End index of new slice (this item not included), END for all after index1

Returns

This

split() [1/4]

bool split ( char  delim, T1 &  left, T2 &  right  ) const

inline

Split at first occurrence of delimiter into left/right substrings.

• Template types are automatically deduced from arguments
• For more advanced parsing see StrTok

Template Parameters

T1	String type to store left substring
T2	String type to store right substring

Parameters

delim	Delimiter to find
left	Set to substring before delim, set to this if not found [out]
right	Set to substring after delim, null if not found [out]

Returns

Whether successful, false if delim not found

split() [2/4]

bool split ( char  delim, T1 &  left  ) const

inline

Split at first occurrence of delimiter into left substring.

• Template types are automatically deduced from arguments
• For more advanced parsing see StrTok

Template Parameters

T1	String type to store left substring

Parameters

delim	Delimiter to find
left	Set to substring before delim, set to this if not found [out]

Returns

Whether successful, false if delim not found

split() [3/4]

bool split ( char  delim, ValNull  left, T2 &  right  ) const

inline

Split at first occurrence of delimiter into right substring.

• Template types are automatically deduced from arguments
• For more advanced parsing see StrTok

Template Parameters

T2	String type to store right substring

Parameters

delim	Delimiter to find
left	vNULL (ignored)
right	Set to substring after delim, null if not found [out]

Returns

Whether successful, false if delim not found

split() [4/4]

C::Size split ( C &  items, char  delim = ','  ) const

inline

Split delimited string into item list using given tokenizer.

• This tokenizes and adds each item to list, using convert() for conversion to list item type
• String must be convertible to list item type via convert()
• See join() to join list back into string

Template Parameters

Tok	Tokenizer to use, such as StrTok
C	List container for items – inferred from items parameter

Parameters

items	List to add items to [in/out]
delim	Delimiter to use

splitat() [1/3]

bool splitat ( Key  index, T1 &  left, T2 &  right  ) const

inlineinherited

Split into left/right sublists at index.

• Can use methods like find() or findany() for index
• Template types are automatically deduced from arguments
• For more advanced parsing see StrTok

Template Parameters

T1	List type to store left sublist
T2	List type to store right sublist

Parameters

index	Index to split at, bad index (NONE or out-of-bounds) splits at end
left	Set to sublist before index, set to this if bad index [out]
right	Set to sublist after index, null if bad index [out]

Returns

Whether successful, false if bad index

splitat() [2/3]

bool splitat ( Key  index, T1 &  left  ) const

inlineinherited

Split into left sublist at index.

• Can use methods like find() or findany() for index
• Template types are automatically deduced from arguments
• For more advanced parsing see StrTok

Template Parameters

T1	List type to store left sublist

Parameters

index	Index to split at, bad index (NONE or out-of-bounds) splits at end
left	Set to sublist before index, set to this if bad index [out]

Returns

Whether successful, false if bad index

splitat() [3/3]

bool splitat ( Key  index, ValNull  left, T2 &  right  ) const

inlineinherited

Split into right sublist at index.

• Can use methods like find() or findany() for index
• Template types are automatically deduced from arguments
• For more advanced parsing see StrTok

Template Parameters

T2	List type to store right sublist

Parameters

index	Index to split at, bad index (NONE or out-of-bounds) splits at end
left	vNULL (ignored)
right	Set to sublist after index, null if bad index [out]

Returns

Whether successful, false if bad index

splitat_setl() [1/2]

bool splitat_setl ( Key  index )

inlineinherited

Split at index and set as left sublist.

• Can use methods like find() or findany() for index
• Sets this to sublist before index, unchanged if bad index [out]

Parameters

index

Index to split at, bad index (NONE or out-of-bounds) splits at end (i.e. unchanged)

Returns

Whether successful, false if bad index

splitat_setl() [2/2]

bool splitat_setl ( Key  index, T2 &  right  )

inlineinherited

Split at index, set as left sublist, and save right sublist.

• Can use methods like find() or findany() for index
• Sets this to sublist before index, unchanged if bad index [out]

Parameters

index	Index to split at, bad index (NONE or out-of-bounds) splits at end (i.e. unchanged)
right	Set to sublist after index, null if bad index [out]

Returns

Whether successful, false if bad index

splitat_setr() [1/2]

bool splitat_setr ( Key  index )

inlineinherited

Split at index and set as right sublist.

• Can use methods like find() or findany() for index
• Sets this to sublist after index, null if bad index [out]

Parameters

index

Index to split at, bad index (NONE or out-of-bounds) splits at end

Returns

Whether successful, false if bad index

splitat_setr() [2/2]

bool splitat_setr ( Key  index, T1 &  left  )

inlineinherited

Split at index, set as right sublist, and save left sublist.

• Can use methods like find() or findany() for index
• Sets this to sublist after index, null if bad index [out]

Parameters

index	Index to split at, bad index (NONE or out-of-bounds) splits at end
left	Set to sublist before index, set to this if bad index [out]

Returns

Whether successful, false if bad index

splitmap()

C::Size splitmap ( C &  map, char  delim = ',', char  kvdelim = '='  ) const

inline

Split delimited string into map key/value items.

• This parses/tokenizes str and adds each item to map, using convert() for conversion to map key and value types
• Map key and value types must be convertible from String via convert()
• See joinmap() to join map back into string

Template Parameters

C	List container for items – inferred from map parameter

Parameters

map	List to add items to [in/out]
delim	Item delimiter to use
kvdelim	Key/Value delimiter to use

Returns

Number of items added to map

splitr() [1/3]

bool splitr ( char  delim, T1 &  left, T2 &  right  ) const

inline

Split at last occurrence of delimiter into left/right substrings.

• Template types are automatically deduced from arguments
• For more advanced parsing see StrTok

Template Parameters

T1	String type to store left substring
T2	String type to store right substring

Parameters

delim	Delimiter to find
left	Set to substring before delim, set to this if not found [out]
right	Set to substring after delim, null if not found [out]

Returns

Whether successful, false if delim not found

splitr() [2/3]

bool splitr ( char  delim, T1 &  left  ) const

inline

Split at last occurrence of delimiter into left substring.

• Template types are automatically deduced from arguments
• For more advanced parsing see StrTok

Template Parameters

T1	String type to store left substring

Parameters

delim	Delimiter to find
left	Set to substring before delim, set to this if not found [out]

Returns

Whether successful, false if delim not found

splitr() [3/3]

bool splitr ( char  delim, ValNull  left, T2 &  right  ) const

inline

Split at last occurrence of delimiter into right substring.

• Template types are automatically deduced from arguments
• For more advanced parsing see StrTok

Template Parameters

T2	String type to store right substring

Parameters

delim	Delimiter to find
left	vNULL (ignored)
right	Set to substring after delim, null if not found [out]

Returns

Whether successful, false if delim not found

starts() [1/3]

bool starts ( const Item *  items, Size  size  ) const

inlineinherited

Check if starts with given items.

• Uses item operator==() for comparisons

Parameters

items	Items to check
size	Size as item count to check

Returns

Whether starts with items

starts() [2/3]

bool starts ( const ListBaseType &  items ) const

inlineinherited

Check if this starts with given items.

• Uses item operator==() for comparisons

Parameters

items

Items to check

Returns

Whether starts with items

starts() [3/3]

bool starts ( char  ch ) const

inline

Check if this starts with given character.

Parameters

ch	Character to check

Returns

Whether starts with character

strip() [1/2]

String& strip ( )

inline

Strip left (beginning) and right (ending) whitespace (spaces and tabs).

• This non-destructively removes whitespace so data isn't modified – see Slicing
• This doesn't strip newlines – see strip2()

Returns

This

strip() [2/2]

String& strip ( char  ch )

inline

Strip left (beginning) and right (ending) occurences of character.

• This non-destructively removes characters so data isn't modified – see Slicing

Parameters

ch	Character to strip

Returns

This

strip2()

String& strip2 ( )

inline

Strip left (beginning) and right (ending) whitespace from string, including newlines.

• This non-destructively removes characters so data isn't modified – see Slicing
• This is CPU-optimized where possible – see C++ Compilers & Optimization
• See also strip()

Returns

This

strip_newlines()

String& strip_newlines ( )

inline

Strip left (beginning) and right (ending) newlines from string.

• This non-destructively removes characters so data isn't modified – see Slicing
• This removes all beginning and ending newline chars (CR and LF) so this effectively recognizes all the main newlines types, see Newline

Returns

This

stripl() [1/3]

String& stripl ( )

inline

Strip left (beginning) whitespace (spaces and tabs).

• This non-destructively removes whitespace so data isn't modified – see Slicing
• This doesn't strip newlines – see stripl2()

Returns

This

stripl() [2/3]

String& stripl ( char  ch, Size  max = ALL  )

inline

Strip left (beginning) occurrences of character.

• This non-destructively removes characters so data isn't modified – see Slicing

Parameters

ch	Character to strip
max	Max count to strip, ALL for all

Returns

This

stripl() [3/3]

String& stripl ( const char *  str, Size  strsize, Size  max = ALL  )

inline

Strip left (beginning) occurrences of string.

• This non-destructively removes characters so data isn't modified – see Slicing

Parameters

str	Pointer to string to strip
strsize	String length to strip
max	Max number of occurences to strip, ALL for all

Returns

This

stripl2()

String& stripl2 ( )

inline

Strip left (beginning) whitespace from string, including newlines.

• This non-destructively removes characters so data isn't modified – see Slicing
• This is CPU-optimized where possible – see C++ Compilers & Optimization
• See also stripl()

Returns

This

stripl_newlines() [1/2]

String& stripl_newlines ( )

inline

Strip all left (beginning) newlines from string.

• This non-destructively removes characters so data isn't modified – see Slicing
• This removes all beginning newline chars (CR and LF) so this effectively recognizes all the main newlines types, see Newline

Returns

This

stripl_newlines() [2/2]

String& stripl_newlines ( Size  max )

inline

Strip left (beginning) newlines from string.

• This non-destructively removes characters so data isn't modified – see Slicing
• This recognizes all the main newlines types, see Newline
• Note that a single newline may be 2 characters, so a max of 1 may remove 2 characters, and so on

Parameters

max	Max number of newlines to strip, ALL for all

Returns

This

stripr() [1/3]

String& stripr ( )

inline

Strip right (ending) whitespace (spaces and tabs).

• This non-destructively removes whitespace so data isn't modified – see Slicing
• This doesn't strip newlines – see stripr2()

Returns

This

stripr() [2/3]

String& stripr ( char  ch, Size  max = ALL  )

inline

Strip right (ending) occurences of character.

• This non-destructively removes characters so data isn't modified – see Slicing

Parameters

ch	Character to strip
max	Max count to strip, ALL for all

Returns

This

stripr() [3/3]

String& stripr ( const char *  str, Size  strsize, Size  max = ALL  )

inline

Strip right (ending) occurences of string.

• This non-destructively removes characters so data isn't modified – see Slicing

Parameters

str	Pointer to string to strip
strsize	String length to strip
max	Max number of occurences to strip, ALL for all

Returns

This

stripr2()

String& stripr2 ( )

inline

Strip right (ending) whitespace (including newlines) from string.

• This non-destructively removes characters so data isn't modified – see Slicing
• This is CPU-optimized where possible – see C++ Compilers & Optimization
• See also stripr()

Returns

This

stripr_newlines() [1/2]

String& stripr_newlines ( )

inline

Strip all right (ending) newlines from string.

• This non-destructively removes characters so data isn't modified – see Slicing
• This removes all ending newline chars (CR and LF) so this effectively recognizes all the main newlines types, see Newline

Returns

This

stripr_newlines() [2/2]

String& stripr_newlines ( Size  max )

inline

Strip right (ending) newlines from string.

• This non-destructively removes characters so data isn't modified – see Slicing
• This recognizes all the main newlines types, see Newline

Parameters

max	Max number of newlines to strip, ALL for all

Returns

This

swap() [1/2]

void swap ( Key  index1, Key  index2  )

inlineinherited

Swap items.

• Calls unshare() and does swap, if index1 and index2 are valid and not the same

Parameters

index1	Index of first item to swap
index2	Index of second item to swap

swap() [2/2]

void swap ( ListType &  list )

inlineinherited

Swap with another list.

• This swaps internal state directly so is faster than moving items

Parameters

list	List to swap with

token()

bool token ( StringT &  value, char  delim  )

inline

Extract next token from string.

• If delim is found, the token value up to that delim is extracted
• If delim isn't found, the whole string is extracted
• The extracted token is removed from this string, including the delim (if found)
• See also: StrTok (and variants)

Template Parameters

StringT

Output string type to store line (String or SubString), inferred from first parameter

Parameters

value	Set to next token value, or null if none [out]
delim	Delimiter to tokenize on

Returns

Whether next token was found, false if current string is empty

token_any()

bool token_any ( StringT &  value, Char &  found_delim, const char *  delims, Size  count  )

inline

Extract next token from string using any of given delimiters.

• If a delim is found, the token value up to that delim is extracted
• If a delim isn't found, the whole string is extracted
• The extracted token is removed from this string, including the delim (if found)
• See also: StrTok (and variants)

Template Parameters

StringT

Output string type to store line (String or SubString), inferred from first parameter

Parameters

value	Set to next token value, or null if none [out]
found_delim	Set to delimited found, null if no delim found [out]
delims	Delimiters to search for
count	Count of delimiters to search for, must be positive

Returns

Whether next token was found, false if current string is empty

token_line()

bool token_line ( StringT &  line )

inline

Extract next line from string.

• The extracted line is removed from this string, along with the ending newline
• This recognizes all the main newlines types, see Newline

Template Parameters

StringT

Output string type to store line (String or SubString), inferred from parameter

Parameters

line	Set to extracted line (newline removed), null if no line extracted

Returns

Whether line extracted, false if this is empty

tokenr()

bool tokenr ( StringT &  value, char  delim  )

inline

Extract next token from string in reverse (from end of string).

• If delim is found, the token value up to that delim is extracted
• If delim isn't found, the whole string is extracted
• The extracted token is removed from this string, including the delim (if found)
• See also: StrTokR (and variants)

Template Parameters

StringT

Output string type to store line (String or SubString), inferred from first parameter

Parameters

value	Set to next token value, or null if none [out]
delim	Delimiter to tokenize on

Returns

Whether next token was found, false if current string is empty

tokenr_any()

bool tokenr_any ( StringT &  value, Char &  found_delim, const char *  delims, Size  count  )

inline

Extract next token from string in reverse (from end of string) using any of given delimiters.

• If a delim is found, the token value up to that delim is extracted
• If a delim isn't found, the whole string is extracted
• The extracted token is removed from this string, including the delim (if found)
• See also: StrTokR (and variants)

Template Parameters

StringT

Output string type to store line (String or SubString), inferred from first parameter

Parameters

value	Set to next token value, or null if none [out]
found_delim	Set to delimited found, null if no delim found [out]
delims	Delimiters to search for
count	Count of delimiters to search for, must be positive

Returns

Whether next token was found, false if current string is empty

tokenr_line()

bool tokenr_line ( StringT &  line )

inline

Extract next line from string in reverse (from end of string).

• The extracted line is removed from this string, along with the ending newline
• This recognizes all the main newlines types, see Newline

Template Parameters

StringT

Output string type to store line (String or SubString), inferred from parameter

Parameters

line	Set to extracted line (newline removed), null if no line extracted

Returns

Whether line extracted, false if this is empty

tolower()

ThisType& tolower ( )

inline

Convert all uppercase characters in string to lowercase (modifier).

• This recognizes standard ASCII codes 0-127
• This does not use any locale information

Returns

This

toupper()

ThisType& toupper ( )

inline

Convert all lowercase characters in string to uppercase (modifier).

• This recognizes standard ASCII codes 0-127
• This does not use any locale information

Returns

This

triml() [1/2]

ListType& triml ( Size  size )

inlineinherited

Trim left (beginning) items.

• This non-destructively trims beginning items

Parameters

size	Trim size as item count to remove

Returns

This

triml() [2/2]

String& triml ( Size  size )

inline

Trim left (beginning) items.

• This non-destructively trims beginning items

Parameters

size	Trim size as item count to remove

Returns

This

trimr() [1/2]

ListType& trimr ( Size  size )

inlineinherited

Trim right (ending) items.

• This non-destructively trims ending items

Parameters

size	Trim size as item count to remove

Returns

This

trimr() [2/2]

String& trimr ( Size  size )

inline

Trim right (ending) items.

• This non-destructively trims ending items

Parameters

size	Trim size as item count to remove

Returns

This

truncate() [1/2]

ListType& truncate ( Size  size = 0 )

inlineinherited

Truncate to given size.

• This non-destructively trims ending items

Parameters

size	Size to truncate to as item count

Returns

This

truncate() [2/2]

String& truncate ( Size  size = 0 )

inline

Truncate to given size.

• This non-destructively trims ending items

Parameters

size	Size to truncate to as item count

Returns

This

unshare()

String& unshare ( )

inline

Make data unique by allocating new buffer, if needed (modifier).

• Use reserve() instead to reserve additional space while unsharing
• Use to make buffer unique (not shared) and writable (when not empty)
• This is called automatically by mutable/modifier methods
• This does nothing if empty or not shared

Returns

This

unslice()

String& unslice ( )

inline

Clean and remove hidden items previously removed via slicing (modifier).

• Modify operations do this automatically as needed
• This is mainly useful for cleanup before starting critical performance code

Returns

This

whitespace()

static const String& whitespace ( )

inlinestatic

Get string of ASCII whitespace characters (space, tab).

Returns

String of whitespace

write_direct()

char* write_direct ( Size  size )

inline

Get pointer for writing directly to buffer to append data.

• Call write_direct_finish() to commit written data, or don't to cancel
• This always allocates enough space so doesn't fail with String

Parameters

size	Requred size in bytes to reserve

Returns

Buffer to write to (at append position), NULL on error

write_direct_finish()

bool write_direct_finish ( Size  size )

inline

Finish writing directly to buffer.

• This commits data written directly after calling write_direct() or write_direct_multi(), one of which must be called first
• This always succeeds with String

Parameters

size	Size written in bytes, must not be greater than size passed to write_direct()

Returns

Whether successful, false on error

write_direct_flush()

char* write_direct_flush ( Size &  available, Size  written_size, Size  reserve_size  )

inline

Flush data written directly to buffer and get pointer for appending more.

• This commits data written directly after previous call or write_direct_multi(), which must be called first
• If reserve_size is 0 then this does the same as write_direct_finish() and returns a non-NULL but invalid pointer on success
• This isn't normally needed with String but the interface is compatibille with Stream types

Parameters

available	Stores available size reserved in bytes, may be less than reserve_size, 0 if reserve_size was 0 [out]
written_size	Size written in bytes to flush, must not be greater than available size from previous call to this or write_direct_multi()
reserve_size	Requred size in bytes to reserve, 0 to finish

Returns

Buffer to write to (at append position), NULL on error

write_direct_multi()

char* write_direct_multi ( Size &  available, Size  reserve_size  )

inline

Get pointer for writing directly to buffer to append data and allow multiple passes for larger sizes.

• Call write_direct_flush() or write_direct_finish() to commit written data, or neither to cancel
• If reserve_size is 0 then this does nothing and returns a non-NULL but still invalid pointer
• This always allocates enough space with String so multiple passes with write_direct_multi() aren't required, but the interface is still compatibille with Stream types
• With String, this is the same as write_direct()

Parameters

available	Stores available size reserved in bytes, may be less than reserve_size, 0 if reserve_size was 0 [out]
reserve_size	Requred size in bytes to reserve

Returns

Buffer to write to (at append position), NULL on error

write_out()

Out& write_out ( )

inline

Get parent output string.

Returns

Parent output string (this)

writebin()

Size writebin ( const char *  buf, Size  size  )

inline

Write (append) to string.

• This is the same as add(const char*,Size)

Parameters

buf	Data to write
size	Size to write

Returns

Size actually written, 0 on error

writechar()

Size writechar ( char  ch, Size  count = 1  )

inline

Write (append) repeat character as text output to string.

• This is the same as add(char,Size)

Parameters

ch	Character to write
count	Character count to write, must be positive

Returns

Size actually written (same as count)

writefmtchar()

bool writefmtchar ( char  ch, Size  count, const FmtSetField &  field  )

inline

Write (append) formatted and/or repeated character.

Parameters

ch	Character to write
count	Character repeat count to use
field	Field attributes to use

Returns

Whether successful, always true with String

writefmtdump() [1/2]

bool writefmtdump ( const FmtDump &  fmt, const char *  newline, uint  newlinesize  )

inline

Write formatted data dump.

• Output may span multiple lines, and always ends with a newline (unless dump data is empty)

Parameters

fmt	Format data, including buffer to dump
newline	Newline string to use
newlinesize	Size of newline string in bytes (max 2)

Returns

Whether successful, always true with String

writefmtdump() [2/2]

bool writefmtdump ( const FmtDump &  fmt, Newline  nl = NL_SYS  )

inline

Write formatted data dump.

• Output may span multiple lines, and always ends with a newline (unless dump data is empty)

Parameters

fmt	Format data, including buffer to dump
nl	Newline type to use, NL or NL_SYS for system default

Returns

Whether successful, always true with String

writefmtnum()

bool writefmtnum ( TNum  num, const FmtSetInt &  fmt, const FmtSetField *  field = NULL  )

inline

Write (append) formatted signed number with field alignment.

Template Parameters

TNum	Number type, inferred by param

Parameters

num	Number to write
fmt	Integer formatting attributes to use
field	Field formatting attributes to use, NULL for none

Returns

Whether successful, always true with String

writefmtnumf()

bool writefmtnumf ( TNum  num, const FmtSetFloat &  fmt, const FmtSetField *  field = NULL  )

inline

Write (append) formatted floating point number with field alignment.

Template Parameters

TNum	Number type, inferred by param

Parameters

num	Number to write
fmt	Floating point formatting attributes to use
field	Field formatting attributes to use, NULL for none

Returns

Whether successful, always true with String

writefmtnumu()

bool writefmtnumu ( TNum  num, const FmtSetInt &  fmt, const FmtSetField *  field = NULL  )

inline

Write (append) formatted unsigned number with field alignment.

Template Parameters

TNum	Number type, inferred by param

Parameters

num	Number to write
fmt	Integer formatting attributes to use
field	Field formatting attributes to use, NULL for none

Returns

Whether successful, always true with String

writefmtstr()

bool writefmtstr ( const char *  str, Size  size, const FmtSetField &  field  )

inline

Write (append) text with field alignment.

Parameters

str	String buffer to write from
size	Size to write in bytes
field	Field attributes to use

Returns

Whether successful, always true with String

writenum()

bool writenum ( TNum  num, int  base = fDEC  )

inline

Write (append) formatted signed number.

Template Parameters

TNum	Number type, inferred by param

Parameters

num	Number to write
base	Base to use for formatting

Returns

Whether successful, always true with String

writenumf()

bool writenumf ( TNum  num, int  precision = fPREC_AUTO  )

inline

Write (append) formatted floating-point number.

Template Parameters

TNum	Number type, inferred by param

Parameters

num	Number to write
precision	Formatting precision (number of fractional digits), 0 for none, fPREC_AUTO for automatic

Returns

Whether successful, always true with String

writenumu()

bool writenumu ( TNum  num, int  base = fDEC  )

inline

Write (append) formatted unsigned number.

Template Parameters

TNum	Number type, inferred by param

Parameters

num	Number to write
base	Base to use for formatting

Returns

Whether successful, always true with String

writequoted()

Size writequoted ( const char *  buf, Size  size, char  delim, bool  optional = false  )

inline

Write (append) quoted output to string.

• Newlines and unprintable characters are written as-is
• This uses Smart Quoting – see Smart Quoting

Parameters

buf	Data to quote and write
size	Data size to write
delim	Delimiter for next field to escape via quoting
optional	Whether quoting is optional, true to avoid quoting if possible

Returns

Size actually written, 0 on error (unquotable text)

writetext()

Size writetext ( const char *  buf, Size  size  )

inline

Write (append) text output to string.

• This is the same as add(const char*,Size)

Parameters

buf	Data to write
size	Size to write

Returns

Size actually written, 0 on error

Member Data Documentation

buf_

Buf buf_

protectedinherited

List buffer.

data_

char * data_

inherited

Data pointer, NULL if null.

size_

StrSizeT size_

inherited

Data size as item count, 0 if empty or null.

---

The documentation for this class was generated from the following file:

• evo/string.h