#include <evo/ustring.h>

Inheritance diagram for UnicodeString:

[legend]

Detailed Description

Unicode string container using UTF-16.

This is useful for converting String (UTF-8) to UTF-16 for use with APIs that require it
- Conversion on invalid UTF-8 defaults to umREPLACE_INVALID - Invalid UTF-8 bytes are each replaced with UNICODE_REPLACEMENT_CHAR
See Unicode page: Unicode
Caution: Setting from a raw wchar16 pointer will use Unsafe Pointer Referencing

C++11:

Move semantics
char8_t, char16_t

Windows Only:

Conversion using Win32 API:

Example

#include <evo/ustring.h>
using namespace evo;
int main() {
    // Convert UTF-8 string literal to UTF-16
    UnicodeString ustr("test123");
    // Convert UTF-16 string to UTF-8
    String str(ustr);
    // Modify str then convert it to UTF-16
    str = "newtest";
    ustr = str;
    return 0;
}

Example with C++11

C++11 UTF-16 string literal (u prefix) is supported.

#include <evo/ustring.h>
using namespace evo;
int main() {
    // Initialize with UTF-16 literal
    UnicodeString ustr(u"test123");
    // Convert UTF-16 string to UTF-8
    String str(ustr);
    // Modify str then convert it to UTF-16
    str = "newtest";
    ustr = str;
    return 0;
}

Public Types
typedef void	EvoContainerType

typedef wchar16	Item
	Item type (same as Value) More...

typedef DataCopy< wchar16 >::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< wchar16, Size >	ListBaseType
	List base type for any Evo list More...

typedef List< wchar16, StrSizeT >	ListType
	List type More...

typedef StrSizeT	Size
	Size type. More...

typedef UnicodeString	ThisType
	This string type. More...

typedef wchar16	Value
	Value type (same as Item) More...

Public Member Functions
	UnicodeString ()
	Default constructor sets as null. More...

	UnicodeString (const UnicodeString &str)
	Copy constructor. More...

	UnicodeString (const wchar16 *str, Size size)
	Constructor for string pointer. More...

	UnicodeString (const wchar16 *str)
	Constructor for null terminated string. More...

	UnicodeString (const StringBase &str)
	Constructor to convert string from UTF-8. More...

	UnicodeString (const char *str, Size size)
	Constructor to convert string from UTF-8. More...

	UnicodeString (const char *str)
	Constructor to convert terminated string from UTF-8. More...

	UnicodeString (const PtrBase< wchar16 > &str)
	Constructor to copy null terminated string from managed pointer. More...

	UnicodeString (UnicodeString &&src)
	Move constructor (C++11). More...

	UnicodeString (const char16_t *str, Size size)
	Constructor for UTF-16 string pointer (C++11). More...

	UnicodeString (const char16_t *str)
	Constructor for UTF-16 string pointer (C++11). More...

UnicodeString &	add (const Item *data, Size size)
	Append new items copied from data pointer (modifier). More...

UnicodeString &	add (const ListBaseType &data)
	Append new items copied from another list (modifier). More...

UnicodeString &	add (const Item &data)
	Append new item (modifier). More...

ListType &	addmin (Size minsize)
	Append new items up to a given minimum size (modifier). More...

UnicodeString &	addnew (Size size=1)
	Append new items (modifier). More...

void	advAdd (Size size)
	Advanced: Append new items without initializing (constructing) them. More...

wchar16 *	advBuffer (Size size)
	Advanced: Resize and get buffer pointer (modifier). More...

wchar16 *	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...

wchar16 *	advFirst ()
	Advanced: Get first item (modifier). More...

Key	advInsert (Key index, Size size)
	Advanced: Insert new items without initializing (constructing) them. More...

wchar16 &	advItem (Key index)
	Advanced: Get item (mutable). More...

wchar16 *	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...

UnicodeString &	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...

wchar16 *	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 ListType &	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...

UnicodeString &	capacity (Size size)
	Set new capacity (modifier). More...

Size	capacity () const
	Get capacity. More...

UnicodeString &	capacitymax (Size max)
	Set maximum capacity (modifier). More...

UnicodeString &	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...

UnicodeString &	clear ()
	Clear by removing all items. More...

UnicodeString &	compact ()
	Reduce capacity to fit current size (modifier). More...

int	compare (const ListBaseType &data) const
	Comparison. More...

int	compare (const StringBase &data) const
	Comparison against UTF-8 string. More...

bool	contains (ItemVal item) const
	Check whether contains given item. More...

bool	contains (const Item *data, Size size) const
	Check if contains given data. More...

bool	contains (const ListBaseType &data) const
	Check if contains given data. More...

UnicodeString &	copy (const WCHAR *str, Size size)
	Copy from terminated Windows `WCHAR` string pointer (Windows only). More...

UnicodeString &	copy (const WCHAR *str)
	Copy from Windows `WCHAR` string pointer (Windows only). More...

UnicodeString &	copy (const ListBaseType &str)
	Copy from base list type. More...

UnicodeString &	copy (const wchar16 *str, Size size)
	Copy from raw string pointer. More...

UnicodeString &	copy (const wchar16 *str)
	Copy from terminated raw string pointer. More...

const wchar16 *	cstr (UnicodeString &buffer) const
	Get terminated string pointer, using given string buffer if needed (const). More...

const wchar16 *	cstr ()
	Get terminated string pointer (const). More...

const wchar16 *	cstrM () const
	Get terminated string pointer (modifier). More...

const wchar16 *	data () const
	Get string pointer (const). More...

wchar16 *	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 (const). More...

bool	ends (ItemVal item) const
	Check if this ends with given item. 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...

UnicodeString &	fill (const Item &item, Key index=0, Size size=ALL)
	Fill using item (modifier). More...

Key	find (ItemVal item, Key start=0, Key end=END) const
	Find first occurrence of item with forward search. 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	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	findr (ItemVal item, Key start=0, Key end=END) const
	Find last occurrence of item with reverse search. More...

const Item *	first () const
	Get first item (const). More...

Item *	firstM ()
	Get first item (mutable). 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	insertnew (Key index, Size size=1)
	Insert new items (modifier). More...

const Item &	item (Key index) const
	Get item at position (const). More...

wchar16 &	itemM (Key index)
	Get item at position (mutable). 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...

bool	operator!= (const UnicodeString &str) const
	Inequality operator. More...

bool	operator!= (const wchar16 *str) const
	Inequality operator. More...

bool	operator!= (const StringBase &str) const
	Inequality operator to compare against UTF-8 string. More...

bool	operator!= (const char *str) const
	Inequality operator to compare against terminated UTF-8 string. More...

bool	operator!= (const ListBaseType &data) const
	Inequality operator. More...

wchar16 &	operator() (Key index)
	Get item at position (mutable). More...

UnicodeString &	operator<< (const Item &data)
	Append operator. More...

UnicodeString &	operator<< (const ListBaseType &data)
	Append operator. More...

UnicodeString &	operator<< (const ValNull &val)
	Append operator to set as null and empty. More...

UnicodeString &	operator<< (const ValEmpty &val)
	Append operator to set as empty but not null. More...

UnicodeString &	operator= (UnicodeString &&src)
	Move assignment operator (C++11). More...

UnicodeString &	operator= (const char16_t *str)
	Assignment operator for terminated UTF-16 string pointer (C++11). More...

UnicodeString &	operator= (const UnicodeString &str)
	Assignment operator. More...

UnicodeString &	operator= (const ListBaseType &str)
	Assignment operator to copy from base list type. More...

UnicodeString &	operator= (const wchar16 *str)
	Assignment operator for terminated UTF-16 string. More...

UnicodeString &	operator= (const StringBase &str)
	Assignment operator to convert from UTF-8 string base type. More...

UnicodeString &	operator= (const char *str)
	Assignment operator to convert from terminated UTF-8 string. More...

UnicodeString &	operator= (const PtrBase< wchar16 > &str)
	ASsignment operator for null terminated string from managed pointer. More...

UnicodeString &	operator= (const WCHAR *str)
	Assignment operator for terminated Windows `WCHAR` string (Windows only). More...

bool	operator== (const UnicodeString &str) const
	Equality operator. More...

bool	operator== (const wchar16 *str) const
	Equality operator. More...

bool	operator== (const StringBase &str) const
	Equality operator to compare against UTF-8 string. More...

bool	operator== (const char *str) const
	Equality operator to compare against terminated UTF-8 string. More...

bool	operator== (const ListBaseType &data) const
	Equality operator. More...

const Item &	operator[] (Key index) const
	Get item at position (const). More...

bool	pop (wchar16 &item, Key index)
	Pop a copy of given item (modifier). More...

bool	pop (wchar16 &item)
	Pop a copy of last item (stack) (modifier). More...

const Item *	pop ()
	Pop last item (stack). More...

bool	popq (wchar16 &item)
	Pop a copy of first item (queue) (modifier). More...

const Item *	popq ()
	Pop first item (queue). More...

UnicodeString &	prepend (const Item *data, Size size)
	Prepend new items copied from data pointer (modifier). More...

UnicodeString &	prepend (const ListBaseType &data)
	Prepend new items copied from another list (modifier). More...

UnicodeString &	prepend (const Item &data)
	Prepend new item (modifier). More...

UnicodeString &	prependnew (Size size=1)
	Prepend new items (modifier). More...

Size	remove (Key index, Size size=1)
	Remove items (modifier). More...

UnicodeString &	replace (Key index, Size rsize, const Item *data, Size size)
	Replace items with new data (modifier). More...

UnicodeString &	reserve (Size size, bool prefer_realloc=false)
	Reserve capacity for additional items (modifier). More...

UnicodeString &	resize (Size size)
	Resize while preserving existing data (modifier). More...

UnicodeString &	set ()
	Set as null and empty. More...

UnicodeString &	set (const ListType &str)
	Set to new string. More...

UnicodeString &	set (const ListBaseType &str)
	Set from base list type. More...

UnicodeString &	set (const wchar16 *str, Size size)
	Set from raw string pointer. More...

UnicodeString &	set (const wchar16 *str)
	Set from terminated raw string pointer. More...

UnicodeString &	set (const StringBase &str)
	Set and convert from UTF-8 string base type. More...

UnicodeString &	set (const char *str, Size size, UtfMode mode=umREPLACE_INVALID)
	Set and convert from UTF-8 string. More...

UnicodeString &	set (const char *str)
	Set and convert from terminated UTF-8 string. More...

UnicodeString &	set (const PtrBase< wchar16 > &str)
	Set to null terminated string from managed pointer. More...

UnicodeString &	set (const WCHAR *str, Size size)
	Set from Windows `WCHAR` string pointer (Windows only). More...

UnicodeString &	set (const WCHAR *str)
	Set from terminated Windows `WCHAR` string pointer (Windows only). 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...

UnicodeString &	set2 (const ListType &data, Key index1, Key index2)
	Set from subset of another list using start/end positions. More...

UnicodeString &	set2 (const ListBaseType &data, Key index1, Key index2)
	Set as copy of sublist using start/end positions. More...

ListType &	set2 (const ListType &data, Key index1, Key index2)
	Set from subset of another list using start/end positions. More...

UnicodeString &	set_win32 (const char *str, int size)
	Set as UTF-16 string converted from UTF-8 string (Windows only). More...

UnicodeString &	set_win32 (const char *str)
	Set as UTF-16 string converted from terminated UTF-8 string (Windows only). More...

UnicodeString &	setempty ()
	Set as empty but not null. More...

bool	shared () const
	Get whether shared. More...

Size	size () const
	Get size. More...

UnicodeString &	slice (Key index)
	Slice beginning items. More...

UnicodeString &	slice (Key index, Size size)
	Slice to given sublist. More...

UnicodeString &	slice2 (Key index1, Key index2)
	Slice to given sublist using start/end positions. 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...

bool	starts (ItemVal item) const
	Check if this starts with given item. 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...

void	swap (Key index1, Key index2)
	Swap items. More...

void	swap (ListType &list)
	Swap with another list. More...

UnicodeString &	triml (Size size)
	Trim left (beginning) items. More...

UnicodeString &	trimr (Size size)
	Trim right (ending) items. More...

UnicodeString &	truncate (Size size=0)
	Truncate to given size. More...

UnicodeString &	unshare ()
	Make data unique by allocating new buffer, if needed (modifier). More...

UnicodeString &	unslice ()
	Clean and remove hidden items previously removed via slicing (modifier). More...

Public Attributes
wchar16 *	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 wchar16 Item

inherited

Item type (same as Value)

◆ ItemVal

typedef DataCopy<wchar16 >::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<wchar16 ,Size> ListBaseType

inherited

List base type for any Evo list

◆ ListType

typedef List<wchar16,StrSizeT> ListType

List type

◆ Size

typedef StrSizeT Size

Size type.

◆ ThisType

typedef UnicodeString ThisType

This string type.

◆ Value

typedef wchar16 Value

inherited

Value type (same as Item)

Constructor & Destructor Documentation

◆ UnicodeString() [1/11]

UnicodeString ( )

inline

Default constructor sets as null.

◆ UnicodeString() [2/11]

UnicodeString ( const UnicodeString & str )

inline

Copy constructor.

Makes shared copy if possible – see Sharing

Parameters

str	String to copy

◆ UnicodeString() [3/11]

UnicodeString	(	const wchar16 *	str,
		Size	size
	)

inline

Constructor for string pointer.

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

Parameters

str	String pointer to use
size	String size as wchar16 count

◆ UnicodeString() [4/11]

UnicodeString ( const wchar16 * str )

inline

Constructor for null terminated string.

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

Parameters

str	String pointer, must be terminated, initialized as null if NULL

◆ UnicodeString() [5/11]

UnicodeString ( const StringBase & str )

inline

Constructor to convert string from UTF-8.

Parameters

str	String to convert

◆ UnicodeString() [6/11]

UnicodeString	(	const char *	str,
		Size	size
	)

inline

Constructor to convert string from UTF-8.

Parameters

str	String to convert
size	String size in bytes

◆ UnicodeString() [7/11]

UnicodeString ( const char * str )

inline

Constructor to convert terminated string from UTF-8.

Parameters

str	String to convert, must be terminated

◆ UnicodeString() [8/11]

UnicodeString ( const PtrBase< wchar16 > & 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 UnicodeString(const wchar16*)
Use Ptr<wchar16> to wrap raw pointer

Parameters

str	String pointer, must be terminated, initialized as null if NULL

◆ UnicodeString() [9/11]

UnicodeString ( UnicodeString && src )

inline

Move constructor (C++11).

Parameters

src	Source to move

◆ UnicodeString() [10/11]

UnicodeString	(	const char16_t *	str,
		Size	size
	)

inline

Constructor for UTF-16 string pointer (C++11).

UnicodeString(const wchar16*,Size) is preferred, since wchar16 is always 16 bits
This requires char16_t to be 16 bits, which is normally the case but the standard allows it to be larger
- This uses assert() to check char16_t is 16 bits
Caution: Uses Unsafe Pointer Referencing

Parameters

str	String pointer to use
size	String size as `wchar16` count

◆ UnicodeString() [11/11]

UnicodeString ( const char16_t * str )

inline

Constructor for UTF-16 string pointer (C++11).

UnicodeString(const wchar16*,Size) is preferred, since wchar16 is always 16 bits
This requires char16_t to be 16 bits, which is normally the case but the standard allows it to be larger
- This uses assert() to check char16_t is 16 bits
Caution: Uses Unsafe Pointer Referencing

Parameters

str	String pointer to use, must be terminated

Member Function Documentation

◆ add() [1/3]

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

inline

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/3]

UnicodeString& add ( const ListBaseType & data )

inline

Append new items copied from another list (modifier).

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

Parameters

data	Data to append

Returns: This

◆ add() [3/3]

UnicodeString& add ( const Item & data )

inline

Append new item (modifier).

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

Parameters

data	Data to append

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

◆ addnew()

UnicodeString& addnew ( Size size = 1 )

inline

Append new items (modifier).

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

Parameters

size	Size as item count 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]

wchar16 * 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]

wchar16 * 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()

wchar16 * 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()

wchar16 & 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()

wchar16 * 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()

UnicodeString& 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()

wchar16 * 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 ListType& asconst ( ) const

inlineinherited

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 ( )

inlineinherited

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 items mutable

Returns: Iterator at first item, or at end position if empty

See also: IterM, end(), cbegin(), cend()

◆ begin() [2/2]

Iter begin ( ) const

inlineinherited

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()

◆ capacity() [1/2]

UnicodeString& 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

◆ capacity() [2/2]

Size capacity ( ) const

inlineinherited

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

◆ capacitymax()

UnicodeString& 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()

UnicodeString& 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

inlineinherited

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

inlineinherited

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()

UnicodeString& 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()

UnicodeString& 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

inline

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 StringBase & data ) const

inline

Comparison against UTF-8 string.

Parameters

data	Data to compare to

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

◆ contains() [1/3]

bool contains ( ItemVal item ) const

inlineinherited

Check whether contains given item.

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

Parameters

item	Item to check for

Returns: Whether item was found

◆ contains() [2/3]

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() [3/3]

bool contains ( const ListBaseType & data ) 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

Returns: Whether data was found

◆ copy() [1/5]

UnicodeString& copy	(	const WCHAR *	str,
		Size	size
	)

inline

Copy from terminated Windows WCHAR string pointer (Windows only).

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

Parameters

str	Pointer to string to copy from, NULL to set as null
size	String size as character (WCHAR) count

Returns: This

◆ copy() [2/5]

UnicodeString& copy ( const WCHAR * str )

inline

Copy from Windows WCHAR string pointer (Windows only).

This always makes an unshared copy
For best performance (and less safety) reference string instead with set(const WCHAR*)

Parameters

str	Pointer to string to copy from, must be terminated, NULL to set as null

Returns: This

◆ copy() [3/5]

UnicodeString& copy ( const ListBaseType & str )

inline

Copy from base list type.

This always makes an unshared copy
For best performance (and less safety) reference string instead with set(const ListBaseType&)

Parameters

str	String to copy from

Returns: This

◆ copy() [4/5]

UnicodeString& copy	(	const wchar16 *	str,
		Size	size
	)

inline

Copy from raw string pointer.

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

Parameters

str	String to copy from
size	String size as character (wchar16) count

Returns: This

◆ copy() [5/5]

UnicodeString& copy ( const wchar16 * str )

inline

Copy from terminated raw string pointer.

This always makes an unshared copy
For best performance (and less safety) reference string instead with set(const wchar16*)

Parameters

str	String to copy from, must be terminated, NULL to set as null by calling set()

Returns: This

◆ cstr() [1/2]

const wchar16* cstr ( UnicodeString & 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

Parameters

buffer Buffer to use, if needed

Returns: Terminated string pointer

◆ cstr() [2/2]

const wchar16* cstr ( )

inline

Get terminated string pointer (const).

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

Returns: Terminated string pointer

◆ cstrM()

const wchar16* 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(wchar16) after this may (will) invalidate the returned pointer

◆ data()

const wchar16* 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()

wchar16 * 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).

◆ empty()

bool empty ( ) const

inlineinherited

Get whether empty.

Empty when size() is 0

Returns: Whether empty

◆ end() [1/2]

IterM end ( )

inlineinherited

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

inlineinherited

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: begin() const, cend()

◆ ends() [1/3]

bool ends ( ItemVal item ) const

inlineinherited

Check if this ends with given item.

Uses item operator==() for comparisons

Parameters

item	Item to check

Returns: Whether ends with item

◆ ends() [2/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() [3/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

◆ fill()

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

inline

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

◆ find()

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

◆ findany()

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

◆ findanyr()

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

◆ findr()

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

◆ 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

◆ 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/3]

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/3]

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/3]

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

◆ 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()

wchar16 & 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)

◆ 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

◆ 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

◆ operator!=() [1/5]

bool operator!= ( const UnicodeString & str ) const

inline

Inequality operator.

Parameters

str	String to compare to

Returns: Whether inequal

◆ operator!=() [2/5]

bool operator!= ( const wchar16 * str ) const

inline

Inequality operator.

Parameters

str	String to compare to, must be terminated

Returns: Whether inequal

◆ operator!=() [3/5]

bool operator!= ( const StringBase & str ) const

inline

Inequality operator to compare against UTF-8 string.

Parameters

str	String to compare to, must be terminated

Returns: Whether inequal

◆ operator!=() [4/5]

bool operator!= ( const char * str ) const

inline

Inequality operator to compare against terminated UTF-8 string.

Parameters

str	String to compare to, must be terminated

Returns: Whether inequal

◆ operator!=() [5/5]

bool operator!= ( const ListBaseType & data ) const

inlineinherited

Inequality operator.

Parameters

data	Data to compare to

Returns: Whether inequal

◆ operator()()

wchar16 & 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/4]

UnicodeString& operator<< ( const Item & data )

inline

Append operator.

Same as add(const Item&)
Append operators can be chained
Example:
// Clear character list and append two characters
list << vEMPTY << 'a' << 'b';

Parameters

data	Data to append

Returns: This

◆ operator<<() [2/4]

UnicodeString& operator<< ( const ListBaseType & data )

inline

Append operator.

Same as add(const ListBaseType&)
Append operators can be chained
Example:
// Clear list and append two other lists
list << vEMPTY << list2 << list3;

Parameters

data	Data to append

Returns: This

◆ operator<<() [3/4]

UnicodeString& operator<< ( const ValNull & val )

inline

Append operator to set as null and empty.

Same as set()
Append operators can be chained
Example:
// Clear character list and append two characters
list << vNULL << 'a' << 'b';

Parameters

val vNULL

Returns: This

◆ operator<<() [4/4]

UnicodeString& operator<< ( const ValEmpty & val )

inline

Append operator to set as empty but not null.

Append operators can be chained
Example:
// Clear character list and append two characters
list << vEMPTY << 'a' << 'b';

Parameters

val vEMPTY

Returns: This

◆ operator=() [1/9]

UnicodeString& operator= ( UnicodeString && src )

inline

Move assignment operator (C++11).

Parameters

src	Source to move

Returns: This

◆ operator=() [2/9]

UnicodeString& operator= ( const char16_t * str )

inline

Assignment operator for terminated UTF-16 string pointer (C++11).

operator=(const wchar16*) is preferred, since wchar16 is always 16 bits
This requires char16_t to be 16 bits, which is normally the case but the standard allows it to be larger
- This uses assert() to check char16_t is 16 bits
Caution: Uses Unsafe Pointer Referencing

Parameters

str	String pointer to use, must be terminated

Returns: This

◆ operator=() [3/9]

UnicodeString& operator= ( const UnicodeString & str )

inline

Assignment operator.

Makes shared copy if possible – see Sharing

Parameters

str	String to copy

Returns: This

◆ operator=() [4/9]

UnicodeString& operator= ( const ListBaseType & str )

inline

Assignment operator to copy from base list type.

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

Parameters

str	String data to assign

Returns: This

◆ operator=() [5/9]

UnicodeString& operator= ( const wchar16 * str )

inline

Assignment operator for terminated UTF-16 string.

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

Parameters

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

Returns: This

◆ operator=() [6/9]

UnicodeString& operator= ( const StringBase & str )

inline

Assignment operator to convert from UTF-8 string base type.

Parameters

str	String str to convert from

Returns: This

◆ operator=() [7/9]

UnicodeString& operator= ( const char * str )

inline

Assignment operator to convert from terminated UTF-8 string.

Parameters

str	String str to convert from, must be terminated

Returns: This

◆ operator=() [8/9]

UnicodeString& operator= ( const PtrBase< wchar16 > & str )

inline

ASsignment operator for null terminated string from managed pointer.

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

Parameters

str	String pointer, must be terminated, set to null if NULL

Returns: This

◆ operator=() [9/9]

UnicodeString& operator= ( const WCHAR * str )

inline

Assignment operator for terminated Windows WCHAR string (Windows only).

Caution: Uses Unsafe Pointer Referencing
For best safety use copy(const WCHAR*)

Parameters

str	Pointer to string to set, must be terminated, NULL to set as null

Returns: This

◆ operator==() [1/5]

bool operator== ( const UnicodeString & str ) const

inline

Equality operator.

Parameters

str	String to compare to

Returns: Whether equal

◆ operator==() [2/5]

bool operator== ( const wchar16 * str ) const

inline

Equality operator.

Parameters

str	String to compare to, must be terminated

Returns: Whether equal

◆ operator==() [3/5]

bool operator== ( const StringBase & str ) const

inline

Equality operator to compare against UTF-8 string.

Parameters

str	String to compare to, must be terminated

Returns: Whether equal

◆ operator==() [4/5]

bool operator== ( const char * str ) const

inline

Equality operator to compare against terminated UTF-8 string.

Parameters

str	String to compare to, must be terminated

Returns: Whether equal

◆ operator==() [5/5]

bool operator== ( const ListBaseType & data ) const

inlineinherited

Equality operator.

Parameters

data	Data 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	(	wchar16 &	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 ( wchar16 & 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 ( wchar16 & 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/3]

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

inline

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/3]

UnicodeString& prepend ( const ListBaseType & data )

inline

Prepend new items copied from another list (modifier).

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

Parameters

data	Data to prepend

Returns: This

◆ prepend() [3/3]

UnicodeString& prepend ( const Item & data )

inline

Prepend new item (modifier).

Removes items sliced from beginning – see unslice()

Parameters

data	Data to prepend

Returns: This

◆ prependnew()

UnicodeString& prependnew ( Size size = 1 )

inline

Prepend new items (modifier).

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

Parameters

size	Size as item count 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()

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

inline

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

◆ reserve()

UnicodeString& 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()

UnicodeString& 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

◆ set() [1/15]

UnicodeString& set ( )

inline

Set as null and empty.

Returns: This

◆ set() [2/15]

UnicodeString& set ( const ListType & str )

inline

Set to new string.

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

Parameters

str	String to set from

Returns: This

◆ set() [3/15]

UnicodeString& set ( const ListBaseType & str )

inline

Set from base list type.

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

Parameters

str	String to assign

Returns: This

◆ set() [4/15]

UnicodeString& set	(	const wchar16 *	str,
		Size	size
	)

inline

Set from raw string pointer.

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

Parameters

str	String pointer to set from
size	String size as character (wchar16) count

Returns: This

◆ set() [5/15]

UnicodeString& set ( const wchar16 * str )

inline

Set from terminated raw string pointer.

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

Parameters

str	String pointer to set from, must be terminated

Returns: This

◆ set() [6/15]

UnicodeString& set ( const StringBase & str )

inline

Set and convert from UTF-8 string base type.

Parameters

str	String str to convert from

Returns: This

◆ set() [7/15]

UnicodeString& set	(	const char *	str,
		Size	size,
		UtfMode	mode = `umREPLACE_INVALID`
	)

inline

Set and convert from UTF-8 string.

Parameters

str	String str to convert from
size	String size as character count
mode	How to handle invalid UTF-8 bytes and values that convert to reserved UTF-16 surrogate values: umINCLUDE_INVALID - Invalid UTF-8 bytes are still converted, but invalid UTF-16 surrogate values that can't be represented are skipped umREPLACE_INVALID - Invalid UTF-8 bytes are each replaced with UNICODE_REPLACEMENT_CHAR umSKIP_INVALID - Invalid input is skipped and ignored umSTRICT - Stop on invalid input with an error

Returns: This

◆ set() [8/15]

UnicodeString& set ( const char * str )

inline

Set and convert from terminated UTF-8 string.

Parameters

str	String str to convert from, must be terminated, NULL to call set()

Returns: This

◆ set() [9/15]

UnicodeString& set ( const PtrBase< wchar16 > & str )

inline

Set to null terminated string from managed pointer.

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

Parameters

str	String pointer, must be terminated, set to null if NULL

Returns: This

◆ set() [10/15]

UnicodeString& set	(	const WCHAR *	str,
		Size	size
	)

inline

Set from Windows WCHAR string pointer (Windows only).

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

Parameters

str	Pointer to string to set, NULL to set as null
size	String size as character (WCHAR) count

Returns: This

◆ set() [11/15]

UnicodeString& set ( const WCHAR * str )

inline

Set from terminated Windows WCHAR string pointer (Windows only).

Caution: Uses Unsafe Pointer Referencing
For best safety use copy(const WCHAR*)

Parameters

str	Pointer to string to set, must be terminated, NULL to set as null

Returns: This

◆ set() [12/15]

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() [13/15]

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() [14/15]

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() [15/15]

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

◆ set2() [1/3]

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

inline

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/3]

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

inline

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/3]

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

◆ set_win32() [1/2]

UnicodeString& set_win32	(	const char *	str,
		int	size
	)

inline

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

This uses the Win32 API to do the conversion, and so is only supported in Windows
Invalid UTF-8 characters are replaced with UNICODE_REPLACEMENT_CHAR
For terminated strings see: set_unicode_win32(const char*)

Parameters

str	String to convert from, NULL to set as null by calling set()
size	String size as character count

Returns: This

◆ set_win32() [2/2]

UnicodeString& set_win32 ( const char * str )

inline

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

This uses the Win32 API to do the conversion, and so is only supported in Windows
Invalid UTF-8 characters are replaced with UNICODE_REPLACEMENT_CHAR
For non-terminated strings see: set_unicode_win32(const char*,int)

Parameters

str	String to convert from, must be terminated, NULL to set as null by calling set()

Returns: This

◆ setempty()

UnicodeString& setempty ( )

inline

Set as empty but not null.

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/2]

UnicodeString& 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() [2/2]

UnicodeString& 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()

UnicodeString& 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

◆ 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

◆ starts() [1/3]

bool starts ( ItemVal item ) const

inlineinherited

Check if this starts with given item.

Uses item operator==() for comparisons

Parameters

item	Item to check

Returns: Whether starts with item

◆ starts() [2/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() [3/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

◆ 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

◆ triml()

UnicodeString& 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()

UnicodeString& 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()

UnicodeString& 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()

UnicodeString& 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()

UnicodeString& 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

Member Data Documentation

◆ buf_

Buf buf_

protectedinherited

List buffer.

◆ data_

wchar16 * 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/ustring.h

Detailed Description

Public Types

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Member Typedef Documentation

◆ EvoContainerType

◆ Item

◆ ItemVal

◆ Iter

◆ IterM

◆ Key

◆ ListBaseType

◆ ListType

◆ Size

◆ ThisType

◆ Value

Constructor & Destructor Documentation

◆ UnicodeString() [1/11]

◆ UnicodeString() [2/11]

◆ UnicodeString() [3/11]

◆ UnicodeString() [4/11]

◆ UnicodeString() [5/11]

◆ UnicodeString() [6/11]

◆ UnicodeString() [7/11]

◆ UnicodeString() [8/11]

◆ UnicodeString() [9/11]

◆ UnicodeString() [10/11]

◆ UnicodeString() [11/11]

Member Function Documentation

◆ add() [1/3]

◆ add() [2/3]

◆ add() [3/3]

◆ addmin()

◆ addnew()

◆ advAdd()

◆ advBuffer() [1/2]

◆ advBuffer() [2/2]

◆ advEdit()

◆ advEditDone()

◆ advFirst()

◆ advInsert()

◆ advItem()

◆ advLast()

◆ advPrepend()

◆ advRemove()

◆ advResize()

◆ advSize()

◆ advSwap()

◆ advWrite()

◆ advWriteDone()

◆ asconst()

◆ begin() [1/2]

◆ begin() [2/2]

◆ capacity() [1/2]

◆ capacity() [2/2]

◆ capacitymax()

◆ capacitymin()

◆ cbegin()

◆ cend()

◆ clear()

◆ compact()

◆ compare() [1/2]

◆ compare() [2/2]

◆ contains() [1/3]

◆ contains() [2/3]

◆ contains() [3/3]

◆ copy() [1/5]

◆ copy() [2/5]

◆ copy() [3/5]

◆ copy() [4/5]

◆ copy() [5/5]

◆ cstr() [1/2]

◆ cstr() [2/2]

◆ cstrM()

◆ data()

◆ dataM()

◆ empty()

◆ end() [1/2]