Description:

template<typename TChar>
requires alib::characters::IsCharacter<TChar>
class alib::strings::TString< TChar >

This class is the base class of all ALib string classes. Objects of this type represent character strings whose data is allocated outside their scope. In particular, the class does not allocate a character array buffer to store and manipulate string data.

Once constructed, objects of this class are immutable, except for the possibility to assign a complete new object value. This means there is no interface to change the single two data members buffer and length. The immutable nature of this type is lifted by derived types. While class Substring allows changing the start and length of the string represented, class AString holds a copy of the data and consequently allows modifying the string stored.

See also: For an introduction into the ALib string classes see this module's Programmer's Manual.

Template Parameters

TChar The character type of this string. Alias names for specializations along the different character types are provided in namespace alib with type definitions String, NString, WString, XString, ComplementString, and StrangeString.

Definition at line 83 of file string.inl.

Inheritance diagram for alib::strings::TString< TChar >:

[legend]

Inner Type Index:
class	TRandomAccessIterator

Public Type Index:
using	size_type = integer
	The type defining sizes of strings.

using	value_type = TChar
	Exposes template parameter TChar to the outer world in a `std` compatible way.

Public Method Index:
constexpr	TString () noexcept=default

template<typename T> requires alib::characters::IsImplicitArraySource<T, TChar>
constexpr	TString (const T &src) noexcept

template<typename T> requires alib::characters::IsExplicitArraySource<T, TChar>
constexpr	TString (const T &src) noexcept

constexpr	TString (const TChar *pBuffer, integer pLength) noexcept

constexpr	TString (const TString &) noexcept=default
	Defaulted copy constructor.

	TString (const_iterator &start, const_iterator &end)

constexpr	TString (lang::IsNullptr auto const &) noexcept
	Constructor accepting `nullptr`. Constructs a nulled string.

template<typename T> requires alib::characters::IsMutableArraySource<T, TChar>
constexpr	TString (T &src) noexcept

template<typename TAllocator> requires alib::lang::IsAllocator<TAllocator>
	TString (TAllocator &allocator, const TString< TChar > &copy)

constexpr	TString (TString &&) noexcept=default
	Defaulted move constructor.

template<typename T> requires ( alib::characters::IsImplicitArrayCast<T, TChar> && !alib::strings::NoAutoCastTraits< TString<TChar>, characters::Policy::Implicit, std::remove_cv_t<T> >::value )
constexpr	operator T () const

template<typename T> requires ( alib::characters::IsExplicitArrayCast<T, TChar> && !alib::strings::NoAutoCastTraits< TString<TChar>, characters::Policy::ExplicitOnly, std::remove_cv_t<T> >::value )
constexpr	operator T () const

constexpr TString &	operator= (const TString &) noexcept=default

constexpr TString &	operator= (TString &&) noexcept=default

Buffer Access, Length, and State
constexpr const TChar *	Buffer () const

constexpr integer	Length () const

integer	WStringLength () const

constexpr bool	IsNull () const

constexpr bool	IsNotNull () const

constexpr bool	IsEmpty () const

constexpr bool	IsNotEmpty () const

template<typename TCheck = CHK>
TString< TChar >	Substring (integer regionStart, integer regionLength=MAX_LEN) const

Character Access
template<typename TCheck = CHK>
TChar	CharAt (integer idx) const

template<typename TCheck = CHK>
TChar	CharAtStart () const

template<typename TCheck = CHK>
TChar	CharAtEnd () const

TChar	operator[] (integer idx) const

Hashing
std::size_t	Hashcode () const

std::size_t	HashcodeIgnoreCase () const

Comparison Methods
template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>
bool	Equals (const TString< TChar > &rhs) const

template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>
int	CompareTo (const TString< TChar > &rhs) const

template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>
int	CompareTo (const TString &rhs, integer rhsRegionStart, integer rhsRegionLength=MAX_LEN) const

template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>
int	CompareTo (const TString &rhs, integer rhsRegionStart, integer rhsRegionLength, integer regionStart, integer regionLength=MAX_LEN) const

template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>
bool	ContainsAt (const TString &needle, integer pos) const

template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>
bool	StartsWith (const TString &needle) const

template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>
bool	EndsWith (const TString &needle) const

Search
template<typename TCheck = CHK>
integer	IndexOf (TChar needle, integer startIdx=0) const

template<typename TCheck = CHK>
integer	IndexOf (TChar needle, integer regionStart, integer regionLength) const

integer	IndexOfOrLength (TChar needle) const

template<typename TCheck = CHK>
integer	IndexOfOrLength (TChar needle, integer startIdx) const

template<typename TCheck = CHK>
integer	LastIndexOf (TChar needle, integer startIndex=MAX_LEN) const

template<lang::Inclusion TInclusion, typename TCheck = CHK>
integer	IndexOfAny (const TString &needles, integer startIdx=0) const

template<lang::Inclusion TInclusion, typename TCheck = CHK>
integer	LastIndexOfAny (const TString &needles, integer startIdx=MAX_LEN) const

template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>
integer	IndexOf (const TString &needle, integer startIdx=0, integer endIdx=strings::MAX_LEN) const

template<typename TCheck = CHK>
integer	IndexOfFirstDifference (const TString &needle, lang::Case sensitivity=lang::Case::Sensitive, integer startIdx=0) const

integer	IndexOfSegmentEnd (TChar opener, TChar closer, integer idx) const

template<typename TCheck = CHK>
integer	CountChar (TChar needle, integer startPos=0) const

template<typename TCheck = CHK>
integer	CountChar (TChar needle, TChar omit, integer startPos) const

template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>
integer	Count (const TString &needle, integer startPos=0) const

template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>
integer	Count (const TString &needle, const TString &omit, integer startPos=0) const

Parsing Numbers
ALIB_DLL uint64_t	ParseDecDigits (integer startIdx=0, integer *newIdx=nullptr) const

ALIB_DLL int64_t	ParseInt (integer startIdx=0, TNumberFormat< TChar > numberFormat=nullptr, integer newIdx=nullptr) const

int64_t	ParseInt (TNumberFormat< TChar > numberFormat, integer newIdx=nullptr) const

int64_t	ParseInt (integer *newIdx) const

int64_t	ParseInt (integer startIdx, integer *newIdx) const

ALIB_DLL uint64_t	ParseDec (integer startIdx=0, TNumberFormat< TChar > numberFormat=nullptr, integer newIdx=nullptr) const

uint64_t	ParseDec (TNumberFormat< TChar > numberFormat, integer newIdx=nullptr) const

uint64_t	ParseDec (integer *newIdx) const

uint64_t	ParseDec (integer startIdx, integer *newIdx) const

ALIB_DLL uint64_t	ParseBin (integer startIdx=0, TNumberFormat< TChar > numberFormat=nullptr, integer newIdx=nullptr) const

uint64_t	ParseBin (TNumberFormat< TChar > numberFormat, integer newIdx=nullptr) const

uint64_t	ParseBin (integer *newIdx) const

uint64_t	ParseBin (integer startIdx, integer *newIdx) const

ALIB_DLL uint64_t	ParseHex (integer startIdx=0, TNumberFormat< TChar > numberFormat=nullptr, integer newIdx=nullptr) const

uint64_t	ParseHex (TNumberFormat< TChar > numberFormat, integer newIdx=nullptr) const

uint64_t	ParseHex (integer *newIdx) const

uint64_t	ParseHex (integer startIdx, integer *newIdx) const

ALIB_DLL uint64_t	ParseOct (integer startIdx=0, TNumberFormat< TChar > numberFormat=nullptr, integer newIdx=nullptr) const

uint64_t	ParseOct (TNumberFormat< TChar > numberFormat, integer newIdx=nullptr) const

uint64_t	ParseOct (integer *newIdx) const

uint64_t	ParseOct (integer startIdx, integer *newIdx) const

ALIB_DLL double	ParseFloat (integer startIdx=0, TNumberFormat< TChar > numberFormat=nullptr, integer newIdx=nullptr) const

double	ParseFloat (TNumberFormat< TChar > numberFormat, integer newIdx=nullptr) const

double	ParseFloat (integer *newIdx) const

double	ParseFloat (integer startIdx, integer *newIdx) const

Conversion
integer	CopyTo (TChar *dest) const

template<typename TAllocator> requires alib::lang::IsAllocator<TAllocator>
void	Allocate (TAllocator &allocator, const TString< TChar > &copy)

template<typename TAllocator> requires alib::lang::IsAllocator<TAllocator>
void	Free (TAllocator &allocator)

std::iterator_traits
const_iterator	begin () const

const_iterator	cbegin () const

const_iterator	end () const

const_iterator	cend () const

const_reverse_iterator	rbegin () const

const_reverse_iterator	rend () const

const_reverse_iterator	crbegin () const

const_reverse_iterator	crend () const

size_type	size () const

Protected Field Index:
const TChar *	buffer

integer	length

Protected Method Index:
template<lang::Case TSensitivity = lang::Case::Sensitive>
ALIB_DLL integer	indexOfString (const TString &needle, integer startIdx, integer endIdx) const

Type Definition Details:

◆ const_iterator

template<typename TChar>

using alib::strings::TString< TChar >::const_iterator = TRandomAccessIterator<const TChar>

The constant iterator exposed by this character container. A Mutable version is found only in descendant classes (e.g., AString).

Definition at line 2145 of file string.inl.

◆ const_reverse_iterator

template<typename TChar>

using alib::strings::TString< TChar >::const_reverse_iterator = std::reverse_iterator<const_iterator>

The constant reverse iterator exposed by this character container. A Mutable version is found only in descendant classes (e.g., AString).

Definition at line 2149 of file string.inl.

◆ size_type

template<typename TChar>

using alib::strings::TString< TChar >::size_type = integer

The type defining sizes of strings.

Definition at line 90 of file string.inl.

◆ value_type

template<typename TChar>

using alib::strings::TString< TChar >::value_type = TChar

Exposes template parameter TChar to the outer world in a std compatible way.

Definition at line 87 of file string.inl.

Field Details:

◆ buffer

template<typename TChar>

const TChar* alib::strings::TString< TChar >::buffer

protected

Pointer to an array of constant character values. This array holds the string that an instance of this type is representing.
Read access to this field is granted with the method Buffer.

For technical reasons, this documentation unfortunately omits the important fact that this field is part of an anonymous union declared like this:

 union
 {
     const TChar*   buffer;
           TChar*  vbuffer;
 };

Hence, the field can also be interpreted as a pointer to an array of non-constant character values. Derived classes might use the sibling version vbuffer to modify the contents of the string if it is assured that such memory is writable. This is, for example, done extensively by the implementation of class AString.

Note: It might not be considered pure/nice OO-design to prepare a feature of specialized classes in a non-abstract base class, as done here. But the alternative would have been to force derived classes to perform re-interpret casts or even worse tricks to rightfully access a writeable buffer.

Definition at line 133 of file string.inl.

◆ length

template<typename TChar>

integer alib::strings::TString< TChar >::length

protected

The length of the character string represented. Read access to this field is granted with the method Length.

Definition at line 138 of file string.inl.

Constructor(s) / Destructor Details:

◆ TString() [1/8]

template<typename TChar>

alib::strings::TString< TChar >::TString ( )

constexprdefaultnoexcept

Defaulted default constructor. Leaves this instance uninitialized and undefined. In other words, the methods Buffer and Length give random results.

◆ TString() [2/8]

template<typename TChar>

alib::strings::TString< TChar >::TString	(	const TChar *	pBuffer,
		integer	pLength )

inlineconstexprnoexcept

Constructor accepting a pointer to a character array and a string length.

Parameters

pBuffer	Pointer to the start of the character string to represent.
pLength	The length of the character string to represent.

Definition at line 168 of file string.inl.

◆ TString() [3/8]

template<typename TChar>

alib::strings::TString< TChar >::TString ( lang::IsNullptr auto const & )

inlineconstexprnoexcept

Constructor accepting nullptr. Constructs a nulled string.

Definition at line 174 of file string.inl.

◆ TString() [4/8]

template<typename TChar>

template<typename T>
requires alib::characters::IsImplicitArraySource<T, TChar>

alib::strings::TString< TChar >::TString ( const T & src )

inlineconstexprnoexcept

Templated implicit constructor accepting a const reference to an object of a type that satisfies the concept IsImplicitArraySource.

Custom types can be enabled for this constructor by specializing the traits-type ArrayTraits, which is used for both; the implementation of the concept, and the implementation of this constructor itself.

Template Parameters

T	The type of the given src. Requires satisfying the concept IsImplicitArraySource. Deduced by the compiler.

Parameters

src	The source of the string data to copy.

Definition at line 191 of file string.inl.

◆ TString() [5/8]

template<typename TChar>

template<typename T>
requires alib::characters::IsExplicitArraySource<T, TChar>

alib::strings::TString< TChar >::TString ( const T & src )

inlineexplicitconstexprnoexcept

Templated explicit constructor accepting a const reference to an object of a type that satisfies the concept IsExplicitArraySource.

Custom types can be enabled for this constructor by specializing the traits-type ArrayTraits, which is used for both; the implementation of the concept, and the implementation of this constructor itself.

Template Parameters

T	The type of the given src. Requires satisfying the concept IsExplicitArraySource. Deduced by the compiler.

Parameters

src	The source of the string data to copy.

Definition at line 209 of file string.inl.

◆ TString() [6/8]

template<typename TChar>

template<typename T>
requires alib::characters::IsMutableArraySource<T, TChar>

alib::strings::TString< TChar >::TString ( T & src )

inlineexplicitconstexprnoexcept

Templated explicit constructor accepting a mutable reference to an object of a type that satisfies the concept IsMutableArraySource.

Custom types can be enabled for this constructor by specializing the traits-type ArrayTraits, which is used for both; the implementation of the concept, and the implementation of this constructor itself.

Template Parameters

T	The type of the given src. Requires satisfying the concept IsMutableArraySource. Deduced by the compiler.

Parameters

src	The source of the string data to copy.

Definition at line 227 of file string.inl.

◆ TString() [7/8]

template<typename TChar>

template<typename TAllocator>
requires alib::lang::IsAllocator<TAllocator>

alib::strings::TString< TChar >::TString	(	TAllocator &	allocator,
		const TString< TChar > &	copy )

inline

Constructor which allocates memory, copies the given string's contents, and lets this string represent this new character array.
Note that it is up to the using code to duly deallocate the memory, because the destructor of this type does not do so.

See also: Methods Allocate and Free for information how to use allocated string objects.

Template Parameters

TAllocator The type of the given allocator, as prototyped with Allocator. Requires satisfying the concept IsAllocator. Deduced by the compiler.

Parameters

allocator	The allocator to use.
copy	The string to copy to the new memory allocated.

Definition at line 245 of file string.inl.

◆ TString() [8/8]

template<typename TChar>

alib::strings::TString< TChar >::TString	(	const_iterator &	start,
		const_iterator &	end )

inline

Constructs this string using start and end iterators.

Parameters

start	An iterator referencing the start of the string.
end	An iterator referencing the end of the string.

Definition at line 2200 of file string.inl.

Method Details:

◆ AdjustRegion()

template<typename TChar>

bool alib::strings::TString< TChar >::AdjustRegion	(	integer &	regionStart,
		integer &	regionLength ) const

inline

Adjusts a region given as in/out parameters, to fit to this object's range [0..length].

Parameters

[in,out]	regionStart	The proposed region start which might get adjusted to fit to range [0..length].
[in,out]	regionLength	The proposed region length which might get adjusted to fit to range [0..length].

Returns: Returns true, if the adjusted region is empty.

Definition at line 1919 of file string.inl.

◆ Allocate()

template<typename TChar>

template<typename TAllocator>
requires alib::lang::IsAllocator<TAllocator>

void alib::strings::TString< TChar >::Allocate	(	TAllocator &	allocator,
		const TString< TChar > &	copy )

inline

Sets this String to a copy of the given string, allocated in given allocator.

Note: In case the given copy is empty or nulled, no allocation is performed and this string is set to empty. Still, the pointer to the buffer is copied. Thus, this string behaves in respect to the method IsNull the same as the given string copy.

Template Parameters

TAllocator The type of the given allocator, as prototyped with Allocator. Deduced by the compiler.

Parameters

allocator	The allocator to use.
copy	The string to copy to the new memory allocated.

Definition at line 1870 of file string.inl.

◆ begin()

template<typename TChar>

const_iterator alib::strings::TString< TChar >::begin ( ) const

inline

Returns an iterator pointing to a constant character at the start of this string.

Returns: The start of this string.

Definition at line 2158 of file string.inl.

◆ Buffer()

template<typename TChar>

const TChar * alib::strings::TString< TChar >::Buffer ( ) const

inlineconstexpr

Returns a pointer to the first character of the string we are representing.

Note: The string is not guaranteed to be zero-terminated.

Returns: The start of the character array comprising the string represented by this object.

Definition at line 313 of file string.inl.

◆ cbegin()

template<typename TChar>

const_iterator alib::strings::TString< TChar >::cbegin ( ) const

inline

Returns an iterator pointing to a constant character at the start of this string.

Returns: The start of this string.

Definition at line 2162 of file string.inl.

◆ cend()

template<typename TChar>

const_iterator alib::strings::TString< TChar >::cend ( ) const

inline

Returns an iterator pointing behind this string.

Returns: The end of this string.

Definition at line 2170 of file string.inl.

◆ CharAt()

template<typename TChar>

template<typename TCheck = CHK>

TChar alib::strings::TString< TChar >::CharAt ( integer idx ) const

inline

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

Template Parameters

TCheck Defaults to CHK, which is the normal invocation mode. If false is given, no range check is performed.

Parameters

idx	The index of the character to read.

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

Definition at line 421 of file string.inl.

◆ CharAtEnd()

template<typename TChar>

template<typename TCheck = CHK>

TChar alib::strings::TString< TChar >::CharAtEnd ( ) const

inline

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

Template Parameters

TCheck Defaults to CHK, which is the normal invocation mode. If false is given, no check for an empty or nulled object is performed.

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

Definition at line 460 of file string.inl.

◆ CharAtStart()

template<typename TChar>

template<typename TCheck = CHK>

TChar alib::strings::TString< TChar >::CharAtStart ( ) const

inline

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

Template Parameters

TCheck Defaults to CHK, which is the normal invocation mode. If false is given, no check for an empty string object is performed.

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

Definition at line 440 of file string.inl.

◆ CompareTo() [1/3]

template<typename TChar>

template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>

int alib::strings::TString< TChar >::CompareTo	(	const TString< TChar > &	rhs,
		integer	rhsRegionStart,
		integer	rhsRegionLength,
		integer	regionStart,
		integer	regionLength = MAX_LEN ) const

inline

Compares a region of this object with a region of another string-like object.

Template Parameters

TCheck Defaults to CHK, which is the normal invocation mode. If false is given, no check for a nulled comparison object is performed and this string must not be empty. Furthermore, no check is performed whether the given regions fit to this object respectively the other region to the object given with parameter rhs. This also means that the default value of regionLength must not be used in this case.

TSensitivity Determines if comparison is case-sensitive (the default) or not.

Parameters

rhs	The string to compare this string with.
rhsRegionStart	The start of the region in rhs to compare this object with.
rhsRegionLength	The length of the region in rhs to compare this object with.
regionStart	The start of the region in this object to compare with
regionLength	The length of the region in this object to compare with. Defaults to MAX_LEN.

Returns

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

Definition at line 690 of file string.inl.

◆ CompareTo() [2/3]

template<typename TChar>

template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>

int alib::strings::TString< TChar >::CompareTo	(	const TString< TChar > &	rhs,
		integer	rhsRegionStart,
		integer	rhsRegionLength = MAX_LEN ) const

inline

Compares this string with a region of another string-like object.

Template Parameters

TCheck	Defaults to CHK, which is the normal invocation mode. If `false` is given, no check for a nulled comparison object is performed and this string must not be empty. Furthermore, no check is performed whether the given region fits to parameter rhs. This also means that the default value must not be used with TCheck==NC.
TSensitivity	Determines if comparison is case-sensitive (the default) or not.

Parameters

rhs	The string to compare this string with.
rhsRegionStart	The start of the region in rhs to compare this object with.
rhsRegionLength	The length of the region in rhs to compare this object with. Defaults to MAX_LEN.

Returns

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

Definition at line 644 of file string.inl.

◆ CompareTo() [3/3]

template<typename TChar>

template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>

int alib::strings::TString< TChar >::CompareTo ( const TString< TChar > & rhs ) const

inline

Compares this string with a string-like object.

Template Parameters

TCheck	Defaults to CHK, which is the normal invocation mode. If `false` is given, no check for a nulled object (this) is performed and this string must not be of zero length (while rhs might be of zero length).
TSensitivity	Determines if comparison is case-sensitive (the default) or not.

Parameters

rhs	The object to compare.

Returns

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

Definition at line 596 of file string.inl.

◆ ContainsAt()

template<typename TChar>

template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>

bool alib::strings::TString< TChar >::ContainsAt	(	const TString< TChar > &	needle,
		integer	pos ) const

inline

Returns true, if the contents of the given string-like object is found at the given position.

Note

The following rules apply:

If pos is out of range or needle is nulled, false is returned. (This check only done if TCheck equals CHK.)
Otherwise, if the length of needle is 0, true is returned.

Template Parameters

TCheck	Defaults to CHK, which is the normal invocation mode. If `<false>` is given, no check on parameter pos is performed and needle must not be nulled.
TSensitivity	Determines if comparison is case-sensitive (the default) or not.

Parameters

needle	The string to compare with. If it is empty, `true` is returned.
pos	The position to search for needle.

Returns: true if needle is found at the given position. False otherwise.

Definition at line 732 of file string.inl.

◆ CopyTo()

template<typename TChar>

integer alib::strings::TString< TChar >::CopyTo ( TChar * dest ) const

inline

Copies this string's contents into a given character buffer. It is the caller's responsibility that dest is large enough, write-enabled, etc.

Parameters

dest	The destination buffer.

Returns: The length of this string.

Definition at line 1850 of file string.inl.

◆ Count() [1/2]

template<typename TChar>

template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>

integer alib::strings::TString< TChar >::Count	(	const TString< TChar > &	needle,
		const TString< TChar > &	omit,
		integer	startPos = 0 ) const

inline

Counts all occurrences of needle, unless followed by omit, starting at startPos to the end of the string.

For empty strings needle, 0 is returned. Also, for empty strings omit, 0 is returned.

Template Parameters

TSensitivity	Case sensitivity of the comparison. Optional and defaults to Case::Sensitive.
TCheck	Defaults to CHK, which is the normal invocation mode. If `false` is given, parameter startPos must be valid and needle must not be empty.

Parameters

needle	The string to search for.
omit	Omit occurrence if the given string follows.
startPos	The index to start the counting. Optional and defaults to `0`.

Returns: The index of the first difference in needle.

Definition at line 1340 of file string.inl.

◆ Count() [2/2]

template<typename TChar>

template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>

integer alib::strings::TString< TChar >::Count	(	const TString< TChar > &	needle,
		integer	startPos = 0 ) const

inline

Counts all occurrences of needle from startPos to the end of the string.

For empty strings needle, 0 is returned.

Template Parameters

TCheck	Defaults to CHK, which is the normal invocation mode. If `false` is given, parameter startIdx must be valid and needle must not be empty.
TSensitivity	Case sensitivity of the comparison. Optional and defaults to Case::Sensitive.

Parameters

needle	The string to search for.
startPos	The index to start the counting. Optional and defaults to `0`.

Returns: The index of the first difference in needle.

Definition at line 1293 of file string.inl.

◆ CountChar() [1/2]

template<typename TChar>

template<typename TCheck = CHK>

integer alib::strings::TString< TChar >::CountChar	(	TChar	needle,
		integer	startPos = 0 ) const

inline

Counts all occurrences of character needle in the range from startPos to the end of the string.

For empty strings needle, 0 is returned.

Template Parameters

TCheck Defaults to CHK, which is the normal invocation mode. If false is given, no range check is performed.

Parameters

needle	The character to search for.
startPos	The index to start the counting. Optional and defaults to `0`.

Returns: The index of the first difference in needle.

Definition at line 1206 of file string.inl.

◆ CountChar() [2/2]

template<typename TChar>

template<typename TCheck = CHK>

integer alib::strings::TString< TChar >::CountChar	(	TChar	needle,
		TChar	omit,
		integer	startPos ) const

inline

Counts all occurrences of character needle, unless followed by character omit in the range from startPos to the end of the string.

For empty strings needle, 0 is returned. Also, for empty strings omit, 0 is returned.

Template Parameters

TCheck Defaults to CHK, which is the normal invocation mode. If false is given, no range check is performed.

Parameters

needle	The character to search for.
omit	Omit occurrence if the given character follows.
startPos	The index to start the counting.

Returns: The index of the first difference in needle.

Definition at line 1247 of file string.inl.

◆ crbegin()

template<typename TChar>

const_reverse_iterator alib::strings::TString< TChar >::crbegin ( ) const

inline

Returns a reverse iterator pointing to a constant character at the end of this string.

Returns: The last character of this string.

Definition at line 2182 of file string.inl.

◆ crend()

template<typename TChar>

const_reverse_iterator alib::strings::TString< TChar >::crend ( ) const

inline

Returns a reverse iterator pointing before the start of this string.

Returns: The character before this string.

Definition at line 2186 of file string.inl.

◆ end()

template<typename TChar>

const_iterator alib::strings::TString< TChar >::end ( ) const

inline

Returns an iterator pointing behind this string.

Returns: The end of this string.

Definition at line 2166 of file string.inl.

◆ EndsWith()

template<typename TChar>

template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>

bool alib::strings::TString< TChar >::EndsWith ( const TString< TChar > & needle ) const

inline

Returns true, if this string ends with the string found in parameter needle. If needle is empty, true is returned.

Template Parameters

TSensitivity Determines if comparison is case-sensitive (the default) or not.

Parameters

needle The string to compare the end of this string with. If nulled or empty, true is returned.

Returns: true if needle is found at the end of this, false otherwise.

Definition at line 805 of file string.inl.

◆ Equals()

template<typename TChar>

template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>

bool alib::strings::TString< TChar >::Equals ( const TString< TChar > & rhs ) const

inline

Compares this string with a string-like object.

true is returned if this and the compared string are nulled or empty. If only one is nulled or empty, false is returned.

Template Parameters

TCheck	Defaults to CHK, which is the normal invocation mode. If `false` is given, no check for a nulled is performed on this string as well as on rhs.
TSensitivity	Determines if comparison is case-sensitive (the default) or not.

Parameters

rhs	The object to compare.

Returns: true, if the contents of this string and the string representation of the given rhs are equal.

Definition at line 541 of file string.inl.

◆ Free()

template<typename TChar>

template<typename TAllocator>
requires alib::lang::IsAllocator<TAllocator>

void alib::strings::TString< TChar >::Free ( TAllocator & allocator )

inline

Deallocates this String's memory in allocator and sets this instance to nulled.

Note

In case this instance is empty or nulled, no deallocation is performed. This should not happen with due usage, which is:

A string is allocated using the method Allocate on another instance.
For the allocated string, this method is to be called, passing the same allocator.

Nevertheless, because the method Allocate likewise does not perform an allocation call in the case an empty string was given, it is valid use to allocate and later deallocate empty strings.

Template Parameters

TAllocator The type of the given allocator, as prototyped with Allocator. Deduced by the compiler.

Parameters

allocator The allocator to use.

Definition at line 1899 of file string.inl.

◆ Hashcode()

template<typename TChar>

std::size_t alib::strings::TString< TChar >::Hashcode ( ) const

Computes a hash number for the contained string.

Note: If this library is compiled using C++17, internally this method is using std::hash<std::string_view<TChar>>. Otherwise a compatible hash function is used.

See also: Alternative method HashcodeIgnoreCase.

Returns: A hash number which is equal for two instances with the same content.

◆ HashcodeIgnoreCase()

template<typename TChar>

std::size_t alib::strings::TString< TChar >::HashcodeIgnoreCase ( ) const

Computes a hash number for the contained string converted to upper case letters.

See also: Alternative method Hashcode.

Returns: A hash number which is equal for two instances with have the same content if converted to upper case letters.

◆ IndexOf() [1/3]

template<typename TChar>

template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>

integer alib::strings::TString< TChar >::IndexOf	(	const TString< TChar > &	needle,
		integer	startIdx = 0,
		integer	endIdx = strings::MAX_LEN ) const

inline

Searches the given string-like object in this string.

If needle is empty, the adjusted value of startIdx is returned.

Template Parameters

TSensitivity	Case sensitivity of the comparison. Optional and defaults to Case::Sensitive.
TCheck	Defaults to CHK, which is the normal invocation mode. If `false` is given, parameter needle must not be empty and startIdx must be in the range of [0 ... Length() - needle.Length()]. This also implies that this string must not be empty.

Parameters

needle	The string to search for.
startIdx	The index to start the search at. Optional and defaults to `0`.
endIdx	The index where the search ends. Precisely, the index of the first character that is not found. Defaults to MAX_LEN.

Returns: If the checking of parameters failed or the string is not found, -1 is returned. Otherwise the index of the first occurrence of needle.

Definition at line 1104 of file string.inl.

◆ IndexOf() [2/3]

template<typename TChar>

template<typename TCheck = CHK>

integer alib::strings::TString< TChar >::IndexOf	(	TChar	needle,
		integer	regionStart,
		integer	regionLength ) const

inline

Searches a character within a region of this.

Template Parameters

TCheck Defaults to CHK, which is the normal invocation mode. If false is given, no range check is performed.

Parameters

needle	The character to search for.
regionStart	The start of the region to search the character in.
regionLength	The length of the region to search the character in.

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

Definition at line 876 of file string.inl.

◆ IndexOf() [3/3]

template<typename TChar>

template<typename TCheck = CHK>

integer alib::strings::TString< TChar >::IndexOf	(	TChar	needle,
		integer	startIdx = 0 ) const

inline

Searches a character starting from a given position.

Template Parameters

TCheck Defaults to CHK, which is the normal invocation mode. If false is given, no range check is performed.

Parameters

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

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

Definition at line 844 of file string.inl.

◆ IndexOfAny()

template<typename TChar>

template<lang::Inclusion TInclusion, typename TCheck = CHK>

integer alib::strings::TString< TChar >::IndexOfAny	(	const TString< TChar > &	needles,
		integer	startIdx = 0 ) const

inline

Returns the index of the first character which is included, respectively not included in a set of characters given as a string-like object.

Note: In derived class CString, a faster version of this method (using std::strpbrk() respectively std::strspn()) is available. So, if performance is important and repetitive calls are performed, it might be advisable to hold this string and the needles in a zero-terminated string buffer, for example in an AString.

This method searches forwards. For backwards search, see LastIndexOf.

Template Parameters

TInclusion	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.
TCheck	Defaults to CHK, which is the normal invocation mode. If `<false>` is given, no parameter checks are performed.

Parameters

needles	Pointer to a zero-terminated set of characters to be taken into account.
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.

Definition at line 1019 of file string.inl.

◆ IndexOfFirstDifference()

template<typename TChar>

template<typename TCheck = CHK>

integer alib::strings::TString< TChar >::IndexOfFirstDifference	(	const TString< TChar > &	needle,
		lang::Case	sensitivity = lang::Case::Sensitive,
		integer	startIdx = 0 ) const

inline

Searches the first difference of a substring of this string and a string-like object given with parameter needle. If no difference is found, then the index of the first character behind the substring is returned.

Template Parameters

TCheck Defaults to CHK, which is the normal invocation mode. If false is given, no range check is performed.

Parameters

needle	The substring to search for.
sensitivity	Letter case sensitivity of the comparison. Optional and defaults to Case::Sensitive.
startIdx	The index in this string to start the comparison with needle. Optional and defaults to `0`.

Returns: The index of the first difference found or idx plus the length of needle.

Definition at line 1149 of file string.inl.

◆ IndexOfOrLength() [1/2]

template<typename TChar>

integer alib::strings::TString< TChar >::IndexOfOrLength ( TChar needle ) const

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 string's Length if character needle is not found. Otherwise the index of first occurrence.

Definition at line 912 of file string.inl.

◆ IndexOfOrLength() [2/2]

template<typename TChar>

template<typename TCheck = CHK>

integer alib::strings::TString< TChar >::IndexOfOrLength	(	TChar	needle,
		integer	startIdx ) const

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.

Template Parameters

TCheck Defaults to CHK, which is the normal invocation mode. If false is given, no range check is performed.

Parameters

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

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

Definition at line 933 of file string.inl.

◆ IndexOfSegmentEnd()

template<typename TChar>

integer alib::strings::TString< TChar >::IndexOfSegmentEnd	(	TChar	opener,
		TChar	closer,
		integer	idx ) const

The method searches the next matching closer-character while taking nested pairs of opener and closer characters into account.

Before the invocation of this method, the initial opener has to be known already and the given idx has to point to the first character behind the opener, where the search for an according closer is to be started.

This method is useful to scan a string for pairs of opening and closing brackets, while the found segment may contain nested pairs of the same brackets.

Parameters

opener	The character that represents the opening bracket, e.g., `'{'`.
closer	The character that represents the closing bracket, e.g., `'}'`.
idx	Index pointing to first character behind the (first) opener.

Returns: The index of the corresponding closing character. If none was found, a negative value is returned. In the latter case the negated (absolute) value is indicating the number of still open (nested) brackets.

◆ indexOfString()

template<typename TChar>

template<lang::Case TSensitivity = lang::Case::Sensitive>

ALIB_DLL integer alib::strings::TString< TChar >::indexOfString	(	const TString< TChar > &	needle,
		integer	startIdx,
		integer	endIdx ) const

protected

Implementation of the substring search function.

Attention: This protected method expects valid (in range) parameters! Parameter endIdx must be smaller or equal to the length of this string minus the length of needle plus 1.

Template Parameters

TSensitivity The letter case sensitivity of the search.

Parameters

needle	The substring to search.
startIdx	The start index of the search.
endIdx	The index where the search ends. Precisely, the index of the first character that is not found.

Returns: The index of the first occurrence of needle, respectively -1 if not found.

◆ IsEmpty()

template<typename TChar>

bool alib::strings::TString< TChar >::IsEmpty ( ) const

inlineconstexpr

Returns true if this string is of zero length. Note that a nulled string is also considered empty.

See also: Details on the concept of nulled and empty strings are documented in chapter 6.1.1 Nulled Vs. Empty Strings of this module's Programmer's Manual.

Returns: true if the actual length equals zero.

Definition at line 367 of file string.inl.

◆ IsNotEmpty()

template<typename TChar>

bool alib::strings::TString< TChar >::IsNotEmpty ( ) const

inlineconstexpr

Returns true if this string has a length of 1 or more.

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

Definition at line 371 of file string.inl.

◆ IsNotNull()

template<typename TChar>

bool alib::strings::TString< TChar >::IsNotNull ( ) const

inlineconstexpr

Returns true if field buffer does not equal nullptr, false otherwise.

Returns: The negated value of method IsNull.

Definition at line 357 of file string.inl.

◆ IsNull()

template<typename TChar>

bool alib::strings::TString< TChar >::IsNull ( ) const

inlineconstexpr

Returns true if field buffer equals nullptr, false otherwise. Note that a nulled string is also considered empty.

See also: Details on the concept of nulled and empty strings are documented in chapter 6.1.1 Nulled Vs. Empty Strings of this module's Programmer's Manual.

Returns: true if no buffer is allocated.

Definition at line 352 of file string.inl.

◆ LastIndexOf()

template<typename TChar>

template<typename TCheck = CHK>

integer alib::strings::TString< TChar >::LastIndexOf	(	TChar	needle,
		integer	startIndex = MAX_LEN ) const

inline

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

Template Parameters

TCheck Defaults to CHK, which is the normal invocation mode. If false is given, no range check is performed. Consequently, in this case, optional parameter startIndex must be provided.

Parameters

needle	The character to search for.
startIndex	The index within this string to start searching the character. Defaults to MAX_LEN.

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

Definition at line 967 of file string.inl.

◆ LastIndexOfAny()

template<typename TChar>

template<lang::Inclusion TInclusion, typename TCheck = CHK>

integer alib::strings::TString< TChar >::LastIndexOfAny	(	const TString< TChar > &	needles,
		integer	startIdx = MAX_LEN ) const

inline

Returns the index of the last character which is included, respectively not included in set of characters given as a string-like object.

This method searches backwards starting at the given index. For forwards search, see IndexOfAny.

Template Parameters

TInclusion	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.
TCheck	Defaults to CHK, which is the normal invocation mode. If `<false>` is given, no parameter checks are performed.

Parameters

needles	Pointer to a zero-terminated set of characters to be searched for.
startIdx	The index to start the search at. The value is cropped to be in the bounds of 0 and the length of this object minus one. Defaults to MAX_LEN.

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.

Definition at line 1063 of file string.inl.

◆ Length()

template<typename TChar>

integer alib::strings::TString< TChar >::Length ( ) const

inlineconstexpr

Returns the length of the string that this object represents.

Returns: The length of the string represented by this object.

Definition at line 318 of file string.inl.

◆ operator T() [1/2]

template<typename TChar>

template<typename T>
requires ( alib::characters::IsImplicitArrayCast<T, TChar> && !alib::strings::NoAutoCastTraits< TString<TChar>, characters::Policy::Implicit, std::remove_cv_t<T> >::value )

alib::strings::TString< TChar >::operator T ( ) const

inlineconstexpr

Templated implicit cast operator constructing an instance of type T from this string instance. This operator requires the type T satisfying the concept IsImplicitArrayCast.

Custom types can be enabled for this operator by specializing the traits-type ArrayTraits, which is used for both; the implementation of the concept, and the implementation of this operator itself.

Template Parameters

T	The type to implicitly cast this instance to. Requires satisfying the concept IsImplicitArrayCast. Deduced by the compiler.

Returns: A value of type T.

Definition at line 279 of file string.inl.

◆ operator T() [2/2]

template<typename TChar>

template<typename T>
requires ( alib::characters::IsExplicitArrayCast<T, TChar> && !alib::strings::NoAutoCastTraits< TString<TChar>, characters::Policy::ExplicitOnly, std::remove_cv_t<T> >::value )

alib::strings::TString< TChar >::operator T ( ) const

inlineexplicitconstexpr

Templated explicit cast operator constructing an instance of type T from this string instance. This operator requires the type T satisfying the concept IsExplicitArrayCast.

Custom types can be enabled for this operator by specializing the traits-type ArrayTraits, which is used for both; the implementation of the concept, and the implementation of this operator itself.

Template Parameters

T	The type to explicitly cast this instance to. Deduced by the compiler.

Returns: A value of type T.

Definition at line 300 of file string.inl.

◆ operator=() [1/2]

template<typename TChar>

TString & alib::strings::TString< TChar >::operator= ( const TString< TChar > & )

constexprdefaultnoexcept

Defaulted copy assignment operator.

Returns: A reference to this instance.

◆ operator=() [2/2]

template<typename TChar>

TString & alib::strings::TString< TChar >::operator= ( TString< TChar > && )

constexprdefaultnoexcept

Defaulted move assignment operator.

Returns: A reference to this instance.

◆ operator[]()

template<typename TChar>

TChar alib::strings::TString< TChar >::operator[] ( integer idx ) const

inline

Reads a character at a given index.

Note: Unlike method CharAt, this operator does not perform do range check on parameter idx. The rationale for this is that derived mutable types (e.g., class AString), may provide a mutable (non-const) version of this operator, returning a a reference to the character to provide write access. Such reference to a character could not be given if the index was out of range. This way, a check in the derived type could likewise not be implemented.; As a result, this operator is equivalent to the non-checking version of method CharAt<false>. For safe access to characters in the buffer use CharAt (with template parameter TCheck being CHK) which returns '\0' in the case of that idx is out of bounds.; Still, in debug-compilations this operator raises an ALib error if idx is out of bounds.

Parameters

idx	The index of the character within this object's buffer.

Returns: If the character contained at index idx.

Definition at line 493 of file string.inl.

◆ ParseBin() [1/4]

template<typename TChar>

uint64_t alib::strings::TString< TChar >::ParseBin ( integer * newIdx ) const

inline

Overloaded version of alib::strings::TString::ParseBin(integer,TNumberFormat<TChar>,integer)const "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 output parameter newIdx is set to point to the first character behind the parsed number.

Definition at line 1598 of file string.inl.

◆ ParseBin() [2/4]

template<typename TChar>

uint64_t alib::strings::TString< TChar >::ParseBin	(	integer	startIdx,
		integer *	newIdx ) const

inline

Overloaded version of alib::strings::TString::ParseBin(integer,TNumberFormat<TChar>,integer)const "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.

Definition at line 1615 of file string.inl.

◆ ParseBin() [3/4]

template<typename TChar>

ALIB_DLL uint64_t alib::strings::TString< TChar >::ParseBin	(	integer	startIdx = 0,
		TNumberFormat< TChar > *	numberFormat = nullptr,
		integer *	newIdx = nullptr ) const

Reads an unsigned 64-bit integer in binary format at the given position from this string.

Parameter numberFormat defaults to nullptr. 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 number-parsing interface methods have a corresponding implementation within this class.

Parameters

	startIdx	The start index for parsing. Optional and defaults to `0`.
	numberFormat	The format definition. Defaults to `nullptr`.
[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() [4/4]

template<typename TChar>

uint64_t alib::strings::TString< TChar >::ParseBin	(	TNumberFormat< TChar > *	numberFormat,
		integer *	newIdx = nullptr ) const

inline

Overloaded version of alib::strings::TString::ParseBin(integer,TNumberFormat<TChar>,integer)const "ParseBin" providing default values for omitted parameters.

Parameters

	numberFormat	The format definition. Defaults to `nullptr`.
[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 output parameter newIdx is set to point to the first character behind the parsed number.

Definition at line 1584 of file string.inl.

◆ ParseDec() [1/4]

template<typename TChar>

uint64_t alib::strings::TString< TChar >::ParseDec ( integer * newIdx ) const

inline

Overloaded version of alib::strings::TString::ParseDec(integer,TNumberFormat<TChar>,integer)const "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 output parameter newIdx is set to point to the first character behind the parsed number.

Definition at line 1524 of file string.inl.

◆ ParseDec() [2/4]

template<typename TChar>

uint64_t alib::strings::TString< TChar >::ParseDec	(	integer	startIdx,
		integer *	newIdx ) const

inline

Overloaded version of alib::strings::TString::ParseDec(integer,TNumberFormat<TChar>,integer)const "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.

Definition at line 1541 of file string.inl.

◆ ParseDec() [3/4]

template<typename TChar>

ALIB_DLL uint64_t alib::strings::TString< TChar >::ParseDec	(	integer	startIdx = 0,
		TNumberFormat< TChar > *	numberFormat = nullptr,
		integer *	newIdx = nullptr ) const

Reads an unsigned 64-bit integer in standard decimal format at the given position from this AString.

Parameter numberFormat defaults to nullptr. This denotes static singleton TNumberFormat::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 integral values, see methods ParseInt, for floating point numbers ParseFloat.

For more information on number conversion, see class NumberFormat. All number-parsing interface methods have a corresponding implementation within this class.

Parameters

	startIdx	The start index for parsing. Optional and defaults to `0`.
	numberFormat	The format definition. Defaults to `nullptr`.
[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() [4/4]

template<typename TChar>

uint64_t alib::strings::TString< TChar >::ParseDec	(	TNumberFormat< TChar > *	numberFormat,
		integer *	newIdx = nullptr ) const

inline

Overloaded version of alib::strings::TString::ParseDec(integer,TNumberFormat<TChar>,integer)const "ParseDec" providing default values for omitted parameters.

Parameters

	numberFormat	The format definition. Defaults to `nullptr`.
[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 output parameter newIdx is set to point to the first character behind the parsed number.

Definition at line 1510 of file string.inl.

◆ ParseDecDigits()

template<typename TChar>

ALIB_DLL uint64_t alib::strings::TString< TChar >::ParseDecDigits	(	integer	startIdx = 0,
		integer *	newIdx = nullptr ) const

Parses an integral 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 integral 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. Therefore, this parameter can be used to check if a value was found.

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

◆ ParseFloat() [1/4]

template<typename TChar>

double alib::strings::TString< TChar >::ParseFloat ( integer * newIdx ) const

inline

Overloaded version of alib::strings::TString::ParseFloat(integer,TNumberFormat<TChar>,integer)const "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 output parameter newIdx is set to point to the first character behind the parsed number.

Definition at line 1819 of file string.inl.

◆ ParseFloat() [2/4]

template<typename TChar>

double alib::strings::TString< TChar >::ParseFloat	(	integer	startIdx,
		integer *	newIdx ) const

inline

Overloaded version of alib::strings::TString::ParseFloat(integer,TNumberFormat<TChar>,integer)const "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.

Definition at line 1836 of file string.inl.

◆ ParseFloat() [3/4]

template<typename TChar>

ALIB_DLL double alib::strings::TString< TChar >::ParseFloat	(	integer	startIdx = 0,
		TNumberFormat< TChar > *	numberFormat = nullptr,
		integer *	newIdx = nullptr ) const

Reads a floating point number at the given position from this string.

Parameter numberFormat defaults to nullptr. 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 number conversion, see class NumberFormat. All number-parsing interface methods have a corresponding implementation within this class.

Parameters

	startIdx	The start index for parsing. Optional and defaults to `0`.
	numberFormat	The format definition. Defaults to `nullptr`.
[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() [4/4]

template<typename TChar>

double alib::strings::TString< TChar >::ParseFloat	(	TNumberFormat< TChar > *	numberFormat,
		integer *	newIdx = nullptr ) const

inline

Overloaded version of alib::strings::TString::ParseFloat(integer,TNumberFormat<TChar>,integer)const "ParseFloat" providing default values for omitted parameters.

Parameters

	numberFormat	The format definition. Defaults to `nullptr`.
[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 output parameter newIdx is set to point to the first character behind the parsed number.

Definition at line 1805 of file string.inl.

◆ ParseHex() [1/4]

template<typename TChar>

uint64_t alib::strings::TString< TChar >::ParseHex ( integer * newIdx ) const

inline

Overloaded version of alib::strings::TString::ParseHex(integer,TNumberFormat<TChar>,integer)const "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 output parameter newIdx is set to point to the first character behind the parsed number.

Definition at line 1672 of file string.inl.

◆ ParseHex() [2/4]

template<typename TChar>

uint64_t alib::strings::TString< TChar >::ParseHex	(	integer	startIdx,
		integer *	newIdx ) const

inline

Overloaded version of alib::strings::TString::ParseHex(integer,TNumberFormat<TChar>,integer)const "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.

Definition at line 1689 of file string.inl.

◆ ParseHex() [3/4]

template<typename TChar>

ALIB_DLL uint64_t alib::strings::TString< TChar >::ParseHex	(	integer	startIdx = 0,
		TNumberFormat< TChar > *	numberFormat = nullptr,
		integer *	newIdx = nullptr ) const

Reads an unsigned 64-bit integer in hexadecimal format at the given position from this string.

Parameter numberFormat defaults to nullptr. 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 number-parsing interface methods have a corresponding implementation within this class.

Parameters

	startIdx	The start index for parsing. Optional and defaults to `0`.
	numberFormat	The format definition. Defaults to `nullptr`.
[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() [4/4]

template<typename TChar>

uint64_t alib::strings::TString< TChar >::ParseHex	(	TNumberFormat< TChar > *	numberFormat,
		integer *	newIdx = nullptr ) const

inline

Overloaded version of alib::strings::TString::ParseHex(integer,TNumberFormat<TChar>,integer)const "ParseHex" providing default values for omitted parameters.

Parameters

	numberFormat	The format definition. Defaults to `nullptr`.
[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 output parameter newIdx is set to point to the first character behind the parsed number.

Definition at line 1658 of file string.inl.

◆ ParseInt() [1/4]

template<typename TChar>

int64_t alib::strings::TString< TChar >::ParseInt ( integer * newIdx ) const

inline

Overloaded version of alib::strings::TString::ParseInt(integer,TNumberFormat<TChar>,integer)const "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 output parameter newIdx is set to point to the first character behind the parsed number.

Definition at line 1447 of file string.inl.

◆ ParseInt() [2/4]

template<typename TChar>

int64_t alib::strings::TString< TChar >::ParseInt	(	integer	startIdx,
		integer *	newIdx ) const

inline

Overloaded version of alib::strings::TString::ParseInt(integer,TNumberFormat<TChar>,integer)const "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.

Definition at line 1464 of file string.inl.

◆ ParseInt() [3/4]

template<typename TChar>

ALIB_DLL int64_t alib::strings::TString< TChar >::ParseInt	(	integer	startIdx = 0,
		TNumberFormat< TChar > *	numberFormat = nullptr,
		integer *	newIdx = nullptr ) const

Parses an integral value in decimal, binary, hexadecimal or octal format from the string

Parameter numberFormat defaults to nullptr. 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 `nullptr`.
[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() [4/4]

template<typename TChar>

int64_t alib::strings::TString< TChar >::ParseInt	(	TNumberFormat< TChar > *	numberFormat,
		integer *	newIdx = nullptr ) const

inline

Overloaded version of alib::strings::TString::ParseInt(integer,TNumberFormat<TChar>,integer)const "ParseInt" providing default values for omitted parameters.

Parameters

	numberFormat	The format definition. Defaults to `nullptr`.
[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 output parameter newIdx is set to point to the first character behind the parsed number.

Definition at line 1433 of file string.inl.

◆ ParseOct() [1/4]

template<typename TChar>

uint64_t alib::strings::TString< TChar >::ParseOct ( integer * newIdx ) const

inline

Overloaded version of alib::strings::TString::ParseOct(integer,TNumberFormat<TChar>,integer)const "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 output parameter newIdx is set to point to the first character behind the parsed number.

Definition at line 1746 of file string.inl.

◆ ParseOct() [2/4]

template<typename TChar>

uint64_t alib::strings::TString< TChar >::ParseOct	(	integer	startIdx,
		integer *	newIdx ) const

inline

Overloaded version of alib::strings::TString::ParseOct(integer,TNumberFormat<TChar>,integer)const "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.

Definition at line 1763 of file string.inl.

◆ ParseOct() [3/4]

template<typename TChar>

ALIB_DLL uint64_t alib::strings::TString< TChar >::ParseOct	(	integer	startIdx = 0,
		TNumberFormat< TChar > *	numberFormat = nullptr,
		integer *	newIdx = nullptr ) const

Reads an unsigned 64-bit integer in octal format at the given position from this string.

Parameter numberFormat defaults to nullptr. 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 number-parsing interface methods have a corresponding implementation within this class.

Parameters

	startIdx	The start index for parsing. Optional and defaults to `0`.
	numberFormat	The format definition. Defaults to `nullptr`.
[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() [4/4]

template<typename TChar>

uint64_t alib::strings::TString< TChar >::ParseOct	(	TNumberFormat< TChar > *	numberFormat,
		integer *	newIdx = nullptr ) const

inline

Overloaded version of alib::strings::TString::ParseOct(integer,TNumberFormat<TChar>,integer)const "ParseOct" providing default values for omitted parameters.

Parameters

	numberFormat	The format definition. Defaults to `nullptr`.
[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 output parameter newIdx is set to point to the first character behind the parsed number.

Definition at line 1732 of file string.inl.

◆ rbegin()

template<typename TChar>

const_reverse_iterator alib::strings::TString< TChar >::rbegin ( ) const

inline

Returns a reverse iterator pointing to a constant character at the end of this string.

Returns: The last character of this string.

Definition at line 2174 of file string.inl.

◆ rend()

template<typename TChar>

const_reverse_iterator alib::strings::TString< TChar >::rend ( ) const

inline

Returns a reverse iterator pointing before the start of this string.

Returns: The character before this string.

Definition at line 2178 of file string.inl.

◆ size()

template<typename TChar>

size_type alib::strings::TString< TChar >::size ( ) const

inline

Returns Length as size_t. Added for compatibility with the standard library.

Returns: The character before this string.

Definition at line 2190 of file string.inl.

◆ StartsWith()

template<typename TChar>

template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>

bool alib::strings::TString< TChar >::StartsWith ( const TString< TChar > & needle ) const

inline

Returns true, if this string starts with the contents of the string-like object given with parameter needle. In the special case that needle is empty, true is returned.

Template Parameters

TSensitivity	Determines if comparison is case-sensitive (the default) or not.
TCheck	Defaults to CHK, which is the normal invocation mode. If `<false>` is given, the given needle must not be empty and must not be longer than this string! pos is performed and needle must not be nulled.

Parameters

needle The string to compare the start of this string with. If nulled or empty, true is returned.

Returns: true if needle is found at the start of this string, false otherwise.

Definition at line 772 of file string.inl.

◆ Substring()

template<typename TChar>

template<typename TCheck = CHK>

TString< TChar > alib::strings::TString< TChar >::Substring	(	integer	regionStart,
		integer	regionLength = MAX_LEN ) const

inline

Returns a new string object representing a substring of the string that this object represents.

Template Parameters

TCheck Defaults to CHK, which is the normal invocation mode. If false is given, no range check is performed.

Parameters

regionStart	The start of the substring within this string.
regionLength	The length of the substring to return. Defaults to MAX_LEN.

Returns: A string representing a region of this string.

Definition at line 386 of file string.inl.

◆ WStringLength()

template<typename TChar>

integer alib::strings::TString< TChar >::WStringLength ( ) const

Returns the length of the string if represented as a wide character string. If template parameter TChar equals wchar, then this is identical with Length. Otherwise the calculation is done using

mbsnrtowcs() (without providing a conversion buffer) on glibc platforms (e.g., Linux)
MultiByteToWideChar() (without providing a conversion buffer) on the Windows platform.

If the conversion fails, -1 is returned.

Note: On GNU/Linux and Mac OS, it might be necessary to invoke standard C method setlocale() once, before using this method, to successfully calculate the length. This by default is done during library initialization, if performed on class Basecamp.

Returns: The length of string when it was converted to wide characters. If counting failed (what means that a corresponding conversion would also fail) the Length is returned.

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

string.inl

Description:

Inner Type Index:

Public Type Index:

Public Method Index:

Protected Field Index:

Protected Method Index:

Type Definition Details:

◆ const_iterator

◆ const_reverse_iterator

◆ size_type

◆ value_type

Field Details:

◆ buffer

◆ length

Constructor(s) / Destructor Details:

◆ TString() [1/8]

◆ TString() [2/8]

◆ TString() [3/8]

◆ TString() [4/8]

◆ TString() [5/8]

◆ TString() [6/8]

◆ TString() [7/8]

◆ TString() [8/8]

Method Details:

◆ AdjustRegion()

◆ Allocate()

◆ begin()

◆ Buffer()

◆ cbegin()

◆ cend()

◆ CharAt()

◆ CharAtEnd()

◆ CharAtStart()

◆ CompareTo() [1/3]

◆ CompareTo() [2/3]

◆ CompareTo() [3/3]

◆ ContainsAt()

◆ CopyTo()

◆ Count() [1/2]

◆ Count() [2/2]

◆ CountChar() [1/2]

◆ CountChar() [2/2]

◆ crbegin()

◆ crend()

◆ end()

◆ EndsWith()

◆ Equals()

◆ Free()

◆ Hashcode()

◆ HashcodeIgnoreCase()

◆ IndexOf() [1/3]

◆ IndexOf() [2/3]

◆ IndexOf() [3/3]

◆ IndexOfAny()

◆ IndexOfFirstDifference()

◆ IndexOfOrLength() [1/2]

◆ IndexOfOrLength() [2/2]

◆ IndexOfSegmentEnd()

◆ indexOfString()

◆ IsEmpty()

◆ IsNotEmpty()

◆ IsNotNull()

◆ IsNull()

◆ LastIndexOf()

◆ LastIndexOfAny()

◆ Length()

◆ operator T() [1/2]

◆ operator T() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator[]()

◆ ParseBin() [1/4]

◆ ParseBin() [2/4]

◆ ParseBin() [3/4]

◆ ParseBin() [4/4]

◆ ParseDec() [1/4]

◆ ParseDec() [2/4]

◆ ParseDec() [3/4]

◆ ParseDec() [4/4]

◆ ParseDecDigits()