A Unicode-aware string class. More...

#include <String.h>

Collaboration diagram for active::utility::String:

Public Types
using	Unique = std::unique_ptr<String>
	Unique pointer.

using	Shared = std::shared_ptr<String>
	Shared pointer.

using	Option = std::optional<String>
	Optional.

using	size_type = std::string::size_type
	Class size type.

using	sizeOption = std::optional<size_type>
	Optional size type (used to indicate an unspecified or non-existant position)

using	Filter = std::function<bool(char32_t)>
	Unary predicate for filtering strings.

using	Function = std::function<std::optional<char32_t>(char32_t)>
	Unary functions for processing string characters.

Public Member Functions
	String ()

	String (const BufferIn &&source)

	String (const char *source, sizeOption howMany=std::nullopt, DataFormat format=DataFormat{})

	String (const char8_t *source, sizeOption howMany=std::nullopt)

	String (const char16_t *source, sizeOption howMany=std::nullopt, bool isBigEndian=Memory::defaultEndian)

	String (const char32_t *source, sizeOption howMany=std::nullopt, bool isBigEndian=Memory::defaultEndian)

	String (const std::string &source, sizeOption howMany=std::nullopt, DataFormat format=DataFormat{})

	String (const std::u8string &source, sizeOption howMany=std::nullopt)

	String (const std::u16string &source, sizeOption howMany=std::nullopt)

	String (const std::u32string &source, sizeOption howMany=std::nullopt)

	String (size_type newSize, const String &fillText)

	String (char val)

	String (int16_t val)

	String (uint16_t val)

	String (int32_t val)

	String (uint32_t val)

	String (int64_t val)

	String (uint64_t val)

	String (size_t val)

	String (double val, double prec=math::eps, bool padZero=false)

	String (const String &source)

	String (String &&source) noexcept

	~String ()

	operator std::string () const
	Conversion to std::string.

	operator std::u8string () const
	Conversion to std::u8string.

	operator std::u16string () const
	Conversion to std::u16string.

	operator std::u32string () const
	Conversion to std::u32string.

	operator int16_t () const
	Conversion to 16-bit integer.

	operator int32_t () const
	Conversion to 32-bit integer.

	operator uint32_t () const
	Conversion to 32-bit unsigned integer.

	operator int64_t () const
	Conversion to 64-bit integer.

	operator uint64_t () const
	Conversion to 64-bit unsigned integer.

	operator float () const
	Conversion to float.

	operator double () const
	Conversion to double (0 if conversion impossible)

char32_t	operator[] (size_type index) const

String &	operator= (const String &source)

String &	operator= (String &&source) noexcept

String &	operator= (const char *source)

std::strong_ordering	operator<=> (const String &ref) const

bool	operator== (const String &ref) const

bool	operator!= (const String &ref) const

String &	operator+= (const String &source)

String &	operator+= (char source)

size_type	capacity () const

size_type	size () const

size_type	length () const

size_type	dataSize (sizeOption howMany=std::nullopt) const

bool	empty () const

const char *	data () const

std::string	string () const

char32_t	at (size_type index) const

void	forEach (const Function &func) const

String	substr (size_type startPos=0, sizeOption howMany=std::nullopt) const

String	uppercase () const

String	lowercase () const

std::optional< int16_t >	toInt16 () const
	Conversion to optional int16_t (nullopt if conversion impossible)

std::optional< int32_t >	toInt32 () const
	Conversion to optional int32_t (nullopt if conversion impossible)

std::optional< uint32_t >	toUInt32 () const
	Conversion to optional uint32_t (nullopt if conversion impossible)

std::optional< int64_t >	toInt64 () const
	Conversion to optional int64_t (nullopt if conversion impossible)

std::optional< uint64_t >	toUInt64 () const
	Conversion to optional uint64_t (nullopt if conversion impossible)

std::optional< float >	toFloat () const
	Conversion to optional float (nullopt if conversion impossible)

std::optional< double >	toDouble () const
	Conversion to optional double (nullopt if conversion impossible)

const BufferOut &	writeTo (const BufferOut &buffer, DataFormat format=UTF8, bool isNullAdded=true, sizeOption howMany=std::nullopt, sizeOption maxLen=std::nullopt) const

const BufferOut &	writeUTF8 (const BufferOut &buffer, bool isNullAdded=true, sizeOption howMany=std::nullopt, sizeOption maxLen=std::nullopt) const

const BufferOut &	writeUTF16 (const BufferOut &buffer, bool isNullAdded=true, bool isBigEndian=DataFormat::defaultEndian, sizeOption howMany=std::nullopt, sizeOption maxLen=std::nullopt) const

const BufferOut &	writeUTF32 (const BufferOut &buffer, bool isNullAdded=true, bool isBigEndian=DataFormat::defaultEndian, sizeOption howMany=std::nullopt, sizeOption maxLen=std::nullopt) const

bool	isAlphaNumeric (size_type startPos=0, sizeOption howMany=std::nullopt) const

bool	isAlpha (size_type startPos=0, sizeOption howMany=std::nullopt) const

bool	isNumeric (size_type startPos=0, sizeOption howMany=std::nullopt) const

std::strong_ordering	compare (const String &ref) const

sizeOption	find (const String &toFind, size_type startPos=0) const

sizeOption	findIf (const Filter &filter) const

bool	contains (const String &toFind) const

bool	startsWith (const String &toFind) const

bool	endsWith (const String &toFind) const

sizeOption	findFirstOf (const String &toFind, size_type startPos=0) const

sizeOption	findFirstNotOf (const String &toFind, size_type startPos=0) const

sizeOption	findLastOf (const String &toFind, sizeOption lastPos=std::nullopt) const

sizeOption	findLastNotOf (const String &toFind, sizeOption lastPos=std::nullopt) const

sizeOption	rfind (const String &toFind, sizeOption lastPos=std::nullopt) const

void	reserve (size_type newSize)

void	resize (size_type newSize, const String &padding="")

void	clear ()

void	forEach (const Function &func)

String &	assign (const String &source)

size_type	assign (const char *source, sizeOption byteCount=std::nullopt, sizeOption charCount=std::nullopt, DataFormat format=DataFormat{})

String &	append (const String &source)

String &	append (char source)

String &	append (char32_t source)

String &	insert (size_type pos, const String &source, size_type start=0, sizeOption howMany=std::nullopt)

String &	replace (sizeOption pos, sizeOption num, const String &source, size_type start=0, sizeOption howMany=std::nullopt)

String &	replaceAll (const String &toFind, const String &replacement=String())

String &	replaceIf (const Filter &filter, const String &replacement=String())

String &	replaceAnyOf (const String &charsToFind, const String &replacement=String())

String &	erase (size_type pos=0, sizeOption howMany=std::nullopt)

void	popBack ()

String &	padRight (size_type length, const String &repeat=" ")

String &	padLeft (size_type length, const String &repeat=" ")

Static Public Member Functions
static size_type	getValidByteCount (const char *text, sizeOption howMany=std::nullopt, sizeOption charCount=std::nullopt, DataFormat format=DataFormat{})

static sizeOption	getCharacterByteCount (const char *text, sizeOption howMany=std::nullopt, DataFormat format=DataFormat{})

static String::sizeOption	getCharacterCount (const char *text, sizeOption howMany=std::nullopt, DataFormat format=DataFormat{})

static std::pair< char32_t, size_type >	getUnicodeChar (const char *text, sizeOption howMany=std::nullopt, DataFormat format=DataFormat{})

static std::optional< std::u32string >	toUnicode (const char *&text, String::sizeOption howMany=std::nullopt, bool isCountRequired=false)

static std::optional< String >	fromUnicode (const char32_t *&text, bool isBigEndian, String::sizeOption howMany=std::nullopt, bool isCountRequired=false)

static std::optional< std::u32string >	fromUTF16 (const char16_t *&text, bool isBigEndian, String::sizeOption howMany=std::nullopt, bool isCountRequired=false)

static std::optional< std::u16string >	toUTF16 (const char32_t *&text, String::sizeOption howMany=std::nullopt, bool isCountRequired=false)

Static Public Attributes
static constexpr size_type	npos = std::string::npos
	Constant to indicate an unspecified or non-existant position in std::string - use std::nullopt in this class.

static const String	lineTerminator {"\n"}
	The line terminating char(s) for the current platform.

static const String	allWhiteSpace {" \t\r\n"}
	All white space characters.

static const String	allLineEnding {"\r\n"}
	All line ending characters.

static const String	allDigit {"0123456789"}
	All digit characters (0-9)

static const String	allNumeric {"0123456789-"}
	All numeric characters (integer and signed)

static const String	allFloat {"0123456789.-"}
	All floating point characters (floating and integer)

Detailed Description

A Unicode-aware string class.

The String class is a wrapper for std::string and leans heavily on existing functionality it provides, extending it with awareness of Unicode encodings for character positioning. This also provides easy access to the underlying std::string for easy interoperability with any code working with that type.

String content is internally encoded/validated as UTF-8, but it can be encode/decode UTF8, UTF16, UTF32, ASCII and ISO8859. Character positions are calculated to allow indexing, but the time to find a position averages O(n) It is recommended to use classes like BufferIn to analyse by-character content on large blocks of text efficiently

This class does not use a 'special' value to denote non-existent or unspecified positions, e.g. like string::npos Rather, an optional is used for these cases, e.g. if searching for a dot outside the first 5 characters of some text, using std::string could look like this:

if (auto pos = text.find("."); (pos != nos) && (pos > 4))

With this string class, the optional response simplifies the syntax:

if (auto pos = text.find("."); pos > 4)

The String class also provides a range of static functions for validating or converting blocks of text for all supported encoding. Conversion operators and constructors provide interoperability with a range of common types, e.g. std::string, std::u32string etc

In line with current C++ standards, any ranges passed by a pointer and length must be valid, e.g. the atart address must not be nullptr, or behaviour will be undefined

Constructor & Destructor Documentation

◆ String() [1/22]

active::utility::String::String ( )

inline

Default constructor

Here is the caller graph for this function:

◆ String() [2/22]

String::String ( const BufferIn && source )

Constructor from an input buffer

Parameters

source The source input buffer

◆ String() [3/22]

String::String	(	const char *	source,
		sizeOption	howMany = std::nullopt,
		DataFormat	format = DataFormat{} )

Constructor from an input char array

Parameters

source	The character array to be copied
howMany	The number of bytes to copy (nullopt for full length)
format	The source text data format

◆ String() [4/22]

active::utility::String::String	(	const char8_t *	source,
		sizeOption	howMany = std::nullopt )

inline

Constructor from an input UTF8 char array

Parameters

source	The character array to be copied
howMany	The number of bytes to copy (nullopt for full length)

◆ String() [5/22]

active::utility::String::String	(	const char16_t *	source,
		sizeOption	howMany = std::nullopt,
		bool	isBigEndian = Memory::defaultEndian )

inline

Constructor from an input UTF16 char array

Parameters

source	The character array to be copied
howMany	The number of 16-bit chars to copy (nullopt for null-terminated)

◆ String() [6/22]

active::utility::String::String	(	const char32_t *	source,
		sizeOption	howMany = std::nullopt,
		bool	isBigEndian = Memory::defaultEndian )

inline

Constructor from an input UTF32 char array

Parameters

source	The character array to be copied
howMany	The number of 32-bit chars to copy (nullopt for null-terminated)

◆ String() [7/22]

active::utility::String::String	(	const std::string &	source,
		sizeOption	howMany = std::nullopt,
		DataFormat	format = DataFormat{} )

inline

Constructor from an input string

Parameters

source	The string to be copied
howMany	The number of chars to copy (nullopt for full length)
format	The source text data format

◆ String() [8/22]

active::utility::String::String	(	const std::u8string &	source,
		sizeOption	howMany = std::nullopt )

inline

Constructor from an input string

Parameters

source	The UTF-8 string to be copied
howMany	The number of chars to copy (nullopt for full length)

◆ String() [9/22]

String::String	(	const std::u16string &	source,
		sizeOption	howMany = std::nullopt )

Constructor from an input string

Parameters

source	The UTF-16 string to be copied
howMany	The number of chars to copy (nullopt for full length)

Here is the call graph for this function:

◆ String() [10/22]

String::String	(	const std::u32string &	source,
		sizeOption	howMany = std::nullopt )

Constructor from an input string

Parameters

source	The UTF-32 string to be copied
howMany	The number of chars to copy (nullopt for full length)

Here is the call graph for this function:

◆ String() [11/22]

String::String	(	size_type	newSize,
		const String &	fillText )

Constructor with optional text fill expression and number of repeats

Parameters

newSize	The required number of expression repeats
fillText	The expression to fill the string

Here is the call graph for this function:

◆ String() [12/22]

active::utility::String::String ( char val )

inlineexplicit

Constructor from a char

Parameters

val A char

◆ String() [13/22]

active::utility::String::String ( int16_t val )

inlineexplicit

Constructor from 16-bit integer

Parameters

val	A 16-bit integer

◆ String() [14/22]

active::utility::String::String ( uint16_t val )

inlineexplicit

Constructor from unsigned 16-bit integer

Parameters

val	An unsigned 16-bit integer

◆ String() [15/22]

active::utility::String::String ( int32_t val )

inlineexplicit

Constructor from 32-bit integer

Parameters

val	A 32-bit integer

◆ String() [16/22]

active::utility::String::String ( uint32_t val )

inlineexplicit

Constructor from unsigned 32-bit integer

Parameters

val	An unsigned 32-bit integer

◆ String() [17/22]

active::utility::String::String ( int64_t val )

inlineexplicit

Constructor from 64-bit integer

Parameters

val	A 64-bit integer

◆ String() [18/22]

active::utility::String::String ( uint64_t val )

inlineexplicit

Constructor from unsigned 64-bit integer

Parameters

val	An unsigned 64-bit integer

◆ String() [19/22]

active::utility::String::String ( size_t val )

inlineexplicit

Constructor from size_t integer

Parameters

val	A size_t integer

◆ String() [20/22]

String::String	(	double	val,
		double	prec = math::eps,
		bool	padZero = false )

explicit

Constructor from double

Parameters

val	A double value
prec	The required precision
padZero	True to pad the number to the specified precision with zeros

Here is the call graph for this function:

◆ String() [21/22]

String::String ( const String & source )

Copy constructor

Parameters

source The string to copy

◆ String() [22/22]

String::String ( String && source )

noexcept

Move constructor

Parameters

source The object to move

◆ ~String()

active::utility::String::~String ( )

inline

Destructor

Member Function Documentation

◆ append() [1/3]

String & active::utility::String::append ( char source )

inline

Append the specified char to this (NB: don't use this casually - encoding must be assumed and converted accordingly)

Parameters

source The char to append

Returns: A reference to this

Here is the call graph for this function:

◆ append() [2/3]

String & active::utility::String::append ( char32_t source )

inline

Append the specified unicode char to this

Parameters

source The char to append (assumed to be UTF-32)

Returns: A reference to this

Here is the call graph for this function:

◆ append() [3/3]

String & String::append ( const String & source )

Append the specified string to this

Parameters

source The string to append

Returns: A reference to this

Here is the caller graph for this function:

◆ assign() [1/2]

String::size_type String::assign	(	const char *	source,
		sizeOption	byteCount = std::nullopt,
		sizeOption	charCount = std::nullopt,
		DataFormat	format = DataFormat{} )

Assign a specified string to this

Parameters

source	The character array to be copied
byteCount	The maximum number of bytes in the array (nullopt = null-terminated)
charCount	The maximum number of (encoded) characters to read (nullopt = as byteCount limit)
format	The source text data format

Returns: The number of bytes assigned from the source

◆ assign() [2/2]

String & String::assign ( const String & source )

Assign a specified string to this

Parameters

source The string to assign

Returns: A reference to this

Here is the caller graph for this function:

◆ at()

char32_t String::at ( size_type index ) const

Subscript function

Parameters

index The required character position (checked - exception thrown if out of bounds)

Returns: The character at the specified index

Here is the call graph for this function:

Here is the caller graph for this function:

◆ capacity()

String::size_type String::capacity ( ) const

Return the number of bytes this string can contain

Returns: The number of bytes this string can contain

◆ clear()

void active::utility::String::clear ( )

inline

Clear the string contents

Here is the caller graph for this function:

◆ compare()

std::strong_ordering String::compare ( const String & ref ) const

Three-way comparison to a reference string

Parameters

ref	The string to compare this to

Returns: The relationship between this and ref (less, equal, greater)

Here is the caller graph for this function:

◆ contains()

bool active::utility::String::contains ( const String & toFind ) const

inline

Determine if the string contains a substring

Parameters

toFind The substring to find

Returns: True if the substring is found

Here is the call graph for this function:

Here is the caller graph for this function:

◆ data()

const char * active::utility::String::data ( ) const

inline

Return a pointer to a C representation of the string data

Returns: A pointer to the string data

Here is the caller graph for this function:

◆ dataSize()

String::size_type String::dataSize ( sizeOption howMany = std::nullopt ) const

Return the number of bytes consumed by this string

Parameters

howMany The number of chars to count (nullopt = for full length)

Returns: The number of bytes consumed by the string (NB: String are null terminated, but this is not included in the data length)

Here is the caller graph for this function:

◆ empty()

bool active::utility::String::empty ( ) const

inline

Determine if the string is empty

Returns: True is the string is empty

Here is the caller graph for this function:

◆ endsWith()

bool active::utility::String::endsWith ( const String & toFind ) const

inline

Determine if this string ends with a substring

Parameters

toFind The substring to find

Returns: True if this string ends with the substring

◆ erase()

String & String::erase	(	size_type	pos = 0,
		sizeOption	howMany = std::nullopt )

Erase a specified range of characters from a string

Parameters

pos	The position to erasing from
howMany	The number of characters to erase (nullopt to erase to end)

Returns: A reference to this

Here is the call graph for this function:

Here is the caller graph for this function:

◆ find()

String::sizeOption String::find	(	const String &	toFind,
		size_type	startPos = 0 ) const

Find the specified string within this

Parameters

toFind	The string to find
startPos	The character to start searching from

Returns: The index where a match is found (nullopt = not found)

Here is the call graph for this function:

Here is the caller graph for this function:

◆ findFirstNotOf()

String::sizeOption String::findFirstNotOf	(	const String &	toFind,
		size_type	startPos = 0 ) const

Find the first character not in a specified string

Parameters

toFind	A string of characters to not find
startPos	The character to begin searching from

Returns: The index of the first non-matching character (nullopt = not found)

Here is the call graph for this function:

Here is the caller graph for this function:

◆ findFirstOf()

String::sizeOption String::findFirstOf	(	const String &	toFind,
		size_type	startPos = 0 ) const

Find the first character which is in a specified string

Parameters

toFind	A string of characters to find
startPos	The character to begin searching from

Returns: The index of the first matching character (nullopt = not found)

Here is the call graph for this function:

◆ findIf()

String::sizeOption String::findIf ( const Filter & filter ) const

Find the specified string within this using a filter

Parameters

filter The string filter

Returns: The index where a match is found (nullopt = not found)

Here is the call graph for this function:

◆ findLastNotOf()

String::sizeOption String::findLastNotOf	(	const String &	toFind,
		sizeOption	lastPos = std::nullopt ) const

Find the last character in this string which is not in the specified string

Parameters

toFind	A string of characters not to find
lastPos	The position of the last character to be compared

Returns: The index of the last non-matching character (nullopt = not found)

Here is the call graph for this function:

◆ findLastOf()

String::sizeOption String::findLastOf	(	const String &	toFind,
		sizeOption	lastPos = std::nullopt ) const

Find the last character in this string which is in the specified string

Parameters

toFind	A string of characters to find
lastPos	The position of the last character to be compared

Returns: The index of the last matching character (nullopt = not found)

Here is the call graph for this function:

◆ forEach() [1/2]

void String::forEach ( const Function & func )

Apply a function to specified characters in the string

Parameters

func	The character function (the returned value replaces the input character)

Here is the call graph for this function:

◆ forEach() [2/2]

void String::forEach ( const Function & func ) const

Apply a function to specified characters in the string

Parameters

func	The character function (the returned value is ignored)

Here is the call graph for this function:

◆ fromUnicode()

std::optional< String > String::fromUnicode	(	const char32_t *&	text,
		bool	isBigEndian,
		String::sizeOption	howMany = std::nullopt,
		bool	isCountRequired = false )

static

Get a UTF-8 string from a UTF-32 source

Parameters

text	The source text
isBigEndian	True if byte ordering is big-endian
howMany	The number of 32-bit code points in the text (nullopt = null-terminated)
isCountRequired	True if the specified number of code points must be valid (ignored if howMany = nullopt)

Returns: The UTF-8 string read from the UTF-32 source (nullopt on error, including failure to meet isCountRequired condition)

Here is the caller graph for this function:

◆ fromUTF16()

std::optional< std::u32string > String::fromUTF16	(	const char16_t *&	text,
		bool	isBigEndian,
		String::sizeOption	howMany = std::nullopt,
		bool	isCountRequired = false )

static

Get a UTF-32 string from a UTF-16 (16-bit) source

Parameters

text	The source text
isBigEndian	True if byte ordering is big-endian
howMany	The number of words (16-bit values) in the text (nullopt = null-terminated)
isCountRequired	True if the specified number of words must be valid (ignored if howMany = nullopt)

Returns: The UTF-32 string read from the UTF-16 source (nullopt on error, including failure to meet isCountRequired condition)

Here is the caller graph for this function:

◆ getCharacterByteCount()

String::sizeOption String::getCharacterByteCount	(	const char *	text,
		sizeOption	howMany = std::nullopt,
		DataFormat	format = DataFormat{} )

static

Get the width of a specified character in bytes

Parameters

text	The source text
howMany	The number of bytes in the array
format	The text data format

Returns: The character width in bytes (nullopt for bad encoding)

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getCharacterCount()

String::sizeOption String::getCharacterCount	(	const char *	text,
		sizeOption	howMany = std::nullopt,
		DataFormat	format = DataFormat{} )

static

Get the number of valid characters found at a specified address

Parameters

text	The source text
format	The text data format
howMany	The number of bytes in the array (nullopt = null-terminated)

Returns: The nummber of characters found (nullopt if bad encoding found)

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getUnicodeChar()

std::pair< char32_t, String::size_type > String::getUnicodeChar	(	const char *	text,
		sizeOption	howMany = std::nullopt,
		DataFormat	format = DataFormat{} )

static

Get a unicode (UTF-32) character from a specified source

Parameters

text	The source text
howMany	The number of bytes in the text
format	The source data format

Returns: The unicode char paired with the number of bytes consumed from the source (0 = no valid char found)

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getValidByteCount()

String::size_type String::getValidByteCount	(	const char *	text,
		sizeOption	howMany = std::nullopt,
		sizeOption	charCount = std::nullopt,
		DataFormat	format = DataFormat{} )

static

Get the number of bytes in the specified text (counting only valid UTF8 characters)

Parameters

text	The source text
howMany	The number of bytes in the text
charCount	The maximum number of (encoded) chars to seek
format	The text data format

Returns: The number of bytes in the text containing valid UTF8 characters

Here is the call graph for this function:

Here is the caller graph for this function:

◆ insert()

String & String::insert	(	size_type	pos,
		const String &	source,
		size_type	start = 0,
		sizeOption	howMany = std::nullopt )

Insert a string into this

Parameters

pos	The insertion point
source	The string to insert
start	The start point in the source string
howMany	The number of chars to insert (nullopt inserts all)

Returns: A reference to this

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isAlpha()

bool String::isAlpha	(	size_type	startPos = 0,
		sizeOption	howMany = std::nullopt ) const

Determine if the string is entirely letters

Parameters

startPos	The position to checking from
howMany	The number of characters to check (nullopt = to end)

Returns: True is the string is letters

◆ isAlphaNumeric()

bool String::isAlphaNumeric	(	size_type	startPos = 0,
		sizeOption	howMany = std::nullopt ) const

Determine if the string is entirely alphanumeric

Parameters

startPos	The position to checking from
howMany	The number of characters to check (nullopt = to end)

Returns: True is the string is alphanumeric

◆ isNumeric()

bool String::isNumeric	(	size_type	startPos = 0,
		sizeOption	howMany = std::nullopt ) const

Determine if the string is entirely numeric

Parameters

startPos	The position to checking from
howMany	The number of characters to check (nullopt = to end)

Returns: True is the string is numbers

◆ length()

size_type active::utility::String::length ( ) const

inline

Get the string length (alias for size)

Returns: The number of characters in the string (size)

Here is the call graph for this function:

Here is the caller graph for this function:

◆ lowercase()

String String::lowercase ( ) const

Create a lowercase version of the string

Returns: A lowercase version of the string

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator!=()

bool active::utility::String::operator!= ( const String & ref ) const

inline

Inequality operator

Parameters

ref	The string to compare this to

Returns: True if the strings differ

◆ operator+=() [1/2]

String & active::utility::String::operator+= ( char source )

inline

Addition with assignment operator

Parameters

source The char to append

Returns: A reference to this

Here is the call graph for this function:

◆ operator+=() [2/2]

String & active::utility::String::operator+= ( const String & source )

inline

Addition with assignment operator

Parameters

source The string to append

Returns: A reference to this

Here is the call graph for this function:

◆ operator<=>()

std::strong_ordering active::utility::String::operator<=> ( const String & ref ) const

inline

Three-way comparison operator

Parameters

ref	The string to compare this to

Returns: The relationship between this and ref (less, equal, greater)

Here is the call graph for this function:

◆ operator=() [1/3]

String & String::operator= ( const char * source )

Assignment operator

Parameters

source A pointer to a char array

Returns: A reference to this

◆ operator=() [2/3]

String & String::operator= ( const String & source )

Assignment operator

Parameters

source The object to copy

Returns: A reference to this

Here is the call graph for this function:

◆ operator=() [3/3]

String & String::operator= ( String && source )

noexcept

Move assignment operator

Parameters

source The object to move

Returns: A reference to this

◆ operator==()

bool active::utility::String::operator== ( const String & ref ) const

inline

Equality operator

Parameters

ref	The string to compare this to

Returns: True if the strings are identical

◆ operator[]()

char32_t String::operator[] ( size_type index ) const

Subscript operator

Parameters

index The required character position (unchecked - out of bounds behaviour undefined)

Returns: The character at the specified index

Here is the call graph for this function:

◆ padLeft()

String & String::padLeft	(	size_type	length,
		const String &	repeat = " " )

Pad the string with a repeated character to reach a specified length (so the existing content is flush with the left)

Parameters

length	The required string length
repeat	The character to repeatedly append util the length is met

Returns: A reference to this

Here is the call graph for this function:

◆ padRight()

String & String::padRight	(	size_type	length,
		const String &	repeat = " " )

Pad the string with a repeated character to reach a specified length (so the existing content is flush with the right)

Parameters

length	The required string length
repeat	The character to repeatedly insert util the length is met

Returns: A reference to this

Here is the call graph for this function:

Here is the caller graph for this function:

◆ popBack()

void String::popBack ( )

Remove the last character from the string

Here is the call graph for this function:

◆ replace()

String & String::replace	(	sizeOption	pos,
		sizeOption	num,
		const String &	source,
		size_type	start = 0,
		sizeOption	howMany = std::nullopt )

Replace a specified string segment with another string

Parameters

pos	The position to begin replacing (nullopt = append to end)
num	The number of chars to replace (nullopt = to the string end)
source	The replacement string
start	The start point in the replacement string
howMany	The number of chars to extract from the replacement string (nullopt inserts all)

Returns: A reference to this

Here is the call graph for this function:

Here is the caller graph for this function:

◆ replaceAll()

String & String::replaceAll	(	const String &	toFind,
		const String &	replacement = String() )

Replace all instances of a specified expression

Parameters

toFind	The expression to be replaced
replacement	The replacement expression

Returns: A reference to this

Here is the call graph for this function:

Here is the caller graph for this function:

◆ replaceAnyOf()

String & String::replaceAnyOf	(	const String &	charsToFind,
		const String &	replacement = String() )

Replace any instances of specified characters

Parameters

charsToFind	The characters to be replaced (NB: each character is treated independently - the order does not matter)
replacement	The replacement expression

Returns: A reference to this

Here is the call graph for this function:

◆ replaceIf()

String & String::replaceIf	(	const Filter &	filter,
		const String &	replacement = String() )

Replace all chars passing a specified filter

Parameters

filter	The filter for chars to be replaced
replacement	The replacement expression

Returns: A reference to this

Here is the call graph for this function:

◆ reserve()

void String::reserve ( size_type newSize )

Reserve the specified number of bytes for the string to grow into

Parameters

newSize The number of bytes to reserve

Here is the caller graph for this function:

◆ resize()

void String::resize	(	size_type	newSize,
		const String &	padding = "" )

Resize the string and (when grown) pad with the specified character

Parameters

newSize	The required number of characters
padding	A padding character (when the sring grows - only the first character is used)

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rfind()

String::sizeOption String::rfind	(	const String &	toFind,
		sizeOption	lastPos = std::nullopt ) const

Find the specified string searching backwards

Parameters

toFind	The string to find
lastPos	The position of the last character to be compared

Returns: The index of a matching string (nullopt = not found)

Here is the call graph for this function:

◆ size()

String::size_type String::size ( ) const

Get the number of characters in the string

Returns: The number of characters in the string

Here is the caller graph for this function:

◆ startsWith()

bool active::utility::String::startsWith ( const String & toFind ) const

inline

Determine if this string starts with a substring

Parameters

toFind The substring to find

Returns: True if this string starts with the substring

◆ string()

std::string active::utility::String::string ( ) const

inline

Return the string content as a std::string

Returns: A std::string representation

Here is the caller graph for this function:

◆ substr()

String String::substr	(	size_type	startPos = 0,
		sizeOption	howMany = std::nullopt ) const

Get a specified substring of this string

Parameters

startPos	The position of the first character
howMany	The number of characters to get (nullopt for full length)

Returns: The requested string segment

Here is the call graph for this function:

Here is the caller graph for this function:

◆ toUnicode()

std::optional< std::u32string > String::toUnicode	(	const char *&	text,
		String::sizeOption	howMany = std::nullopt,
		bool	isCountRequired = false )

static

Get a UTF-32 string from a UTF-8 source

Parameters

text	The source UTF-8 text (advances to the byte beyond the last counted character)
howMany	The number of bytes in the text (nullopt = null-terminated)
isCountRequired	True if the specified number of bytes must be valid (ignored if howMany = nullopt)

Returns: The unicode code point for the specified chars (nullopt on failure)

Here is the caller graph for this function:

◆ toUTF16()

std::optional< std::u16string > String::toUTF16	(	const char32_t *&	text,
		String::sizeOption	howMany = std::nullopt,
		bool	isCountRequired = false )

static

Get a UTF-16 string from a UTF-32 source

Parameters

text	The source text
howMany	The number of code points in the text (nullopt = null-terminated)
isCountRequired	True if the specified number of code points must be valid (ignored if howMany = nullopt)

Returns: The UTF-16 string read from the UTF-32 source (nullopt on error, including failure to meet isCountRequired condition)

Here is the caller graph for this function:

◆ uppercase()

String String::uppercase ( ) const

Create an uppercase version of the string

Returns: An uppercase version of the string

Here is the call graph for this function:

Here is the caller graph for this function:

◆ writeTo()

const BufferOut & String::writeTo	(	const BufferOut &	buffer,
		DataFormat	format = UTF8,
		bool	isNullAdded = true,
		sizeOption	howMany = std::nullopt,
		sizeOption	maxLen = std::nullopt ) const

Write this string to a buffer

Parameters

buffer	The destination buffer
format	The required output format
isNullAdded	True to add a terminating null
howMany	The number of characters to write (nullopt for all)
maxLen	The maximum number of chars to write

Returns: A reference to the destination

Here is the call graph for this function:

Here is the caller graph for this function:

◆ writeUTF16()

const BufferOut & String::writeUTF16	(	const BufferOut &	buffer,
		bool	isNullAdded = true,
		bool	isBigEndian = DataFormat::defaultEndian,
		sizeOption	howMany = std::nullopt,
		sizeOption	maxLen = std::nullopt ) const

Write this string as UTF-16 to a buffer

Parameters

buffer	The destination buffer
isNullAdded	True to add a terminating null
isBigEndian	True if byte ordering is big-endian
howMany	The number of characters to write (nullopt for all)
maxLen	The maximum number of chars the destination can hold (including terminating null - nullopt for full length)

Returns: A reference to the destination

Here is the call graph for this function:

Here is the caller graph for this function:

◆ writeUTF32()

const BufferOut & String::writeUTF32	(	const BufferOut &	buffer,
		bool	isNullAdded = true,
		bool	isBigEndian = DataFormat::defaultEndian,
		sizeOption	howMany = std::nullopt,
		sizeOption	maxLen = std::nullopt ) const

Write this string as UTF-32 to a buffer

Parameters

buffer	The destination buffer
isNullAdded	True to add a terminating null
isBigEndian	True if byte ordering is big-endian
howMany	The number of characters to write (nullopt for all)
maxLen	The maximum number of chars the destination can hold (including terminating null - nullopt for full length)

Returns: A reference to the destination

Here is the call graph for this function:

Here is the caller graph for this function:

◆ writeUTF8()

const BufferOut & String::writeUTF8	(	const BufferOut &	buffer,
		bool	isNullAdded = true,
		sizeOption	howMany = std::nullopt,
		sizeOption	maxLen = std::nullopt ) const

Write this string to a buffer (as internally encoded)

Parameters

buffer	The destination buffer
isNullAdded	True to add a terminating null
howMany	The number of characters to write (nullopt for all)
maxLen	The maximum number of bytes the destination can hold (including terminating null - nullopt for full length)

Returns: A reference to the destination

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ allFloat

const String active::utility::String::allFloat {"0123456789.-"}

static

All floating point characters (floating and integer)

All numeric characters (floating and integer)

◆ allNumeric

const String active::utility::String::allNumeric {"0123456789-"}

static

All numeric characters (integer and signed)

All numeric characters (floating and integer)

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

/Users/rwessel/Documents/Development/ActiveLib/Active/Utility/String.h
/Users/rwessel/Documents/Development/ActiveLib/Active/Utility/String.cpp

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ String() [1/22]

◆ String() [2/22]

◆ String() [3/22]

◆ String() [4/22]

◆ String() [5/22]

◆ String() [6/22]

◆ String() [7/22]

◆ String() [8/22]

◆ String() [9/22]

◆ String() [10/22]

◆ String() [11/22]

◆ String() [12/22]

◆ String() [13/22]

◆ String() [14/22]

◆ String() [15/22]

◆ String() [16/22]

◆ String() [17/22]

◆ String() [18/22]

◆ String() [19/22]

◆ String() [20/22]

◆ String() [21/22]

◆ String() [22/22]

◆ ~String()

Member Function Documentation

◆ append() [1/3]

◆ append() [2/3]

◆ append() [3/3]

◆ assign() [1/2]

◆ assign() [2/2]

◆ at()

◆ capacity()

◆ clear()

◆ compare()

◆ contains()

◆ data()

◆ dataSize()

◆ empty()

◆ endsWith()

◆ erase()

◆ find()

◆ findFirstNotOf()

◆ findFirstOf()

◆ findIf()

◆ findLastNotOf()

◆ findLastOf()

◆ forEach() [1/2]

◆ forEach() [2/2]

◆ fromUnicode()

◆ fromUTF16()

◆ getCharacterByteCount()

◆ getCharacterCount()

◆ getUnicodeChar()

◆ getValidByteCount()

◆ insert()

◆ isAlpha()

◆ isAlphaNumeric()

◆ isNumeric()

◆ length()

◆ lowercase()

◆ operator!=()

◆ operator+=() [1/2]

◆ operator+=() [2/2]

◆ operator<=>()

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ operator==()

◆ operator[]()

◆ padLeft()

◆ padRight()

◆ popBack()

◆ replace()

◆ replaceAll()

◆ replaceAnyOf()