Class Description

A mutable string, that provides public access to its internal buffer and fields. First of all, the existence of this class is motivated to reach a certain level of compatibility between source code that uses the ALib across different languages (currently Java, C# and C++) whose implementations share a similar AString class.

As the given C#/Java StringBuilder/Buffer classes are either "sealed" and/or do not provide direct access to the internal buffer, to avoid conversion to new immutable strings in certain situations, the A-Worx Library implements its own string class. More complex functions, like extended formatting operations are not supported and remain the domain of the language specific class libraries.

Null-state:

Class AString is 'nullable', which means, that an instance may have no internal character array allocated. If constructed with zero size, a null pointer or another AString which is 'nulled' (but not a non-null, zero length string object of any type), the allocation size is 0. Nevertheless, method Buffer will return a valid empty char[] (a static singleton). This has the advantage that in many situations the null-state is not needed to handled specially (those cases where the difference between a nulled and an empty string is irrelevant). Consequently, it makes a difference if an AString is constructed using AString() or "AString(\""). This allows to differentiate between 'nulled' AStrings and empty AStrings, which is quite handy in certain situations. An object that was filled already can be reset to represent null by either assigning a nulled AString, by invoking SetBuffer(0) or by invoking SetNull on the instance. See also methods IsNull, IsNotNull and Capacity. The methods Equals and CompareTo allow null comparisons. e.g. an nulled AString equals to another nulled AString but not to a zero length, not nulled AString.

Non-checking methods

In general, AString methods are internally checking the provided parameters. For example, method _( AString src, int regionStart, int regionLength = int.MaxValue) is adjusting the provided region information to fit to the size of the provided AString.
Chances are high, that the code invoking this method "knows" about the correctness of the region. In this case, the checks are redundant.

For avoiding unnecessary checks, various methods are provided by AString that omit such checks. These methods share the same name as the standard one, with the suffix "_NC" appended (NC stands for "no checks").

In the sample above, if the calling code was sure about the parameters regionStart and regionLength being in the bounds of src, method _NC( AString src, int regionStart, int regionLength ) can be used.

Attention

The following rules apply to all methods which suffixed by _NC:

Parameters are not checked for being null.
Index, size, length, region start/end and other parameters are not checked to be correct
If parameters are incorrect, the result of the methods is undefined and in debug compilations an assertion may be raised.
Append methods that in their original version would set a nulled AString to non nulled state in the case that an empty string or string region is appended, are not confirming to this principle in their _NC version. In other words, nulled strings keep being nulled if empty strings are appended.
In the Java and C# versions of the AWorx Library, the hash value of an AString object keeps being cached when invoking an _NC method. This may lead to wrong behavior, e.g. when an AString object is used as a key of a hash table. To avoid errors, within a context that makes use of an AStrings' hash value, before each hash code retrieval (C#: GetHashCode(), Java: hashCode()), it has to be certified that at least one of the methods manipulating the object has to be a non _NC method.
Apart from the previous points, the behavior and result of invoking an _NC version of a method is the same as of invoking the original version. The only difference is in a higher execution performance.

Public Static Methods
static bool	IsNull (Object o)

static bool	IsNullOrEmpty (AString ms)

Public Methods
Constructors and Destructor

	AString ()

	AString (int size)

	AString (AString src, int regionStart=0, int regionLength=int.MaxValue)

	AString (Substring src)

	AString (String src, int regionStart=0, int regionLength=int.MaxValue)

	AString (StringBuilder src, int regionStart=0, int regionLength=int.MaxValue)

Memory allocation and buffer access

char[]	Buffer ()

void	SetBuffer (int newCapacity)

void	EnsureRemainingCapacity (int spaceNeeded)

int	Capacity ()

void	SetNull ()

bool	IsNull ()

bool	IsNotNull ()

int	SetLength (int newLength)

void	SetLength_NC (int newLength)

int	Length ()

bool	IsEmpty ()

bool	IsNotEmpty ()

Insert and Delete

AString	Clear ()

AString	_ ()

AString	InsertAt (char[] src, int cStart, int cLength, int pos)

AString	InsertAt (AString src, int pos)

AString	InsertAt (Substring src, int pos)

AString	InsertAt (String src, int pos)

AString	InsertAt (StringBuilder src, int pos)

AString	InsertChars (char c, int qty, int pos)

AString	InsertChars (char c, int qty)

AString	ReplaceSubstring (char[] src, int cStart, int cLength, int regionStart, int regionLength)

AString	ReplaceSubstring (AString src, int regionStart, int regionLength)

AString	ReplaceSubstring (Substring src, int regionStart, int regionLength)

AString	ReplaceSubstring (String src, int regionStart, int regionLength)

AString	ReplaceRegion (char c, int regionStart, int regionLength)

AString	Delete (int regionStart, int regionLength=int.MaxValue)

AString	Delete_NC (int regionStart, int regionLength)

AString	DeleteStart (int regionLength)

AString	DeleteStart_NC (int regionLength)

AString	DeleteEnd (int regionLength)

AString	DeleteEnd_NC (int regionLength)

AString	Trim (char[] trimChars=null)

int	TrimAt (int idx, char[] trimChars=null)

AString	TrimStart (char[] trimChars=null)

AString	TrimEnd (char[] trimChars=null)

Basic formatting

AString	NewLine ()

AString	Tab (int tabSize, int minPad=1, char tabChar=' ')

AString	Field (int size=-1, Alignment alignment=Alignment.Right, char padChar=' ', int fieldStart=int.MaxValue)

Appending characters and strings

AString	_NC (char[] src, int regionStart, int regionLength)

AString	_ (Object src)

AString	_NC (Object src)

AString	_ (AString src)

AString	_ (AString src, int regionStart, int regionLength=int.MaxValue)

AString	_NC (AString src)

AString	_NC (AString src, int regionStart, int regionLength)

AString	_ (char[] src)

AString	_ (char[] src, int regionStart, int regionLength=int.MaxValue)

AString	_ (Substring substring)

AString	_NC (Substring src)

AString	_ (String src)

AString	_ (String src, int regionStart, int regionLength=int.MaxValue)

AString	_NC (String src)

AString	_NC (String src, int regionStart, int regionLength)

AString	_ (StringBuilder src)

AString	_ (StringBuilder src, int regionStart, int regionLength=int.MaxValue)

AString	_ (char c)

Comparison

int	CompareTo (String needle, Case sensitivity=Case.Sensitive, int needleRegionStart=0, int needleRegionLength=int.MaxValue, int regionStart=0, int regionLength=int.MaxValue)

int	CompareTo (AString needle, Case sensitivity=Case.Sensitive, int needleRegionStart=0, int needleRegionLength=int.MaxValue, int regionStart=0, int regionLength=int.MaxValue)

int	CompareTo (char[] needle, Case sensitivity=Case.Sensitive, int needleRegionStart=0, int needleRegionLength=int.MaxValue, int regionStart=0, int regionLength=int.MaxValue)

int	CompareTo (Substring needle, Case sensitivity=Case.Sensitive, int regionStart=0, int regionLength=int.MaxValue)

bool	ContainsAt (String needle, int pos, Case sensitivity=Case.Sensitive)

bool	ContainsAt (char[] needle, int needleStart, int needleLength, int pos, Case sensitivity=Case.Sensitive)

bool	ContainsAt (AString needle, int pos, Case sensitivity=Case.Sensitive)

bool	ContainsAt (Substring needle, int pos, Case sensitivity=Case.Sensitive)

bool	StartsWith (String needle, Case sensitivity=Case.Sensitive)

bool	StartsWith (AString needle, Case sensitivity=Case.Sensitive)

bool	StartsWith (Substring needle, Case sensitivity=Case.Sensitive)

bool	EndsWith (String needle, Case sensitivity=Case.Sensitive)

bool	EndsWith (AString needle, Case sensitivity=Case.Sensitive)

bool	EndsWith (Substring needle, Case sensitivity=Case.Sensitive)

override bool	Equals (Object o)

bool	Equals (AString compareString, Case sensitivity=Case.Sensitive)

bool	Equals (String compareString, Case sensitivity=Case.Sensitive)

bool	Equals (Substring compareString, Case sensitivity=Case.Sensitive)

bool	Equals (Object compareString, Case sensitivity=Case.Sensitive)

Search

int	IndexOf (char needle, int startIdx=0)

int	IndexOfOrLength (char needle)

int	IndexOfOrLength (char needle, int startIdx)

int	IndexOf (String needle, int startIdx=0, Case sensitivity=Case.Sensitive)

int	IndexOf (AString needle, int startIdx=0, Case sensitivity=Case.Sensitive)

int	IndexOf (Substring needle, int startIdx=0, Case sensitivity=Case.Sensitive)

int	IndexOfAny (char[] needles, Inclusion inclusion, int startIdx=0)

int	LastIndexOf (char needle, int startIndex=int.MaxValue)

int	LastIndexOfAny (char[] needles, Inclusion inclusion, int startIdx=int.MaxValue)

Replace

int	SearchAndReplace (char needle, char replacement, int startIdx=0)

int	SearchAndReplace (String searchStr, String newStr, int startIdx=0, int maxReplacements=int.MaxValue, Case sensitivity=Case.Sensitive)

int	SearchAndReplace (AString searchStr, AString newStr, int startIdx=0, int maxReplacements=int.MaxValue, Case sensitivity=Case.Sensitive)

AString	SearchAndReplaceAll (AString searchStr, AString newStr, int startIdx=0, int maxReplacements=int.MaxValue, Case sensitivity=Case.Sensitive)

AString	SearchAndReplaceAll (String searchStr, String newStr, int startIdx=0, int maxReplacements=int.MaxValue, Case sensitivity=Case.Sensitive)

AString	ToUpper (int regionStart=0, int regionLength=int.MaxValue)

AString	ToLower (int regionStart=0, int regionLength=int.MaxValue)

AString	Escape (Switch escape=Switch.On, int regionStart=0, int regionLength=int.MaxValue)

Convert

AString	_ (int value, int overrideWidth=0, NumberFormat numberFormat=null)

AString	_ (int value, NumberFormat numberFormat)

AString	_ (uint value, int overrideWidth=0, NumberFormat numberFormat=null)

AString	_ (uint value, NumberFormat numberFormat)

AString	_ (long value, int overrideWidth=0, NumberFormat numberFormat=null)

AString	_ (long value, NumberFormat numberFormat)

AString	_ (ulong value, int overrideWidth=0, NumberFormat numberFormat=null)

AString	_ (ulong value, NumberFormat numberFormat)

AString	_Bin (ulong value, int overrideWidth=0, NumberFormat numberFormat=null)

AString	_Bin (ulong value, NumberFormat numberFormat)

AString	_Hex (ulong value, int overrideWidth=0, NumberFormat numberFormat=null)

AString	_Hex (ulong value, NumberFormat numberFormat)

AString	_Oct (ulong value, int overrideWidth=0, NumberFormat numberFormat=null)

AString	_Oct (ulong value, NumberFormat numberFormat)

AString	_ (double value, int overrideWidth=0, NumberFormat numberFormat=null)

AString	_ (double value, NumberFormat numberFormat)

override String	ToString ()

String	ToString (int regionStart, int regionLength=int.MaxValue)

StringBuilder	ToString (StringBuilder result, int regionStart, int regionLength=int.MaxValue, bool appendMode=false)

StringBuilder	ToString (StringBuilder result, bool appendMode=false)

ulong	ParseDecDigits (int startIdx, out int newIdx)

long	ParseInt (int startIdx, NumberFormat numberFormat, out int newIdx)

long	ParseInt (int startIdx=0, NumberFormat numberFormat=null)

long	ParseInt (int startIdx, out int newIdx)

long	ParseInt (NumberFormat numberFormat, out int newIdx)

long	ParseInt (NumberFormat numberFormat)

long	ParseInt (out int newIdx)

ulong	ParseDec (int startIdx, NumberFormat numberFormat, out int newIdx)

ulong	ParseDec (int startIdx=0, NumberFormat numberFormat=null)

ulong	ParseDec (int startIdx, out int newIdx)

ulong	ParseDec (NumberFormat numberFormat, out int newIdx)

ulong	ParseDec (NumberFormat numberFormat)

ulong	ParseDec (out int newIdx)

ulong	ParseBin (int startIdx, NumberFormat numberFormat, out int newIdx)

ulong	ParseBin (int startIdx=0, NumberFormat numberFormat=null)

ulong	ParseBin (int startIdx, out int newIdx)

ulong	ParseBin (NumberFormat numberFormat, out int newIdx)

ulong	ParseBin (NumberFormat numberFormat)

ulong	ParseBin (out int newIdx)

ulong	ParseHex (int startIdx, NumberFormat numberFormat, out int newIdx)

ulong	ParseHex (int startIdx=0, NumberFormat numberFormat=null)

ulong	ParseHex (int startIdx, out int newIdx)

ulong	ParseHex (NumberFormat numberFormat, out int newIdx)

ulong	ParseHex (NumberFormat numberFormat)

ulong	ParseHex (out int newIdx)

ulong	ParseOct (int startIdx, NumberFormat numberFormat, out int newIdx)

ulong	ParseOct (int startIdx=0, NumberFormat numberFormat=null)

ulong	ParseOct (int startIdx, out int newIdx)

ulong	ParseOct (NumberFormat numberFormat, out int newIdx)

ulong	ParseOct (NumberFormat numberFormat)

ulong	ParseOct (out int newIdx)

double	ParseFloat (int startIdx, NumberFormat numberFormat, out int newIdx)

double	ParseFloat (int startIdx=0, NumberFormat numberFormat=null)

double	ParseFloat (int startIdx, out int newIdx)

double	ParseFloat (NumberFormat numberFormat, out int newIdx)

double	ParseFloat (NumberFormat numberFormat)

double	ParseFloat (out int newIdx)

C# std library interface implementation

override int	GetHashCode ()

Protected Fields
char[]	buffer =CString.NullBuffer

int	fieldReference =0
	A marker for the start of the actual field.

int	hash =0

int	length =0

int	tabReference =0
	The tab reference position. This is set when NewLine is invoked.

Protected Methods
bool	resizeRegion (int regionStart, int regionLength, int newLength)

Character access

char?	this[int idx] `[get, set]`

char	CharAt (int idx)

char	CharAt_NC (int idx)

void	SetCharAt (int idx, char c)

void	SetCharAt_NC (int idx, char c)

char	CharAtStart ()

char	CharAtStart_NC ()

char	CharAtEnd ()

char	CharAtEnd_NC ()

Constructor & Destructor Documentation

◆ AString() [1/6]

AString ( )

inline

Constructs an empty AString. Does not allocate a buffer.

◆ AString() [2/6]

AString ( int size )

inline

Constructor allocating a specific buffer size.

Note: This constructor is useful for AString objects whose minimum future string length is predictable to avoid recurring incremental allocations up to the known minimum size.

Parameters

size	The initial size of the internal buffer.

◆ AString() [3/6]

AString	(	AString	src,
		int	regionStart = `0`,
		int	regionLength = `int.MaxValue`
	)

inline

Constructor copying Substring another AString.

Parameters

src	The source AString to copy from.
regionStart	The start index in ms to append. Defaults to 0.
regionLength	The maximum length of the substring in ms to append. Defaults to int.MaxValue.

◆ AString() [4/6]

AString ( Substring src )

inline

Constructor copying a Substring.

Parameters

src	The source Substring to copy from.

◆ AString() [5/6]

AString	(	String	src,
		int	regionStart = `0`,
		int	regionLength = `int.MaxValue`
	)

inline

Constructor copying a region of a String.

Parameters

src	The source String to copy from.
regionStart	The start index in s to append. Defaults to 0.
regionLength	The maximum length of the substring in s to append. Defaults to int.MaxValue.

◆ AString() [6/6]

AString	(	StringBuilder	src,
		int	regionStart = `0`,
		int	regionLength = `int.MaxValue`
	)

inline

Constructor copying a region of a StringBuilder.

Parameters

src	The source StringBuilder to copy.
regionStart	The start index in ms to append. Defaults to 0.
regionLength	The maximum length of the substring in ms to append. Defaults to int.MaxValue.

Member Function Documentation

◆ _() [1/22]

AString _ ( )

inline

Clear the Buffer. Same as Clear(), really just a synonym to allow short code in alignment with the various "Append" methods named _(src)

Returns: this to allow concatenated calls.

◆ _() [2/22]

AString _ ( AString src )

inline

Append the given AString.

Parameters

src	The AString to append.

Returns: this to allow concatenated calls.

◆ _() [3/22]

AString _	(	AString	src,
		int	regionStart,
		int	regionLength = `int.MaxValue`
	)

inline

Append a region of an AString.

Parameters

src	The AString to append.
regionStart	The start of the region in src to append. Defaults to 0.
regionLength	The maximum length of the region in src to append. Defaults to int.MaxValue.

Returns: this to allow concatenated calls.

◆ _() [4/22]

AString _ ( char c )

inline

Append the given character.

Parameters

c	The character to append.

Returns: this to allow concatenated calls.

◆ _() [5/22]

AString _ ( char[] src )

inline

Append the given char[].

Parameters

src	The source array.

Returns: this to allow concatenated calls.

◆ _() [6/22]

AString _	(	char[]	src,
		int	regionStart,
		int	regionLength = `int.MaxValue`
	)

inline

Append a region of a char[].

Parameters

src	The source array.
regionStart	The start of the region in src to append. Defaults to 0.
regionLength	The maximum length of the region in src to append. Defaults to int.MaxValue.

Returns: this to allow concatenated calls.

◆ _() [7/22]

AString _	(	double	value,
		int	overrideWidth = `0`,
		NumberFormat	numberFormat = `null`
	)

inline

Formats and appends a double floating point value.

Parameter numberFormat defaults to null, which denotes this method to use the static singleton found in NumberFormat.Computational. To generate output better readable for humans, provide NumberFormat.Global, or a customized object of that type.

See NumberFormat for more information on formatting options.

Parameters

value	The value to append.
overrideWidth	If not `0` (the default), overrides the output width otherwise specified in field NumberFormat.IntegralPartMinimumWidth.
numberFormat	The format definition. Defaults to `null`.

Returns: this to allow concatenated calls.

◆ _() [8/22]

AString _	(	double	value,
		NumberFormat	numberFormat
	)

inline

Overloaded version of _(double,int,NumberFormat) which provides default parameter(s).

Parameters

value	The value to append.
numberFormat	The format definition. Defaults to `null`.

Returns: this to allow concatenated calls.

◆ _() [9/22]

AString _	(	int	value,
		int	overrideWidth = `0`,
		NumberFormat	numberFormat = `null`
	)

inline

Format and append a signed 32-Bit integer value.

Parameter numberFormat defaults to null, which denotes this method to use the static singleton found in NumberFormat.Computational. To generate output better readable for humans, provide NumberFormat.Global, or a customized object of that type.

See NumberFormat for more information on formatting options.

Parameters

value	The value to append.
overrideWidth	If not `0` (the default), overrides the output width otherwise specified in field NumberFormat.DecMinimumFieldWidth.
numberFormat	The format definition. Defaults to `null`.

Returns: this to allow concatenated calls.

◆ _() [10/22]

AString _	(	int	value,
		NumberFormat	numberFormat
	)

inline

Overloaded version of _(int,int,NumberFormat) which provides default parameter(s).

Parameters

value	The value to append.
numberFormat	The format definition. Defaults to `null`.

Returns: this to allow concatenated calls.

◆ _() [11/22]

AString _	(	long	value,
		int	overrideWidth = `0`,
		NumberFormat	numberFormat = `null`
	)

inline

Format and append a signed 64-Bit integer value.

Parameter numberFormat defaults to null, which denotes this method to use the static singleton found in NumberFormat.Computational. To generate output better readable for humans, provide NumberFormat.Global, or a customized object of that type.

See NumberFormat for more information on formatting options.

Parameters

value	The value to append.
overrideWidth	If not `0` (the default), overrides the output width otherwise specified in field NumberFormat.DecMinimumFieldWidth.
numberFormat	The format definition. Defaults to `null`.

Returns: this to allow concatenated calls.

◆ _() [12/22]

AString _	(	long	value,
		NumberFormat	numberFormat
	)

inline

Overloaded version of _(long,int,NumberFormat) which provides default parameter(s).

Parameters

value	The value to append.
numberFormat	The format definition. Defaults to `null`.

Returns: this to allow concatenated calls.

◆ _() [13/22]

AString _ ( Object src )

inline

Appends an object by invoking ToString on it.

Parameters

src	The AString compatible type to append

Returns: this to allow concatenated calls.

◆ _() [14/22]

AString _ ( String src )

inline

Append a String.

Parameters

src	The String to append.

Returns: this to allow concatenated calls.

◆ _() [15/22]

AString _	(	String	src,
		int	regionStart,
		int	regionLength = `int.MaxValue`
	)

inline

Append a region of a String.

Parameters

src	The String to append.
regionStart	The start of the region in src to append. Defaults to 0.
regionLength	The maximum length of the region in src to append. Defaults to int.MaxValue

Returns: this to allow concatenated calls.

◆ _() [16/22]

AString _ ( StringBuilder src )

inline

Append the given StringBuilder.

Parameters

src	The StringBuilder to append.

Returns: this to allow concatenated calls.

◆ _() [17/22]

AString _	(	StringBuilder	src,
		int	regionStart,
		int	regionLength = `int.MaxValue`
	)

inline

Append a region of a StringBuilder.

Parameters

src	The StringBuilder to append.
regionStart	The start of the region in src to append.
regionLength	The maximum length of the region in src to append. Defaults to int.MaxValue.

Returns: this to allow concatenated calls.

◆ _() [18/22]

AString _ ( Substring substring )

inline

Append a Substring.

Parameters

substring The source array.

Returns: this to allow concatenated calls.

◆ _() [19/22]

AString _	(	uint	value,
		int	overrideWidth = `0`,
		NumberFormat	numberFormat = `null`
	)

inline

Format and append an unsigned 32-Bit integer value.

Parameter numberFormat defaults to null, which denotes this method to use the static singleton found in NumberFormat.Computational. To generate output better readable for humans, provide NumberFormat.Global, or a customized object of that type.

See NumberFormat for more information on formatting options.

Parameters

value	The value to append.
overrideWidth	If not `0` (the default), overrides the output width otherwise specified in field NumberFormat.DecMinimumFieldWidth.
numberFormat	The format definition. Defaults to `null`.

Returns: this to allow concatenated calls.

◆ _() [20/22]

AString _	(	uint	value,
		NumberFormat	numberFormat
	)

inline

Overloaded version of _(uint,int,NumberFormat) which provides default parameter(s).

Parameters

value	The value to append.
numberFormat	The format definition. Defaults to `null`.

Returns: this to allow concatenated calls.

◆ _() [21/22]

AString _	(	ulong	value,
		int	overrideWidth = `0`,
		NumberFormat	numberFormat = `null`
	)

inline

Format and append an unsigned 64-Bit integer value.

Parameter numberFormat defaults to null, which denotes this method to use the static singleton found in NumberFormat.Computational. To generate output better readable for humans, provide NumberFormat.Global, or a customized object of that type.

See NumberFormat for more information on formatting options.

Parameters

value	The value to append.
overrideWidth	If not `0` (the default), overrides the output width otherwise specified in field NumberFormat.DecMinimumFieldWidth.
numberFormat	The format definition. Defaults to `null`.

Returns: this to allow concatenated calls.

◆ _() [22/22]

AString _	(	ulong	value,
		NumberFormat	numberFormat
	)

inline

Overloaded version of _(ulong,int,NumberFormat) which provides default parameter(s).

Parameters

value	The value to append.
numberFormat	The format definition. Defaults to `null`.

Returns: this to allow concatenated calls.

◆ _Bin() [1/2]

AString _Bin	(	ulong	value,
		int	overrideWidth = `0`,
		NumberFormat	numberFormat = `null`
	)

inline

Append a unsigned 64-Bit integer value in binary format.

Parameter numberFormat defaults to null, which denotes this method to use the static singleton found in NumberFormat.Computational. To generate output better readable for humans, provide NumberFormat.Global, or a customized object of that type.

See NumberFormat for more information on formatting options.

Parameters

value	The value to append.
overrideWidth	If not `0` (the default), overrides the output width otherwise specified in field NumberFormat.BinFieldWidth.
numberFormat	The format definition. Defaults to `null`.

Returns: this to allow concatenated calls.

◆ _Bin() [2/2]

AString _Bin	(	ulong	value,
		NumberFormat	numberFormat
	)

inline

Overloaded version of _Bin(ulong,int,NumberFormat) which provides default parameter(s).

Parameters

value	The value to append.
numberFormat	The format definition. Defaults to `null`.

Returns: this to allow concatenated calls.

◆ _Hex() [1/2]

AString _Hex	(	ulong	value,
		int	overrideWidth = `0`,
		NumberFormat	numberFormat = `null`
	)

inline

Append a unsigned 64-Bit integer value in hexadecimal format.

Parameter numberFormat defaults to null, which denotes this method to use the static singleton found in NumberFormat.Computational. To generate output better readable for humans, provide NumberFormat.Global, or a customized object of that type.

See NumberFormat for more information on formatting options.

Parameters

value	The value to append.
overrideWidth	If not `0` (the default), overrides the output width otherwise specified in field NumberFormat.HexFieldWidth.
numberFormat	The format definition. Defaults to `null`.

Returns: this to allow concatenated calls.

◆ _Hex() [2/2]

AString _Hex	(	ulong	value,
		NumberFormat	numberFormat
	)

inline

Overloaded version of _Hex(ulong,int,NumberFormat) which provides default parameter(s).

Parameters

value	The value to append.
numberFormat	The format definition. Defaults to `null`.

Returns: this to allow concatenated calls.

◆ _NC() [1/7]

AString _NC ( AString src )

inline

Append the given AString.

Attention: Non checking variant of original method. See Non-checking methods for _NC method variants.

Parameters

src	The AString to append.

Returns: this to allow concatenated calls.

◆ _NC() [2/7]

AString _NC	(	AString	src,
		int	regionStart,
		int	regionLength
	)

inline

Append a region of an AString.

Attention: Non checking variant of original method. See Non-checking methods for _NC method variants.

Parameters

src	The AString to append.
regionStart	The start of the region in src to append.
regionLength	The maximum length of the region in src to append.

Returns: this to allow concatenated calls.

◆ _NC() [3/7]

AString _NC	(	char[]	src,
		int	regionStart,
		int	regionLength
	)

inline

Appends a region of a character array.

Attention: Non checking variant of original method. See Non-checking methods for _NC method variants.

Parameters

src	The character array containing the region to append.
regionStart	The start of the region in src to append.
regionLength	The length of the region in src to append.

Returns: this to allow concatenated calls.

◆ _NC() [4/7]

AString _NC ( Object src )

inline

Appends an object by invoking ToString on it.

Attention: Non checking variant of original method. See Non-checking methods for _NC method variants.

Parameters

src	The AString compatible type to append

Returns: this to allow concatenated calls.

◆ _NC() [5/7]

AString _NC ( String src )

inline

Append a String.

Attention: Non checking variant of original method. See Non-checking methods for _NC method variants.

Parameters

src	The String to append.

Returns: this to allow concatenated calls.

◆ _NC() [6/7]

AString _NC	(	String	src,
		int	regionStart,
		int	regionLength
	)

inline

Append a region of a String.

Attention: Non checking variant of original method. See Non-checking methods for _NC method variants.

Parameters

src	The String to append.
regionStart	The start of the region in src to append.
regionLength	The maximum length of the region in src to append.

Returns: this to allow concatenated calls.

◆ _NC() [7/7]

AString _NC ( Substring src )

inline

Append a Substring.

Attention: Non checking variant of original method. See Non-checking methods for _NC method variants.

Parameters

src	The source Substring.

Returns: this to allow concatenated calls.

◆ _Oct() [1/2]

AString _Oct	(	ulong	value,
		int	overrideWidth = `0`,
		NumberFormat	numberFormat = `null`
	)

inline

Append a unsigned 64-Bit integer value in octal format.

Parameter numberFormat defaults to null, which denotes this method to use the static singleton found in NumberFormat.Computational. To generate output better readable for humans, provide NumberFormat.Global, or a customized object of that type.

See NumberFormat for more information on formatting options.

Parameters

value	The value to append.
overrideWidth	If not `0` (the default), overrides the output width otherwise specified in field NumberFormat.OctFieldWidth.
numberFormat	The format definition. Defaults to `null`.

Returns: this to allow concatenated calls.

◆ _Oct() [2/2]

AString _Oct	(	ulong	value,
		NumberFormat	numberFormat
	)

inline

Overloaded version of _Oct(ulong,int,NumberFormat) which provides default parameter(s).

Parameters

value	The value to append.
numberFormat	The format definition. Defaults to `null`.

Returns: this to allow concatenated calls.

◆ Buffer()

char [] Buffer ( )

inline

The internal buffer character array. This may, but should not be accessed directly. In case of external modifications be sure to adjust the length of this AString using SetLength.

Returns: The internal buffer array.

◆ Capacity()

int Capacity ( )

inline

Returns the current size of the internal buffer.

Returns: The size of the allocated buffer.

◆ CharAt()

char CharAt ( int idx )

inline

Retrieves the character at the given index. A range check is performed. If this fails, '\0' is returned.

Parameters

idx	The index of the character to read.

Returns: The character at the given index, or '\0' if index out of range.

◆ CharAt_NC()

char CharAt_NC ( int idx )

inline

Retrieves the character at the given index.

Attention: Non checking variant of original method. See Non-checking methods for _NC method variants.

Parameters

idx	The index of the character to read.

Returns: The character at the given index.

◆ CharAtEnd()

char CharAtEnd ( )

inline

Retrieve the last character. In case of an empty string, '\0' is returned.

Returns: The last character in the AString. If this instance's length is zero, '\0' is returned.

◆ CharAtEnd_NC()

char CharAtEnd_NC ( )

inline

Retrieve the first character.

Attention: Non checking variant of original method. See Non-checking methods for _NC method variants.

Returns: The first character in the AString. If this instance's length is zero, '\0' is returned.

◆ CharAtStart()

char CharAtStart ( )

inline

Retrieve the first character. In case of an empty string, '\0' is returned.

Returns: The first character in the AString. If this instance's length is zero, '\0' is returned.

◆ CharAtStart_NC()

char CharAtStart_NC ( )

inline

Retrieve the first character.

Attention: Non checking variant of original method. See Non-checking methods for _NC method variants.

Returns: The first character in the AString. If this instance's length is zero, '\0' is returned.

◆ Clear()

AString Clear ( )

inline

Clear the Buffer. Same as Delete (0, Length()) but without internal region checks.

Returns: this to allow concatenated calls.

◆ CompareTo() [1/4]

int CompareTo	(	AString	needle,
		Case	sensitivity = `Case.Sensitive`,
		int	needleRegionStart = `0`,
		int	needleRegionLength = `int.MaxValue`,
		int	regionStart = `0`,
		int	regionLength = `int.MaxValue`
	)

inline

Compares a given region of a given string with a region of this instance. Regions that are out of bounds get adjusted and then compared.

Parameters

needle	An object of type AString that is compared to this.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.
needleRegionStart	The start of the substring within the given string that is to be compared to this. Defaults to 0.
needleRegionLength	The length of the substring within the given string that is to be compared to this. Defaults to Integer.MAX_VALUE.
regionStart	The start of the substring within this string that is to be compared. Defaults to 0.
regionLength	The length of the substring within this string that is to be compared. Defaults to Integer.MAX_VALUE.

Returns

0 if this and needle are nulled or if both have a length of 0 or if both share the same content
<0 if this is nulled and needle is not or if this is smaller than needle.
>0 if this is not nulled but needle is or if this is greater than needle.

◆ CompareTo() [2/4]

int CompareTo	(	char[]	needle,
		Case	sensitivity = `Case.Sensitive`,
		int	needleRegionStart = `0`,
		int	needleRegionLength = `int.MaxValue`,
		int	regionStart = `0`,
		int	regionLength = `int.MaxValue`
	)

inline

Compares a given region of a given string with a region of this instance. Regions that are out of bounds get adjusted and then compared.

Parameters

needle	An object of type char[] that is compared to this.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.
needleRegionStart	The start of the substring within the given string that is to be compared to this. Defaults to 0.
needleRegionLength	The length of the substring within the given string that is to be compared to this. Defaults to Integer.MAX_VALUE.
regionStart	The start of the substring within this string that is to be compared. Defaults to 0.
regionLength	The length of the substring within this string that is to be compared. Defaults to Integer.MAX_VALUE.

Returns

0 if this and needle are nulled or if both have a length of 0 or if both share the same content
<0 if this is nulled and needle is not or if this is smaller than needle.
>0 if this is not nulled but needle is or if this is greater than needle.

◆ CompareTo() [3/4]

int CompareTo	(	String	needle,
		Case	sensitivity = `Case.Sensitive`,
		int	needleRegionStart = `0`,
		int	needleRegionLength = `int.MaxValue`,
		int	regionStart = `0`,
		int	regionLength = `int.MaxValue`
	)

inline

Compares a given region of a given string with a region of this instance. Regions that are out of bounds get adjusted and then compared.

Parameters

needle	An object of type String that is compared to this.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.
needleRegionStart	The start of the substring within the given string that is to be compared to this. Defaults to 0.
needleRegionLength	The length of the substring within the given string that is to be compared to this. Defaults to Integer.MAX_VALUE.
regionStart	The start of the substring within this string that is to be compared. Defaults to 0.
regionLength	The length of the substring within this string that is to be compared. Defaults to Integer.MAX_VALUE.

Returns

0 if this and needle are nulled or if both have a length of 0 or if both share the same content
<0 if this is nulled and needle is not or if this is smaller than needle.
>0 if this is not nulled but needle is or if this is greater than needle.

◆ CompareTo() [4/4]

int CompareTo	(	Substring	needle,
		Case	sensitivity = `Case.Sensitive`,
		int	regionStart = `0`,
		int	regionLength = `int.MaxValue`
	)

inline

Compares a Substring with a region of this instance. The region bounds get adjusted to fit to this AString. (If this is not wanted, external checks have to be made prior to calling this method.)

Parameters

needle	An object of type char[] that is compared to this.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.
regionStart	The start of the substring within this string that is to be compared. Defaults to 0.
regionLength	The length of the substring within this string that is to be compared. Defaults to Integer.MAX_VALUE.

Returns

0 if this and needle are nulled or if both have a length of 0 or if both share the same content
<0 if this is nulled and needle is not or if this is smaller than needle.
>0 if this is not nulled but needle is or if this is greater than needle.

◆ ContainsAt() [1/4]

bool ContainsAt	(	AString	needle,
		int	pos,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Checks if the given AString is located at the given position.

Parameters

needle	The AString to search.
pos	The position to look at.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.

Returns: True if the given AString is found at the given position. False otherwise.

◆ ContainsAt() [2/4]

bool ContainsAt	(	char[]	needle,
		int	needleStart,
		int	needleLength,
		int	pos,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Checks if a region of a char[] is located at the given position.

Parameters

needle	The character array containing the needle.
needleStart	The index of the start of the needle within the character array.
needleLength	The length of the needle within the character array.
pos	The position to look at.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.

Returns: True if the given AString is found at the given position. False otherwise.

◆ ContainsAt() [3/4]

bool ContainsAt	(	String	needle,
		int	pos,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Checks if the given String is located at the given position.

Parameters

needle	The string to search.
pos	The position to look at.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.

Returns: True if the given sequence is found at the given position. False otherwise .

◆ ContainsAt() [4/4]

bool ContainsAt	(	Substring	needle,
		int	pos,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Checks if the given AString is located at the given position.

Parameters

needle	The AString to search.
pos	The position to look at.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.

Returns: True if the given AString is found at the given position. False otherwise.

◆ Delete()

AString Delete	(	int	regionStart,
		int	regionLength = `int.MaxValue`
	)

inline

Cuts out a region from the Buffer. A range check is performed and the region is cut to fit to the string.

Note: See also methods Clear, DeleteStart, DeleteStart_NC, DeleteEnd and DeleteEnd_NC.

Parameters

regionStart	The start of the region to delete.
regionLength	The length of the region to delete. Defaults to int.MaxValue

Returns: this to allow concatenated calls.

◆ Delete_NC()

AString Delete_NC	(	int	regionStart,
		int	regionLength
	)

inline

Cuts out a region from the Buffer.

Attention: Non checking variant of original method. See Non-checking methods for _NC method variants. Like with method Delete, it is allowed that the sum of parameters regionStart and regionLength is longer than the length of this AString. In this case, this string is cut starting from index regionStart.

Parameters

regionStart	The start of the region to delete.
regionLength	The length of the region to delete.

Returns: this to allow concatenated calls.

◆ DeleteEnd()

AString DeleteEnd ( int regionLength )

inline

Deletes the given number of characters from the end of the string. The given region length is checked to be between 0 and length.

Attention: Non checking variant of original method. See Non-checking methods for _NC method variants.

Parameters

regionLength The length of the region at the end to delete.

Returns: this to allow concatenated calls.

◆ DeleteEnd_NC()

AString DeleteEnd_NC ( int regionLength )

inline

Deletes the given number of characters from the end of the string.

Attention: Non checking variant of original method. See Non-checking methods for _NC method variants.

Parameters

regionLength The length of the region at the end to delete.

Returns: this to allow concatenated calls.

◆ DeleteStart()

AString DeleteStart ( int regionLength )

inline

Deletes the given number of characters from the start of the string. The given region length is checked to be between 0 and length.

Parameters

regionLength The length of the region at the start to delete.

Returns: this to allow concatenated calls.

◆ DeleteStart_NC()

AString DeleteStart_NC ( int regionLength )

inline

Deletes the given number of characters from the start of the string.

Attention: Non checking variant of original method. See Non-checking methods for _NC method variants.

Parameters

regionLength The length of the region at the start to delete.

Returns: this to allow concatenated calls.

◆ EndsWith() [1/3]

bool EndsWith	(	AString	needle,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Checks if this AString ends with the given AString.

Parameters

needle	The AString to be compared with the start of this AString. If this is null or empty, true is returned.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.

Returns: true if this starts with the given AString, false if not.

◆ EndsWith() [2/3]

bool EndsWith	(	String	needle,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Checks if this String ends with the given String.

Parameters

needle	The string to be compared with the start of this AString. If this is null or empty, true is returned.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.

Returns: true if this starts with the given String, false if not.

◆ EndsWith() [3/3]

bool EndsWith	(	Substring	needle,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Checks if this AString ends with the given Substring.

Parameters

needle	The Substring to be compared with the start of this AString. If this is null or empty, true is returned.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.

Returns: true if this starts with the given Substring, false if not.

◆ EnsureRemainingCapacity()

void EnsureRemainingCapacity ( int spaceNeeded )

inline

Ensures that the capacity of the internal buffer meets or exceeds the actual length plus the given growth value.

Parameters

spaceNeeded The desired growth of the length of the string represented by this.

◆ Equals() [1/5]

bool Equals	(	AString	compareString,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Tests and returns true, if the given AString equals to what this object represents. True is returned if both are zero length or null.

Parameters

compareString	The AString that is compared to this AString.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.

Returns: true, if contents of this and the given AString are equal

◆ Equals() [2/5]

bool Equals	(	Object	compareString,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Tests and returns true, if the given string-type object equals to what this object represents. True is returned if both are zero length or null. If compiled in debug mode, an assertion is thrown if the given object is not of type String, AString, Substring or char[].

Parameters

compareString	An object of string-type that is compared to this AString.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.

Returns: true, if contents of this and the given Substring are equal

◆ Equals() [3/5]

override bool Equals ( Object o )

inline

Compares this to the given object. Given object can be AString or String.

Parameters

o	The Object that this instance is compared with.

Returns: True if given object equals this.

◆ Equals() [4/5]

bool Equals	(	String	compareString,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Tests and returns true, if the given String equals to what this object represents. True is returned if both are zero length or null.

Parameters

compareString	The AString that is compared to this AString.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.

Returns: true, if contents of this and the given AString are equal

◆ Equals() [5/5]

bool Equals	(	Substring	compareString,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Tests and returns true, if the given Substring equals to what this object represents. True is returned if both are zero length or null.

Parameters

compareString	The Substring that is compared to this AString.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.

Returns: true, if contents of this and the given Substring are equal

◆ Escape()

AString Escape	(	Switch	escape = `Switch.On`,
		int	regionStart = `0`,
		int	regionLength = `int.MaxValue`
	)

inline

Escapes non-printable characters in the given region, or converts such escaped characters to their ASCII values.
If the new region length is needed to be known, it can be calculated as the sum of the old region length and the difference of the string before and after the operation.

Parameters

escape	Switch.On escapes ascii characters (the default), Switch.Off converts escaped strings to ascii codes.
regionStart	The start of the region to convert.
regionLength	The length of the region to convert.

Returns: this to allow concatenated calls.

◆ Field()

AString Field	(	int	size = `-1`,
		Alignment	alignment = `Alignment.Right`,
		char	padChar = `' '`,
		int	fieldStart = `int.MaxValue`
	)

inline

If invoked without parameters, the start of a field is marked at the current end of the string. Otherwise the end of a field is set and the contents between the field start marker and the current end of the string is aligned within the field using the given pad character. Note: To implement nested fields, the outer fields have to be set by providing the start marker by using the parameter fieldStart. Hence, only the starting points of the most inner fields can be set using this method without parameters.

Parameters

size	The field size in relation to the starting index of the field, defined either by using Field() prior to this invocation or by providing the parameter fieldStart. The field gets filled with the given pad character to meet the size while the content gets aligned left, right or centered. If the content exceeds the size, then no alignment takes place.
alignment	The alignment of the contents within the field. Defaults to Alignment.Right. Other options are Alignment.Left and Alignment.Center.
padChar	The character used to fill the field up to its size. Defaults to ' ' (space).
fieldStart	This parameter, if given, overwrites the start index of the field. The invocation of Field can be omitted, when this value is explicitly provided. Defaults to int.MaxValue.

Returns: this to allow concatenated calls.

◆ GetHashCode()

override int GetHashCode ( )

inline

Calculates the hash value using the same formula as java.lang.String.

Returns: A hash value for this object.

◆ IndexOf() [1/4]

int IndexOf	(	AString	needle,
		int	startIdx = `0`,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Search the given AString in the this.

Parameters

needle	The string to search.
startIdx	The index to start the search at. Optional and defaults to `0`.
sensitivity	If true, the compare is case insensitive. Optional and defaults to false.

Returns: -1 if the String is not found. Otherwise the index of first occurrence.

◆ IndexOf() [2/4]

int IndexOf	(	char	needle,
		int	startIdx = `0`
	)

inline

Search the given character in the buffer.

Parameters

needle	The character to search.
startIdx	The index to start the search at. Optional and defaults to `0`.

Returns: -1 if the character is not found. Otherwise the index of first occurrence.

◆ IndexOf() [3/4]

int IndexOf	(	String	needle,
		int	startIdx = `0`,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Search the given String in this.

Parameters

needle	The String to search.
startIdx	The index to start the search at. Optional and defaults to `0`.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.

Returns: -1 if the String is not found. Otherwise the index of first occurrence.

◆ IndexOf() [4/4]

int IndexOf	(	Substring	needle,
		int	startIdx = `0`,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Search the given Substring in the this.

Parameters

needle	The string to search.
startIdx	The index to start the search at. Optional and defaults to `0`.
sensitivity	If true, the compare is case insensitive. Optional and defaults to false.

Returns: -1 if the String is not found. Otherwise the index of first occurrence.

◆ IndexOfAny()

int IndexOfAny	(	char[]	needles,
		Inclusion	inclusion,
		int	startIdx = `0`
	)

inline

Returns the index of the first character which is included, respectively not included in a given set of characters.

This method searches from left to right. For reverse search, see LastIndexOfAny.

Parameters

needles	AString with characters to be searched for.
inclusion	Denotes whether the search returns the first index that holds a value that is included or that is not excluded in the set of needle characters.
startIdx	The index to start the search at. If the given value is less than 0, it is set to 0. If it exceeds the length of the string, the length of the string is returned. Defaults to 0.

Returns: The index of the first character found which is included, respectively not included, in the given set of characters. If nothing is found, -1 is returned.

◆ IndexOfOrLength() [1/2]

int IndexOfOrLength ( char needle )

inline

Like IndexOf but in case the character is not found, this method returns the length of this string instead of -1. Depending on the invocation context, the choice for the right version of this method may lead to shorter and more efficient code.

Parameters

needle The character to search for.

Returns: This strings Length if the character needle is not found. Otherwise the index of first occurrence.

◆ IndexOfOrLength() [2/2]

int IndexOfOrLength	(	char	needle,
		int	startIdx
	)

inline

Like IndexOf but in case the character is not found, this method returns the length of this string instead of -1. Depending on the invocation context, the choice for the right version of this method may lead to shorter and more efficient code.

Parameters

needle	The character to search for.
startIdx	The index in this to start searching the character.

Returns: This strings Length if the character needle is not found. Otherwise the index of first occurrence.

◆ InsertAt() [1/5]

AString InsertAt	(	AString	src,
		int	pos
	)

inline

Inserts a Substring . If the position is not between 0 and the length of the target, nothing is inserted.

Note: To insert a string with replacing a different one at the same time, use one of the overloaded methods ReplaceSubstring.

Parameters

src	The char[] to insert characters from.
pos	The position in this object insert the portion of src.

Returns: this to allow concatenated calls.

◆ InsertAt() [2/5]

AString InsertAt	(	char[]	src,
		int	cStart,
		int	cLength,
		int	pos
	)

inline

Inserts a portion of the given char[] at a given position. If the position is not between 0 and the length of the target, nothing is inserted.

Attention: Parameters cStart and cLength are not checked to match the size of src.

Note: To insert a string with replacing a different one at the same time, use ReplaceSubstring(src, pos, regionLength).

Parameters

src	The char[] to insert characters from.
cStart	The start of the substring in src to insert.
cLength	The length of the substring in src to insert.
pos	The position in this object insert the portion of src.

Returns: this to allow concatenated calls.

◆ InsertAt() [3/5]

AString InsertAt	(	String	src,
		int	pos
	)

inline

Inserts a String at a given position. If the position is not between 0 and the length of the target, nothing is inserted.

Note: To insert a string with replacing a different one at the same time, use one of the overloaded methods ReplaceSubstring.

Parameters

src	The char[] to insert characters from.
pos	The position in this object insert the portion of src.

Returns: this to allow concatenated calls.

◆ InsertAt() [4/5]

AString InsertAt	(	StringBuilder	src,
		int	pos
	)

inline

Inserts a StringBuilder at a given position. If the position is not between 0 and the length of the target, nothing is inserted.

Note: To insert a string with replacing a different one at the same time, use one of the overloaded methods ReplaceSubstring.

Parameters

src	The char[] to insert characters from.
pos	The position in this object insert the portion of src.

Returns: this to allow concatenated calls.

◆ InsertAt() [5/5]

AString InsertAt	(	Substring	src,
		int	pos
	)

inline

Inserts a Substring at a given position. If the position is not between 0 and the length of the target, nothing is inserted.

Note: To insert a string with replacing a different one at the same time, use one of the overloaded methods ReplaceSubstring.

Parameters

src	The char[] to insert characters from.
pos	The position in this object insert the portion of src.

Returns: this to allow concatenated calls.

◆ InsertChars() [1/2]

AString InsertChars	(	char	c,
		int	qty
	)

inline

Inserts the given character n-times at the end of this string (appends).

Parameters

c	The character to append.
qty	The quantity of characters to append.

Returns: this to allow concatenated calls.

◆ InsertChars() [2/2]

AString InsertChars	(	char	c,
		int	qty,
		int	pos
	)

inline

Inserts the given character n-times at a given position. If the given position is out of range, nothing is inserted.

Parameters

c	The character to insert qty times.
qty	The quantity of characters to insert.
pos	The index in this object where c is inserted qty times.

Returns: this to allow concatenated calls.

◆ IsEmpty()

bool IsEmpty ( )

inline

Returns true if the actual length equals zero.

Returns: true if the actual length equals zero.

◆ IsNotEmpty()

bool IsNotEmpty ( )

inline

Returns true if the actual length does not equal zero.

Returns: true if the actual length does not equal zero.

◆ IsNotNull()

bool IsNotNull ( )

inline

Returns false if no buffer space is allocated, true otherwise. This might be the case, if constructed with AString() or AString(0), by invoking SetBuffer(0) or SetNull.

Returns: true if no buffer is allocated.

◆ IsNull() [1/2]

bool IsNull ( )

inline

Returns true if no buffer space is allocated, false otherwise. This might be the case, if constructed with AString() or AString(0), by invoking SetBuffer(0) or SetNull.

Returns: true if no buffer is allocated.

◆ IsNull() [2/2]

static bool IsNull ( Object o )

inlinestatic

Static method to test if an arbitrary object is null. In case of type AString or Substring null is returned when they are nulled.

Parameters

o	The object to test

Returns: true if given object is null or a nulled ALib string type.

◆ IsNullOrEmpty()

static bool IsNullOrEmpty ( AString ms )

inlinestatic

Static method to test if an AString is null or has a length of 0.

Parameters

ms	The AString to test.

Returns: true if given AString is null or has a length of 0.

◆ LastIndexOf()

int LastIndexOf	(	char	needle,
		int	startIndex = `int.MaxValue`
	)

inline

Searches a character backwards starting at the end or at given start index.

Parameters

needle	The character to search for.
startIndex	The index in this to start searching the character. Defaults to CString.MaxLen.

Returns: -1 if the character needle is not found. Otherwise the index of its last occurrence relative to the start index.

◆ LastIndexOfAny()

int LastIndexOfAny	(	char[]	needles,
		Inclusion	inclusion,
		int	startIdx = `int.MaxValue`
	)

inline

Returns the index of the first character which is included, respectively not included in a given set of characters. The search starts at the given index and goes backward. For forward search, see IndexOfAny.

Parameters

needles	AString with characters to be searched for.
inclusion	Denotes whether the search returns the first index that holds a value that is included or that is not excluded in the set of needle characters.
startIdx	The index to start the search at. The value is cropped to be in the bounds of 0 and the length of this AString minus one. Defaults to maximum integer value.

Returns: The index of the first character found which is included, respectively not included, in the given set of characters. If nothing is found, -1 is returned.

◆ Length()

int Length ( )

inline

Returns the actual length of this AString. This number is smaller or equals the number returned by Capacity.

Returns: The length of the string represented by this.

◆ NewLine()

AString NewLine ( )

inline

Appends platform specific new line character(s). ( "\\r\\n", "\\r", etc.). The new length of the string is recorded as the reference position for Tab.

Returns: this to allow concatenated calls.

◆ ParseBin() [1/6]

ulong ParseBin	(	int	startIdx,
		NumberFormat	numberFormat,
		out int	newIdx
	)

inline

Reads an unsigned 64-bit integer in binary format at the given position from this AString. This is done, by invoking NumberFormat.ParseBin on the given numberFormat instance.
Parameter numberFormat defaults to null. This denotes static singleton NumberFormat.Computational which is configured to not using - and therefore also not parsing - grouping characters.

Optional output parameter newIdx may be used to detect if parsing was successful. If not, it receives the value of startIdx, even if leading whitespaces had been read.

For more information on number conversion, see class NumberFormat. All of its interface methods have a corresponding implementation within class AString.

Parameters

	startIdx	The start index for parsing. Optional and defaults to `0`.
	numberFormat	The format definition. Defaults to `null`.
[out]	newIdx	Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value startIdx.

Returns: The parsed value. In addition, the output parameter newIdx is set to point to the first character behind the parsed number.

◆ ParseBin() [2/6]

ulong ParseBin	(	int	startIdx,
		out int	newIdx
	)

inline

Overloaded version of ParseBin providing default values for omitted parameters.

Parameters

	startIdx	The start index for parsing. Optional and defaults to `0`.
[out]	newIdx	Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value startIdx.

Returns: The parsed value. In addition, the output parameter newIdx is set to point to the first character behind the parsed number.

◆ ParseBin() [3/6]

ulong ParseBin	(	int	startIdx = `0`,
		NumberFormat	numberFormat = `null`
	)

inline

Overloaded version of ParseBin providing default values for omitted parameters.

Parameters

startIdx	The start index for parsing. Optional and defaults to `0`.
numberFormat	The format definition. Defaults to `null`.

Returns: The parsed value.

◆ ParseBin() [4/6]

ulong ParseBin ( NumberFormat numberFormat )

inline

Overloaded version of ParseBin providing default values for omitted parameters.

Parameters

numberFormat The format definition. Defaults to null.

Returns: The parsed value.

◆ ParseBin() [5/6]

ulong ParseBin	(	NumberFormat	numberFormat,
		out int	newIdx
	)

inline

Overloaded version of ParseBin providing default values for omitted parameters.

Parameters

	numberFormat	The format definition. Defaults to `null`.
[out]	newIdx	Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value `0`.

Returns: The parsed value. In addition, the input/output parameter idx is set to point to the first character behind any found integer number.

◆ ParseBin() [6/6]

ulong ParseBin ( out int newIdx )

inline

Overloaded version of ParseBin providing default values for omitted parameters.

Parameters

[out] newIdx Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value 0.

Returns: The parsed value. In addition, the input/output parameter idx is set to point to the first character behind any found integer number.

◆ ParseDec() [1/6]

ulong ParseDec	(	int	startIdx,
		NumberFormat	numberFormat,
		out int	newIdx
	)

inline

Reads an unsigned 64-bit integer in standard decimal format at the given position from this AString. This is done, by invoking NumberFormat.ParseDec on the given numberFormat instance.
Parameter numberFormat defaults to null. This denotes static singleton NumberFormat.Computational which is configured to not using - and therefore also not parsing - grouping characters.

Optional output parameter newIdx may be used to detect if parsing was successful. If not, it receives the value of startIdx, even if leading whitespaces had been read.

Sign literals '-' or '+' are not accepted and parsing will fail. For reading signed integer values, see methods ParseInt, for floating point numbers ParseFloat.

For more information on number conversion, see class NumberFormat. All of its interface methods have a corresponding implementation within class AString.

Parameters

	startIdx	The start index for parsing. Optional and defaults to `0`.
	numberFormat	The format definition. Defaults to `null`.
[out]	newIdx	Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value startIdx.

Returns: The parsed value. In addition, the output parameter newIdx is set to point to the first character behind the parsed number.

◆ ParseDec() [2/6]

ulong ParseDec	(	int	startIdx,
		out int	newIdx
	)

inline

Overloaded version of ParseDec providing default values for omitted parameters.

Parameters

	startIdx	The start index for parsing. Optional and defaults to `0`.
[out]	newIdx	Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value startIdx.

Returns: The parsed value. In addition, the output parameter newIdx is set to point to the first character behind the parsed number.

◆ ParseDec() [3/6]

ulong ParseDec	(	int	startIdx = `0`,
		NumberFormat	numberFormat = `null`
	)

inline

Overloaded version of ParseDec providing default values for omitted parameters.

Parameters

startIdx	The start index for parsing. Optional and defaults to `0`.
numberFormat	The format definition. Defaults to `null`.

Returns: The parsed value.

◆ ParseDec() [4/6]

ulong ParseDec ( NumberFormat numberFormat )

inline

Overloaded version of ParseDec providing default values for omitted parameters.

Parameters

numberFormat The format definition. Defaults to null.

Returns: The parsed value.

◆ ParseDec() [5/6]

ulong ParseDec	(	NumberFormat	numberFormat,
		out int	newIdx
	)

inline

Overloaded version of ParseDec providing default values for omitted parameters.

Parameters

	numberFormat	The format definition. Defaults to `null`.
[out]	newIdx	Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value `0`.

Returns: The parsed value. In addition, the input/output parameter idx is set to point to the first character behind any found integer number.

◆ ParseDec() [6/6]

ulong ParseDec ( out int newIdx )

inline

Overloaded version of ParseDec providing default values for omitted parameters.

Parameters

[out] newIdx Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value 0.

Returns: The parsed value. In addition, the input/output parameter idx is set to point to the first character behind any found integer number.

◆ ParseDecDigits()

ulong ParseDecDigits	(	int	startIdx,
		out int	newIdx
	)

inline

Parses an integer value consisting of characters '0' to '9' from this string.
Unlike with ParseInt or ParseDec, no sign, whitespaces or group characters are accepted.

Parameters

	startIdx	The start index from where the integer value is tried to be parsed. Optional and defaults to `0`.
[out]	newIdx	Optional output variable that will point to the first character in this string after the float number that was parsed. If parsing fails, it will be set to the value of parameter startIdx.

Returns: The parsed value. In addition, the input/output parameter idx is set to point to the first character behind any found integer number.

◆ ParseFloat() [1/6]

double ParseFloat	(	int	startIdx,
		NumberFormat	numberFormat,
		out int	newIdx
	)

inline

Reads a floating point number at the given position from this AString. This is done, by invoking NumberFormat.ParseFloat on the given numberFormat instance.
Parameter numberFormat defaults to null. This denotes static singleton NumberFormat.Computational which is configured to 'international' settings (not using the locale) and therefore also not parsing grouping characters.

Optional output parameter newIdx may be used to detect if parsing was successful. If not, it receives the value of startIdx, even if leading whitespaces had been read.

For more information on parsing options for floating point numbers and number conversion in general, see class NumberFormat. All of its interface methods have a corresponding implementation within class AString.

Parameters

	startIdx	The start index for parsing. Optional and defaults to `0`.
	numberFormat	The format definition. Defaults to `null`.
[out]	newIdx	Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value startIdx.

Returns: The parsed value. In addition, the output parameter newIdx is set to point to the first character behind the parsed number.

◆ ParseFloat() [2/6]

double ParseFloat	(	int	startIdx,
		out int	newIdx
	)

inline

Overloaded version of ParseFloat providing default values for omitted parameters.

Parameters

	startIdx	The start index for parsing. Optional and defaults to `0`.
[out]	newIdx	Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value startIdx.

Returns: The parsed value. In addition, the output parameter newIdx is set to point to the first character behind the parsed number.

◆ ParseFloat() [3/6]

double ParseFloat	(	int	startIdx = `0`,
		NumberFormat	numberFormat = `null`
	)

inline

Overloaded version of ParseFloat providing default values for omitted parameters.

Parameters

startIdx	The start index for parsing. Optional and defaults to `0`.
numberFormat	The format definition. Defaults to `null`.

Returns: The parsed value.

◆ ParseFloat() [4/6]

double ParseFloat ( NumberFormat numberFormat )

inline

Overloaded version of ParseFloat providing default values for omitted parameters.

Parameters

numberFormat The format definition. Defaults to null.

Returns: The parsed value.

◆ ParseFloat() [5/6]

double ParseFloat	(	NumberFormat	numberFormat,
		out int	newIdx
	)

inline

Overloaded version of ParseFloat providing default values for omitted parameters.

Parameters

	numberFormat	The format definition. Defaults to `null`.
[out]	newIdx	Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value `0`.

Returns: The parsed value. In addition, the input/output parameter idx is set to point to the first character behind any found integer number.

◆ ParseFloat() [6/6]

double ParseFloat ( out int newIdx )

inline

Overloaded version of ParseFloat providing default values for omitted parameters.

Parameters

[out] newIdx Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value 0.

Returns: The parsed value. In addition, the input/output parameter idx is set to point to the first character behind any found integer number.

◆ ParseHex() [1/6]

ulong ParseHex	(	int	startIdx,
		NumberFormat	numberFormat,
		out int	newIdx
	)

inline

Reads an unsigned 64-bit integer in hexadecimal format at the given position from this AString. This is done, by invoking NumberFormat.ParseHex on the given numberFormat instance.
Parameter numberFormat defaults to null. This denotes static singleton NumberFormat.Computational which is configured to not using - and therefore also not parsing - grouping characters.

Optional output parameter newIdx may be used to detect if parsing was successful. If not, it receives the value of startIdx, even if leading whitespaces had been read.

For more information on number conversion, see class NumberFormat. All of its interface methods have a corresponding implementation within class AString.

Parameters

	startIdx	The start index for parsing. Optional and defaults to `0`.
	numberFormat	The format definition. Defaults to `null`.
[out]	newIdx	Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value startIdx.

Returns: The parsed value. In addition, the output parameter newIdx is set to point to the first character behind the parsed number.

◆ ParseHex() [2/6]

ulong ParseHex	(	int	startIdx,
		out int	newIdx
	)

inline

Overloaded version of ParseHex providing default values for omitted parameters.

Parameters

	startIdx	The start index for parsing. Optional and defaults to `0`.
[out]	newIdx	Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value startIdx.

Returns: The parsed value. In addition, the output parameter newIdx is set to point to the first character behind the parsed number.

◆ ParseHex() [3/6]

ulong ParseHex	(	int	startIdx = `0`,
		NumberFormat	numberFormat = `null`
	)

inline

Overloaded version of ParseHex providing default values for omitted parameters.

Parameters

startIdx	The start index for parsing. Optional and defaults to `0`.
numberFormat	The format definition. Defaults to `null`.

Returns: The parsed value.

◆ ParseHex() [4/6]

ulong ParseHex ( NumberFormat numberFormat )

inline

Overloaded version of ParseHex providing default values for omitted parameters.

Parameters

numberFormat The format definition. Defaults to null.

Returns: The parsed value.

◆ ParseHex() [5/6]

ulong ParseHex	(	NumberFormat	numberFormat,
		out int	newIdx
	)

inline

Overloaded version of ParseHex providing default values for omitted parameters.

Parameters

	numberFormat	The format definition. Defaults to `null`.
[out]	newIdx	Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value `0`.

Returns: The parsed value. In addition, the input/output parameter idx is set to point to the first character behind any found integer number.

◆ ParseHex() [6/6]

ulong ParseHex ( out int newIdx )

inline

Overloaded version of ParseHex providing default values for omitted parameters.

Parameters

[out] newIdx Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value 0.

Returns: The parsed value. In addition, the input/output parameter idx is set to point to the first character behind any found integer number.

◆ ParseInt() [1/6]

long ParseInt	(	int	startIdx,
		NumberFormat	numberFormat,
		out int	newIdx
	)

inline

Parses a long integer value in decimal, binary, hexadecimal or octal format from the string by invoking method NumberFormat.ParseInt on the given numberFormat instance.
Parameter numberFormat defaults to null. This denotes static singleton NumberFormat.Computational which is configured to not using - and therefore also not parsing - grouping characters.

Optional output parameter newIdx may be used to detect if parsing was successful. If not, it receives the value of startIdx, even if leading whitespaces had been read.

For more information on number conversion, see class NumberFormat. All of its interface methods have a corresponding implementation within class AString.

Parameters

	startIdx	The start index for parsing. Optional and defaults to `0`.
	numberFormat	The format definition. Defaults to `null`.
[out]	newIdx	Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value startIdx.

Returns: The parsed value. In addition, the output parameter newIdx is set to point to the first character behind the parsed number.

◆ ParseInt() [2/6]

long ParseInt	(	int	startIdx,
		out int	newIdx
	)

inline

Overloaded version of ParseInt providing default values for omitted parameters.

Parameters

	startIdx	The start index for parsing. Optional and defaults to `0`.
[out]	newIdx	Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value startIdx.

Returns: The parsed value. In addition, the output parameter newIdx is set to point to the first character behind the parsed number.

◆ ParseInt() [3/6]

long ParseInt	(	int	startIdx = `0`,
		NumberFormat	numberFormat = `null`
	)

inline

Overloaded version of ParseInt providing default values for omitted parameters.

Parameters

startIdx	The start index for parsing. Optional and defaults to `0`.
numberFormat	The format definition. Defaults to `null`.

Returns: The parsed value.

◆ ParseInt() [4/6]

long ParseInt ( NumberFormat numberFormat )

inline

Overloaded version of ParseInt providing default values for omitted parameters.

Parameters

numberFormat The format definition. Defaults to null.

Returns: The parsed value.

◆ ParseInt() [5/6]

long ParseInt	(	NumberFormat	numberFormat,
		out int	newIdx
	)

inline

Overloaded version of ParseInt providing default values for omitted parameters.

Parameters

	numberFormat	The format definition. Defaults to `null`.
[out]	newIdx	Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value `0`.

Returns: The parsed value. In addition, the input/output parameter idx is set to point to the first character behind any found integer number.

◆ ParseInt() [6/6]

long ParseInt ( out int newIdx )

inline

Overloaded version of ParseInt providing default values for omitted parameters.

Parameters

[out] newIdx Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value 0.

Returns: The parsed value. In addition, the input/output parameter idx is set to point to the first character behind any found integer number.

◆ ParseOct() [1/6]

ulong ParseOct	(	int	startIdx,
		NumberFormat	numberFormat,
		out int	newIdx
	)

inline

Reads an unsigned 64-bit integer in octal format at the given position from this AString. This is done, by invoking NumberFormat.ParseOct on the given numberFormat instance.
Parameter numberFormat defaults to null. This denotes static singleton NumberFormat.Computational which is configured to not using - and therefore also not parsing - grouping characters.

Optional output parameter newIdx may be used to detect if parsing was successful. If not, it receives the value of startIdx, even if leading whitespaces had been read.

For more information on number conversion, see class NumberFormat. All of its interface methods have a corresponding implementation within class AString.

Parameters

	startIdx	The start index for parsing. Optional and defaults to `0`.
	numberFormat	The format definition. Defaults to `null`.
[out]	newIdx	Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value startIdx.

Returns: The parsed value. In addition, the output parameter newIdx is set to point to the first character behind the parsed number.

◆ ParseOct() [2/6]

ulong ParseOct	(	int	startIdx,
		out int	newIdx
	)

inline

Overloaded version of ParseOct providing default values for omitted parameters.

Parameters

	startIdx	The start index for parsing. Optional and defaults to `0`.
[out]	newIdx	Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value startIdx.

Returns: The parsed value. In addition, the output parameter newIdx is set to point to the first character behind the parsed number.

◆ ParseOct() [3/6]

ulong ParseOct	(	int	startIdx = `0`,
		NumberFormat	numberFormat = `null`
	)

inline

Overloaded version of ParseOct providing default values for omitted parameters.

Parameters

startIdx	The start index for parsing. Optional and defaults to `0`.
numberFormat	The format definition. Defaults to `null`.

Returns: The parsed value.

◆ ParseOct() [4/6]

ulong ParseOct ( NumberFormat numberFormat )

inline

Overloaded version of ParseOct providing default values for omitted parameters.

Parameters

numberFormat The format definition. Defaults to null.

Returns: The parsed value.

◆ ParseOct() [5/6]

ulong ParseOct	(	NumberFormat	numberFormat,
		out int	newIdx
	)

inline

Overloaded version of ParseOct providing default values for omitted parameters.

Parameters

	numberFormat	The format definition. Defaults to `null`.
[out]	newIdx	Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value `0`.

Returns: The parsed value. In addition, the input/output parameter idx is set to point to the first character behind any found integer number.

◆ ParseOct() [6/6]

ulong ParseOct ( out int newIdx )

inline

Overloaded version of ParseOct providing default values for omitted parameters.

Parameters

[out] newIdx Optional output variable that will point to the first character in this string after the number parsed. On failure, it will be set to the initial value 0.

Returns: The parsed value. In addition, the input/output parameter idx is set to point to the first character behind any found integer number.

◆ ReplaceRegion()

AString ReplaceRegion	(	char	c,
		int	regionStart,
		int	regionLength
	)

inline

Replaces a region in the string with the given character. The region is adjusted to fit into the current length. In other words, the length of this instances remains the same.

Note: To replace a region with a single character (by shrinking the region to this character) use ReplaceSubstring( " + c, regionStart, regionLength)".

Parameters

c	The character to set in the region.
regionStart	The start of the region
regionLength	The length of the region

Returns: this to allow concatenated calls.

◆ ReplaceSubstring() [1/4]

AString ReplaceSubstring	(	AString	src,
		int	regionStart,
		int	regionLength
	)

inline

Replaces a region in this object by a given AString. If the region does not fit to this object, then nothing is done.

Parameters

src	The replacement string.
regionStart	The start of the region.
regionLength	The length of the region.

Returns: this to allow concatenated calls.

◆ ReplaceSubstring() [2/4]

AString ReplaceSubstring	(	char[]	src,
		int	cStart,
		int	cLength,
		int	regionStart,
		int	regionLength
	)

inline

Replaces a region in this object by a portion of a character array. If the region does not fit to this object, then nothing is done.

Attention: Parameters cStart and cLength are not checked to match the size of src.

Parameters

src	The char[] to insert characters from.
cStart	The start of the substring in src to insert.
cLength	The length of the substring in src to insert.
regionStart	The start of the region.
regionLength	The length of the region.

Returns: this to allow concatenated calls.

◆ ReplaceSubstring() [3/4]

AString ReplaceSubstring	(	String	src,
		int	regionStart,
		int	regionLength
	)

inline

Replaces a region in this object by a given string. If the region does not fit to this object, then nothing is done.

Parameters

src	The replacement string.
regionStart	The start of the region.
regionLength	The length of the region.

Returns: this to allow concatenated calls.

◆ ReplaceSubstring() [4/4]

AString ReplaceSubstring	(	Substring	src,
		int	regionStart,
		int	regionLength
	)

inline

Replaces a region in this object by a given Substring. If the region does not fit to this object, then nothing is done.

Parameters

src	The replacement string.
regionStart	The start of the region.
regionLength	The length of the region.

Returns: this to allow concatenated calls.

◆ resizeRegion()

bool resizeRegion	(	int	regionStart,
		int	regionLength,
		int	newLength
	)

inlineprotected

Protected method that resizes a region into the Buffer. The region contents is undefined.

Parameters

regionStart	The start of the region to insert. If this is out of the string bounds (hence less than 0 or greater then Length), nothing is done.
regionLength	The current length of the region.
newLength	The desired length of the region.

Returns: true, if the parameters were OK and the region was resized, false otherwise.

◆ SearchAndReplace() [1/3]

int SearchAndReplace	(	AString	searchStr,
		AString	newStr,
		int	startIdx = `0`,
		int	maxReplacements = `int.MaxValue`,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Replace one or more occurrences of a string by another string. Returns the number of replacements.

Parameters

searchStr	The String to be replaced.
newStr	The replacement string.
startIdx	The index where the search starts. Optional and defaults to 0.
maxReplacements	The maximum number of replacements to perform. Optional and defaults to int.MaxValue .
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.

Returns: The number of replacements that where performed.

◆ SearchAndReplace() [2/3]

int SearchAndReplace	(	char	needle,
		char	replacement,
		int	startIdx = `0`
	)

inline

Replaces one or more occurrences of one character by another character.

Parameters

needle	The terminatable string to be replaced.
replacement	The replacement string (does not need to be zero terminatable).
startIdx	The index where the search starts. Optional and defaults 0.

Returns: The number of replacements that where performed.

◆ SearchAndReplace() [3/3]

int SearchAndReplace	(	String	searchStr,
		String	newStr,
		int	startIdx = `0`,
		int	maxReplacements = `int.MaxValue`,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Replace one or more occurrences of a string by another string. Returns the number of replacements.

Parameters

searchStr	The String to be replaced.
newStr	The replacement string.
startIdx	The index where the search starts. Optional and defaults to 0.
maxReplacements	The maximum number of replacements to perform. Optional and defaults to int.MaxValue .
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.

Returns: The number of replacements that where performed.

◆ SearchAndReplaceAll() [1/2]

AString SearchAndReplaceAll	(	AString	searchStr,
		AString	newStr,
		int	startIdx = `0`,
		int	maxReplacements = `int.MaxValue`,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Replace one or more occurrences of a string by another string.

Note: The difference to SearchAndReplace is that this method returns this to allow concatenated calls.

Parameters

searchStr	The String to be replaced.
newStr	The replacement string.
startIdx	The index where the search starts. Optional and defaults to 0.
maxReplacements	The maximum number of replacements to perform. Optional and defaults to int.MaxValue .
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.

Returns: this to allow concatenated calls.

◆ SearchAndReplaceAll() [2/2]

AString SearchAndReplaceAll	(	String	searchStr,
		String	newStr,
		int	startIdx = `0`,
		int	maxReplacements = `int.MaxValue`,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Replace one or more occurrences of a string by another string.

Note: The difference to SearchAndReplace is that this method returns this to allow concatenated calls.

Parameters

searchStr	The String to be replaced.
newStr	The replacement string.
startIdx	The index where the search starts. Optional and defaults to 0.
maxReplacements	The maximum number of replacements to perform. Optional and defaults to int.MaxValue .
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.

Returns: this to allow concatenated calls.

◆ SetBuffer()

void SetBuffer ( int newCapacity )

inline

Resizes the internal buffer to meet exactly the given size.

The following rules apply:

The string represented by this instance is copied to the new buffer. If this is larger than the new buffer size, the string is cut at the end to fit.
If the desired new size is 0, then the currently allocated buffer will be released. In this case method Buffer will still return an empty constant character array (using an internal singleton) but method IsNull will return true.

Note: Any methods of this class that extend the length of the string represented, will invoke this method if the current buffer size is not sufficient. If a future string length of an AString is predictable, then it is advisable to allocate such size upfront to avoid recurring allocations.

Parameters

newCapacity The new capacity of the internal buffer.

◆ SetCharAt()

void SetCharAt	(	int	idx,
		char	c
	)

inline

Sets the character at the given index. A range check is performed. If this fails, nothing is done.

Parameters

idx	The index of the character to write.
c	The character to write.

◆ SetCharAt_NC()

void SetCharAt_NC	(	int	idx,
		char	c
	)

inline

Sets the character at the given index.

Attention: Non checking variant of original method. See Non-checking methods for _NC method variants.

Parameters

idx	The index of the character to write.
c	The character to write.

◆ SetLength()

int SetLength ( int newLength )

inline

Set the actual length of the stored string. The string can only be shortened with this method. To change the internal allocation size, see SetBuffer.

Parameters

newLength The new length of the AString. Must be smaller than the current length.

Returns: The new length of the string represented by this. ESCString.

◆ SetLength_NC()

void SetLength_NC ( int newLength )

inline

Set the actual length of the stored string. The string can only be shortened with this method.

Attention: Non checking variant of original method. See Non-checking methods for _NC method variants.

Parameters

newLength The new length of the AString. Must be between 0 and the current length.

◆ SetNull()

void SetNull ( )

inline

Invokes SetBuffer(0).

Returns: true if no buffer is allocated.

◆ StartsWith() [1/3]

bool StartsWith	(	AString	needle,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Checks if this AString starts with the given String.

Parameters

needle	The AString to search. If s is null or empty, false is returned.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.

Returns: true if this starts with the given AString, false if not.

◆ StartsWith() [2/3]

bool StartsWith	(	String	needle,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Checks if this AString starts with the given String.

Parameters

needle	The String to search. If s is null or empty, false is returned.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.

Returns: true if this starts with the given sequence, false if not.

◆ StartsWith() [3/3]

bool StartsWith	(	Substring	needle,
		Case	sensitivity = `Case.Sensitive`
	)

inline

Checks if this AString starts with the given Substring.

Parameters

needle	The Substring to search. If s is null or empty, false is returned.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case.Sensitive.

Returns: true if this starts with the given Substring, false if not.

◆ Tab()

AString Tab	(	int	tabSize,
		int	minPad = `1`,
		char	tabChar = `' '`
	)

inline

Go to the next tab stop by filling in pad characters repeatedly. The tab position is relative the start of the current line within the string (if no calls to NewLine where performed, yet, this is always the start of the string).

Note: While any append operation is allowed, manipulations like Delete or InsertAt will not correct the internal tab reference position to match the index of the then current start of the last line in this string.

Parameters

tabSize	The tab positions are multiples of this parameter.
minPad	(Optional) The minimum pad characters to add. Defaults to 1.
tabChar	(Optional) The character to insert to reach the tab position. Defaults to ' ' (space).

Returns: this to allow concatenated calls.

◆ ToLower()

AString ToLower	(	int	regionStart = `0`,
		int	regionLength = `int.MaxValue`
	)

inline

Converts all or a region of characters in the Buffer to lower case.

Parameters

regionStart	Start of the region to be converted. Defaults to 0
regionLength	Length of the region to be converted. Defaults to int.MaxValue.

Returns: this to allow concatenated calls.

◆ ToString() [1/4]

override String ToString ( )

inline

Creates a String containing a copy of the contents of this AString.

Returns: A String that represents this object.

◆ ToString() [2/4]

String ToString	(	int	regionStart,
		int	regionLength = `int.MaxValue`
	)

inline

Creates a String containing a copy of a region of the contents of this AString.

Parameters

regionStart	The start index of the region in this to create the string from.
regionLength	The maximum length of the region to create the string from. Defaults to int.MaxValue.

Returns: A String that represents the specified sub region of this object.

◆ ToString() [3/4]

StringBuilder ToString	(	StringBuilder	result,
		bool	appendMode = `false`
	)

inline

Copies the contents of this AString into the given StringBuilder.

Parameters

result	A result string to copy the contents of this AString into.
appendMode	Optional: If true, any contents in the result is preserved. Otherwise such content gets replaced (default).

Returns: The (modified) result that was provided (for concatenation of calls).

◆ ToString() [4/4]

StringBuilder ToString	(	StringBuilder	result,
		int	regionStart,
		int	regionLength = `int.MaxValue`,
		bool	appendMode = `false`
	)

inline

Copies a region of the contents of this AString into the given StringBuilder.

Parameters

result	A result string to copy the specified region into.
regionStart	The start index of the region to be copied.
regionLength	The maximum length of the region to be copied. Defaults to int.MaxValue.
appendMode	If true, any contents in the result is preserved. Otherwise such content gets replaced. Defaults to false.

Returns: The (modified) result that was provided (for concatenation of calls).

◆ ToUpper()

AString ToUpper	(	int	regionStart = `0`,
		int	regionLength = `int.MaxValue`
	)

inline

Converts all or a region of characters in the Buffer to upper case.

Parameters

regionStart	Start of the region to be converted. Defaults to 0
regionLength	Length of the region to be converted. Defaults to int.MaxValue.

Returns: this to allow concatenated calls.

◆ Trim()

AString Trim ( char[] trimChars = null )

inline

All characters defined in given set are removed at the beginning and at the end of this AString.

See method TrimAt to remove whitespaces anywhere in the string.

Parameters

trimChars The set of characters to be omitted. Defaults to null which causes this method to use CString.DefaultWhitespaces.

Returns: this to allow concatenated calls.

◆ TrimAt()

int TrimAt	(	int	idx,
		char[]	trimChars = `null`
	)

inline

All characters defined in given set at, left of and right of the given index are removed from the string.
The method returns index of the first character of those characters that were behind the trimmed region. With legal index given, this value can only be smaller or equal to index. If index is out of bounds, the length of the string is returned.

Parameters

idx	The index to perform the trim operation at. Has to be between zero and Length() -1.
trimChars	Pointer to a zero terminated set of characters to be omitted. Defaults to CString.DefaultWhitespaces.

Returns: The index of the first character of those characters that were behind the trimmed region.

◆ TrimEnd()

AString TrimEnd ( char[] trimChars = null )

inline

All characters defined in given set are removed at the end of this string.

See also: Method TrimAt to remove whitespaces at arbitrary places in the string.

Parameters

trimChars The set of characters to be omitted. Defaults to CString.DefaultWhitespaces.

Returns: this to allow concatenated calls.

◆ TrimStart()

AString TrimStart ( char[] trimChars = null )

inline

All characters defined in given set are removed at the beginning of this string.

See also: Method TrimAt to remove whitespaces at arbitrary places in the string.

Parameters

trimChars The set of characters to be omitted. Defaults to CString.DefaultWhitespaces.

Returns: this to allow concatenated calls.

Member Data Documentation

◆ buffer

char [] buffer =CString.NullBuffer

protected

The Buffer array. This may but should not be accessed directly. In case of external modifications the field hash has to be set to dirty (0).

◆ hash

int hash =0

protected

The hash value. Has to be set dirty (0) whenever String is changed from outside!.

◆ length

int length =0

protected

The actual length of the string stored in the Buffer. In case of external modifications the field hash has to be set to dirty (0).

Property Documentation

◆ this[int idx]

char? this[int idx]

getset

The C# indexer allows array type access. This is implemented here including a range check. If this fails, the get part will return '\0', the set part will do nothing.

Note: Access to the characters without index check is provided with method CharAt_NC.

Parameters

idx	The index of the character to read.

Returns: The character at the given index, or '\0' if index out of range.

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

AString.cs

Class Description

Public Static Methods

Public Methods

Protected Fields

Protected Methods

Character access

Constructor & Destructor Documentation

◆ AString() [1/6]

◆ AString() [2/6]

◆ AString() [3/6]

◆ AString() [4/6]

◆ AString() [5/6]

◆ AString() [6/6]

Member Function Documentation

◆ _() [1/22]

◆ _() [2/22]

◆ _() [3/22]

◆ _() [4/22]

◆ _() [5/22]

◆ _() [6/22]

◆ _() [7/22]

◆ _() [8/22]

◆ _() [9/22]

◆ _() [10/22]

◆ _() [11/22]

◆ _() [12/22]

◆ _() [13/22]

◆ _() [14/22]

◆ _() [15/22]

◆ _() [16/22]

◆ _() [17/22]

◆ _() [18/22]

◆ _() [19/22]

◆ _() [20/22]

◆ _() [21/22]

◆ _() [22/22]

◆ _Bin() [1/2]

◆ _Bin() [2/2]

◆ _Hex() [1/2]

◆ _Hex() [2/2]

◆ _NC() [1/7]

◆ _NC() [2/7]

◆ _NC() [3/7]

◆ _NC() [4/7]

◆ _NC() [5/7]

◆ _NC() [6/7]

◆ _NC() [7/7]

◆ _Oct() [1/2]

◆ _Oct() [2/2]

◆ Buffer()

◆ Capacity()

◆ CharAt()

◆ CharAt_NC()

◆ CharAtEnd()

◆ CharAtEnd_NC()

◆ CharAtStart()

◆ CharAtStart_NC()

◆ Clear()

◆ CompareTo() [1/4]

◆ CompareTo() [2/4]

◆ CompareTo() [3/4]

◆ CompareTo() [4/4]

◆ ContainsAt() [1/4]

◆ ContainsAt() [2/4]

◆ ContainsAt() [3/4]

◆ ContainsAt() [4/4]

◆ Delete()

◆ Delete_NC()

◆ DeleteEnd()

◆ DeleteEnd_NC()

◆ DeleteStart()

◆ DeleteStart_NC()

◆ EndsWith() [1/3]

◆ EndsWith() [2/3]

◆ EndsWith() [3/3]

◆ EnsureRemainingCapacity()

◆ Equals() [1/5]

◆ Equals() [2/5]

◆ Equals() [3/5]

◆ Equals() [4/5]