Description:

template<typename TChar, typename TAllocator = lang::HeapAllocator>
requires alib::lang::IsAllocator<TAllocator>
class alib::strings::TAString< TChar, TAllocator >

Specializes base class String to implement mutable character strings using writable and extendable buffer memory.

Construction:
Construction is described in Programmer's Manual, section 3.1.3 AString Construction.

Buffer Management:
There are two possible types of buffers:

Internal buffers
This is the standard case and implements a buffer that is allocated and freed using the allocator type-traits given with template parameter TAllocator. Allocation size eventually grows over time and never shrinks, unless explicitly demanded by the using code. Those buffers are deleted when objects of this type are deleted.
External buffers
Set with overloaded method SetBuffer(TChar*, integer, integer, lang::Responsibility). This class does not manage external buffers. However, if their capacity is exceeded, they will automatically become replaced by an internal buffer. Such a replacement, by default, raises a warning with debug-builds. In situations that buffer replacement is accepted, warnings can be disabled with the method DbgDisableBufferReplacementWarning.

The method SetBuffer provides a boolean parameter that also allows letting an object of this class take control of a buffer provided from outside. In this case, the buffer is considered an internal buffer, hence allocated using the same allocator traits (and if not heap allocation, then also the same allocator instance!), rather than an external one.

The default constructor creates a nulled AString which does not dispose of an allocated buffer, yet. Destruction will free the currently allocated buffer - if internal.

Copy/Move Constructor and Assignment
The class provides the minimum equipment to be usable as member type of standard containers like std::vector. This includes a copy and move constructor as well as a copy assignment operator. Nevertheless, this class is not guaranteed to perform well when used with container types and such use should be avoided if possible.
Outside of containers, the automatic C++ copy and move construction semantics should be avoided. For example, the move constructor grabs the buffer of a given movable AString, as long as this given object does not use an external buffer. If it does, the contents of the movable object is copied like in the copy constructor.

Consequently, objects of this class should have a well defined scope and not be copied and moved like the lightweight string-types. A move assignment operator is not given. The rationale for this design decision is that usually, a "more temporary" string would be assigned to a "less temporary" one. In this case, it would not be helpful to replace the already allocated storage of the assignee.

By the same token, besides the copy assignment, no other assignment operators are given. Instead, method Reset(const TAppendable&) is to be used to clear the existing buffer and insert new string content. This helps to distinguish AString variables from those of the lightweight string-types as shown in the following snippet:

   string1= "Hello";       // Can't be an AString. Rather String, Substring or CString
   string2.Reset("World"); // Obviously an AString. The given string is copied!

Writing directly into the Buffer:
Parent class String holds its protected field buffer in an anonymous C++ union of two pointers, one typed const char* and the other char*. This class exposes the non-constant buffer pointer of that union with method VBuffer. This allows users of this class to freely operate on the buffer. Of course, it is up to the programmer that the integrity of the instance is kept intact and that also the Capacity of the buffer must not be exceeded. In the case that the string's length is changed, method SetLength needs to be used to notify such change with the AString object. The latter of course is invokable only on mutable objects, while method VBuffer is declared const.

In addition to this, a bunch of methods allow the modification of single characters. operator[] is extended by a non-const version that returns a reference to a character instead of just the character value.

Appending Objects to AStrings:
This class is used to provide a global concept of having a sort of "ToString" method with any C++ class. For this, the class provides method Append, which uses template meta programming to accept types with a corresponding specialization of functor template <typename TAppendable, typename TChar, typename TAllocator> AppendableTraits.

The concept is described in detail with chapter 5.1 Appending Custom Types of this module's Programmer's Manual.

Template Parameters

TChar	The character type. Alias names for specializations of this class using character types character, nchar, wchar, xchar, complementChar and strangeChar are provided in namespace alib with type , definitions AString, NAString WAString, XAString, ComplementAString and StrangeAString.
TAllocator	The allocator type to use.

Definition at line 174 of file tastring.inl.

Inheritance diagram for alib::strings::TAString< TChar, TAllocator >:

Public Type Index:
using	AllocatorType = TAllocator
	Exposes the allocator type specified by template parameter TAllocator.
using	iterator = typename base::template TRandomAccessIterator<TChar>
using	reverse_iterator = std::reverse_iterator<iterator>
	Same as iterator, but working from the end to the start of the string.
Public Type Index: inherited from alib::strings::TString< TChar >
using	const_iterator = TRandomAccessIterator<const TChar>
using	const_reverse_iterator = std::reverse_iterator<const_iterator>
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 Type Index: inherited from alib::lang::AllocatorMember< lang::HeapAllocator >
using	AllocatorType
	Exposes the allocator type.

Public Method Index:
constexpr	TAString ()
	Constructs an empty, nulled AString (does not allocate a buffer).
template<typename TAppendable>
	TAString (const TAppendable &src)
	TAString (const TAString &copy)
constexpr	TAString (TAllocator &pAllocator)
	TAString (TAString &&move) noexcept
	~TAString () noexcept
	Destructs an AString object. An internally allocated buffer will be deleted.
TAString &	_ ()
template<typename TCheck = CHK, class TAppendable>
TAString &	_ (const TAppendable &src)
template<typename TCheck = CHK>
TAString &	_ (const TString< TChar > &src, integer regionStart, integer regionLength=MAX_LEN)
template<typename TCheck = CHK>
TAString &	Append (characters::IsCharacter auto src)
template<typename TCheck = CHK, typename TAppendable>
TAString &	Append (const TAppendable &src)
template<typename TCheck = CHK>
TAString &	Append (const TChar *src, integer srcLength)
template<typename TCheck = CHK, typename TCharSrc>
TAString &	Append (const TCharSrc *src, integer srcLength)
template<typename TCheck = CHK>
TAString &	Append (const TString< TChar > &src, integer regionStart, integer regionLength=MAX_LEN)
template<typename TCheck = CHK, typename TStringSource>
TAString &	Append (const TStringSource &src)
template<typename TCheck = CHK>
TAString &	Append (TChar src)
iterator	begin ()
const_iterator	begin () const
integer	Capacity () const
void	dbgCheck () const
void	DbgDisableBufferReplacementWarning ()
template<typename TCheck = CHK>
TAString &	Delete (integer regionStart, integer regionLength=MAX_LEN)
TAString &	DeleteEnd (const TString< TChar > &deleteIfMatch)
template<typename TCheck = CHK>
TAString &	DeleteEnd (integer regionLength)
TAString &	DeleteStart (const TString< TChar > &deleteIfMatch)
template<typename TCheck = CHK>
TAString &	DeleteStart (integer regionLength)
integer	DetectLength (integer offset=0)
iterator	end ()
const_iterator	end () const
void	EnsureRemainingCapacity (integer spaceNeeded)
void	GrowBufferAtLeastBy (integer minimumGrowth)
bool	HasInternalBuffer () const
template<typename TCheck = CHK>
TAString &	InsertAt (const TString< TChar > &src, integer pos)
template<typename TCheck = CHK>
TAString &	InsertChars (TChar c, integer qty)
template<typename TCheck = CHK>
TAString &	InsertChars (TChar c, integer qty, integer pos)
template<typename TCheck = CHK>
TAString &	InsertUninitialized (integer pos, integer size)
TAString &	NewLine ()
template<typename T>
constexpr	operator T () const
template<typename TAppendable>
TAString &	operator+= (const TAppendable &src)
template<typename TAppendable>
TAString &	operator<< (const TAppendable &src)
TAString &	operator= (const TAString &copy)
TChar &	operator[] (integer idx)
TChar	operator[] (integer idx) const
constexpr TChar	pop_back ()
constexpr void	push_back (TChar ch)
reverse_iterator	rbegin ()
const_reverse_iterator	rbegin () const
reverse_iterator	rend ()
const_reverse_iterator	rend () const
template<typename TCheck = CHK>
TAString &	ReplaceRegion (TChar c, integer regionStart, integer regionLength)
template<typename TCheck = CHK>
TAString &	ReplaceSubstring (const TString< TChar > &src, integer regionStart, integer regionLength)
TAString &	Reset ()
template<typename TCheck = CHK, typename TAppendable>
TAString &	Reset (const TAppendable &src)
template<typename TCheck = CHK>
TAString &	Reverse (integer regionStart=0, integer regionLength=MAX_LEN)
integer	SearchAndReplace (const TString< TChar > &needle, const TString< TChar > &replacement, integer startIdx=0, integer maxReplacements=strings::MAX_LEN, lang::Case sensitivity=lang::Case::Sensitive, integer endIdx=strings::MAX_LEN)
integer	SearchAndReplace (TChar needle, TChar replacement, integer startIdx=0, integer endIdx=strings::MAX_LEN)
void	SetBuffer (integer newCapacity)
void	SetBuffer (TChar *extBuffer, integer extBufferSize, integer extLength=0, lang::Responsibility responsibility=lang::Responsibility::KeepWithSender)
template<typename TCheck = CHK>
void	SetCharAt (integer idx, TChar c)
void	SetLength (integer newLength)
void	SetNull ()
	Invokes SetBuffer(0).
TAString &	ShortenBy (integer charsToRemove)
TAString &	ShortenTo (integer newLength)
constexpr const TChar *	Terminate () const
template<typename TCheck = CHK>
TAString &	ToLower (integer regionStart=0, integer regionLength=MAX_LEN)
template<typename TCheck = CHK>
TAString &	ToUpper (integer regionStart=0, integer regionLength=MAX_LEN)
TAString &	Trim (const TCString< TChar > &trimChars=CStringConstantsTraits< TChar >::DefaultWhitespaces())
integer	TrimAt (integer idx, const TCString< TChar > &trimChars=CStringConstantsTraits< TChar >::DefaultWhitespaces())
TAString &	TrimEnd (const TCString< TChar > &trimChars=CStringConstantsTraits< TChar >::DefaultWhitespaces())
TAString &	TrimStart (const TCString< TChar > &trimChars=CStringConstantsTraits< TChar >::DefaultWhitespaces())
TChar *	VBuffer () const
Public Method Index: inherited from alib::strings::TString< TChar >
constexpr	TString () noexcept=default
template<typename T>
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>
constexpr	TString (T &src) noexcept
template<typename TAllocator>
	TString (TAllocator &allocator, const TString< TChar > &copy)
constexpr	TString (TString &&) noexcept=default
	Defaulted move constructor.
bool	AdjustRegion (integer &regionStart, integer &regionLength) const
template<typename TAllocator>
void	Allocate (TAllocator &allocator, const TString< TChar > &copy)
const_iterator	begin () const
constexpr const TChar *	Buffer () const
const_iterator	cbegin () const
const_iterator	cend () const
template<typename TCheck = CHK>
TChar	CharAt (integer idx) const
template<typename TCheck = CHK>
TChar	CharAtEnd () const
template<typename TCheck = CHK>
TChar	CharAtStart () 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>
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< TChar > &rhs) const
template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>
bool	ContainsAt (const TString &needle, integer pos) const
integer	CopyTo (TChar *dest) const
template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>
integer	Count (const TString &needle, const TString &omit, integer startPos=0) const
template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>
integer	Count (const TString &needle, integer startPos=0) 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
const_reverse_iterator	crbegin () const
const_reverse_iterator	crend () const
const_iterator	end () const
template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>
bool	EndsWith (const TString &needle) const
template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>
bool	Equals (const TString< TChar > &rhs) const
template<typename TAllocator>
void	Free (TAllocator &allocator)
std::size_t	Hashcode () const
std::size_t	HashcodeIgnoreCase () 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	IndexOf (TChar needle, integer regionStart, integer regionLength) const
template<typename TCheck = CHK>
integer	IndexOf (TChar needle, integer startIdx=0) const
template<lang::Inclusion TInclusion, typename TCheck = CHK>
integer	IndexOfAny (const TString &needles, integer startIdx=0) const
template<typename TCheck = CHK>
integer	IndexOfFirstDifference (const TString &needle, lang::Case sensitivity=lang::Case::Sensitive, integer startIdx=0) const
integer	IndexOfOrLength (TChar needle) const
template<typename TCheck = CHK>
integer	IndexOfOrLength (TChar needle, integer startIdx) const
integer	IndexOfSegmentEnd (TChar opener, TChar closer, integer idx) const
constexpr bool	IsEmpty () const
constexpr bool	IsNotEmpty () const
constexpr bool	IsNotNull () const
constexpr bool	IsNull () const
template<typename TCheck = CHK>
integer	LastIndexOf (TChar needle, integer startIndex=MAX_LEN) const
template<lang::Inclusion TInclusion, typename TCheck = CHK>
integer	LastIndexOfAny (const TString &needles, integer startIdx=MAX_LEN) const
constexpr integer	Length () const
template<typename T>
constexpr	operator T () const
constexpr TString &	operator= (const TString &) noexcept=default
constexpr TString &	operator= (TString &&) noexcept=default
TChar	operator[] (integer idx) const
uint64_t	ParseBin (integer *newIdx) const
uint64_t	ParseBin (integer startIdx, integer *newIdx) const
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	ParseDec (integer *newIdx) const
uint64_t	ParseDec (integer startIdx, integer *newIdx) const
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	ParseDecDigits (integer startIdx=0, integer *newIdx=nullptr) const
double	ParseFloat (integer *newIdx) const
double	ParseFloat (integer startIdx, integer *newIdx) const
double	ParseFloat (integer startIdx=0, TNumberFormat< TChar > numberFormat=nullptr, integer newIdx=nullptr) const
double	ParseFloat (TNumberFormat< TChar > numberFormat, integer newIdx=nullptr) const
uint64_t	ParseHex (integer *newIdx) const
uint64_t	ParseHex (integer startIdx, integer *newIdx) const
uint64_t	ParseHex (integer startIdx=0, TNumberFormat< TChar > numberFormat=nullptr, integer newIdx=nullptr) const
uint64_t	ParseHex (TNumberFormat< TChar > numberFormat, integer newIdx=nullptr) const
int64_t	ParseInt (integer *newIdx) const
int64_t	ParseInt (integer startIdx, integer *newIdx) const
int64_t	ParseInt (integer startIdx=0, TNumberFormat< TChar > numberFormat=nullptr, integer newIdx=nullptr) const
int64_t	ParseInt (TNumberFormat< TChar > numberFormat, integer newIdx=nullptr) const
uint64_t	ParseOct (integer *newIdx) const
uint64_t	ParseOct (integer startIdx, integer *newIdx) const
uint64_t	ParseOct (integer startIdx=0, TNumberFormat< TChar > numberFormat=nullptr, integer newIdx=nullptr) const
uint64_t	ParseOct (TNumberFormat< TChar > numberFormat, integer newIdx=nullptr) const
const_reverse_iterator	rbegin () const
const_reverse_iterator	rend () const
size_type	size () const
template<typename TCheck = CHK, lang::Case TSensitivity = lang::Case::Sensitive>
bool	StartsWith (const TString &needle) const
template<typename TCheck = CHK>
TString< TChar >	Substring (integer regionStart, integer regionLength=MAX_LEN) const
integer	WStringLength () const
Public Method Index: inherited from alib::lang::AllocatorMember< lang::HeapAllocator >
	AllocatorMember ()
AllocatorInterface< lang::HeapAllocator >	AI () const noexcept
lang::HeapAllocator &	GetAllocator () const noexcept

Protected Type Index:
using	allocBase = lang::AllocatorMember<TAllocator>
	The type of the base class that stores the allocator.
using	base = TString<TChar>
	The base string-type.

Protected Field Index:
integer	capacity
bool	dbgWarnWhenExternalBufferIsReplaced =true
integer	debugLastAllocRequest =0
Protected Field Index: inherited from alib::strings::TString< TChar >
const TChar *	buffer
integer	length
Protected Field Index: inherited from alib::lang::AllocatorMember< lang::HeapAllocator >
lang::HeapAllocator *	allocator
	The allocator stored.

Protected Method Index:
constexpr	TAString (TAllocator &pAllocator, TChar *extBuffer, integer extBufferSize)
constexpr	TAString (TChar *extBuffer, integer extBufferSize)
Protected Method Index: inherited from alib::strings::TString< TChar >
template<lang::Case TSensitivity = lang::Case::Sensitive>
integer	indexOfString (const TString &needle, integer startIdx, integer endIdx) const

Type Definition Details:

◆ AllocatorType

template<typename TChar, typename TAllocator = lang::HeapAllocator>

using alib::strings::TAString< TChar, TAllocator >::AllocatorType = TAllocator

Exposes the allocator type specified by template parameter TAllocator.

Definition at line 298 of file tastring.inl.

◆ allocBase

template<typename TChar, typename TAllocator = lang::HeapAllocator>

using alib::strings::TAString< TChar, TAllocator >::allocBase = lang::AllocatorMember<TAllocator>

protected

The type of the base class that stores the allocator.

Definition at line 185 of file tastring.inl.

◆ base

template<typename TChar, typename TAllocator = lang::HeapAllocator>

using alib::strings::TAString< TChar, TAllocator >::base = TString<TChar>

protected

The base string-type.

Definition at line 182 of file tastring.inl.

◆ iterator

template<typename TChar, typename TAllocator = lang::HeapAllocator>

using alib::strings::TAString< TChar, TAllocator >::iterator = typename base::template TRandomAccessIterator<TChar>

A std::iterator_traits type, implementing the standard library concept of RandomAccessIterator . While parent class String provides a constant iterator only, this class exposes an iterator that allows the modification of the character an iterator references.

Definition at line 1994 of file tastring.inl.

◆ reverse_iterator

template<typename TChar, typename TAllocator = lang::HeapAllocator>

using alib::strings::TAString< TChar, TAllocator >::reverse_iterator = std::reverse_iterator<iterator>

Same as iterator, but working from the end to the start of the string.

Definition at line 1997 of file tastring.inl.

Field Details:

◆ capacity

template<typename TChar, typename TAllocator = lang::HeapAllocator>

integer alib::strings::TAString< TChar, TAllocator >::capacity

protected

The current size of the buffer excluding the trailing '\0'. If no buffer is allocated, this field is 0. If an external Buffer not managed by this class is used, then the size of that buffer is stored as a negative value. Method Capacity therefore returns the absolute value of this field.

Definition at line 192 of file tastring.inl.

◆ dbgWarnWhenExternalBufferIsReplaced

template<typename TChar, typename TAllocator = lang::HeapAllocator>

bool alib::strings::TAString< TChar, TAllocator >::dbgWarnWhenExternalBufferIsReplaced =true

protected

If true, a warning is raised when an external buffer, whose life-cycle is not controlled by this instance gets replaced. This field exists only with debug-compilations of this class.

See also: See method DbgDisableBufferReplacementWarning for more information.

Definition at line 227 of file tastring.inl.

◆ debugLastAllocRequest

template<typename TChar, typename TAllocator = lang::HeapAllocator>

integer alib::strings::TAString< TChar, TAllocator >::debugLastAllocRequest =0

protected

Used to check if previous grow request was exactly what is now the length.
This field is available only if code selection macro ALIB_DEBUG_STRINGS is set.

Definition at line 199 of file tastring.inl.

Constructor(s) / Destructor Details:

◆ TAString() [1/7]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

alib::strings::TAString< TChar, TAllocator >::TAString	(	TAllocator &	pAllocator,
		TChar *	extBuffer,
		integer	extBufferSize )

inlineexplicitconstexprprotected

Constructs an AString with the given external buffer and allocator. The given buffer's life-cycle is considered to be managed externally.
This constructor is protected and provided for derived classes that dispose of their own buffer.

Note

Protected access was given to this method also to avoid misunderstandings that this constructor is not for providing copyable string data. If the functionality of this constructor is needed, it can simply be imitated by

default construction and
immediate invocation of SetBuffer(TChar*, integer, integer, lang::Responsibility).

Parameters

pAllocator	The allocator to use.
extBuffer	The external buffer to use.
extBufferSize	The capacity of the given buffer.

Definition at line 264 of file tastring.inl.

◆ TAString() [2/7]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

alib::strings::TAString< TChar, TAllocator >::TAString	(	TChar *	extBuffer,
		integer	extBufferSize )

inlineexplicitconstexprprotected

Constructs an AString with the given external buffer. The given buffer's life-cycle is considered to be managed externally.
This constructor is protected and provided for derived classes that dispose of their own buffer.

Note

Protected access was given to this method also to avoid misunderstandings that this constructor is not for providing copyable string data. If the functionality of this constructor is needed, it can simply be imitated by

default construction and
immediate invocation of SetBuffer(TChar*, integer, integer, lang::Responsibility).

Parameters

extBuffer	The external buffer to use.
extBufferSize	The capacity of the given buffer.

Definition at line 288 of file tastring.inl.

◆ TAString() [3/7]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

alib::strings::TAString< TChar, TAllocator >::TAString ( )

inlineexplicitconstexpr

Constructs an empty, nulled AString (does not allocate a buffer).

Definition at line 304 of file tastring.inl.

◆ TAString() [4/7]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

alib::strings::TAString< TChar, TAllocator >::TAString ( TAllocator & pAllocator )

inlineexplicitconstexpr

Constructs an empty, nulled AString (does not allocate a buffer). This constructor is to be used with template parameter TAllocator denoting an allocation strategy that includes the need of storing an allocator type in field allocator. For the standard, heap-allocated type AString, this constructor is not applicable.

Parameters

pAllocator The allocator to use.

Definition at line 315 of file tastring.inl.

◆ TAString() [5/7]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

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

inlineexplicit

Copy constructor that allocates memory and copies the contents of the given object.

Parameters

copy	The object to copy.

Definition at line 323 of file tastring.inl.

◆ TAString() [6/7]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

alib::strings::TAString< TChar, TAllocator >::TAString ( TAString< TChar, TAllocator > && move )

inlinenoexcept

Move constructor. See Copy/Move Constructor and Assignment for details.

Parameters

move	The object to move.

Definition at line 336 of file tastring.inl.

◆ TAString() [7/7]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TAppendable>

alib::strings::TAString< TChar, TAllocator >::TAString ( const TAppendable & src )

inlineexplicit

Constructs the object and uses Append to create a string representation of the given object.

Template Parameters

TAppendable The type of parameter source that has a specialization of functor template <typename TAppendable, typename TChar, typename TAllocator> AppendableTraits.

Parameters

src	The source object to append to this string.

Definition at line 376 of file tastring.inl.

◆ ~TAString()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

alib::strings::TAString< TChar, TAllocator >::~TAString ( )

inlinenoexcept

Destructs an AString object. An internally allocated buffer will be deleted.

Definition at line 381 of file tastring.inl.

Method Details:

◆ _() [1/3]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

TAString & alib::strings::TAString< TChar, TAllocator >::_ ( )

inline

Sets the length of the string to zero. Same as method Reset. Provided for compatibility with C# and Java versions of ALib.

Returns: *this to allow concatenated calls.

Definition at line 1417 of file tastring.inl.

◆ _() [2/3]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK, class TAppendable>

TAString & alib::strings::TAString< TChar, TAllocator >::_ ( const TAppendable & src )

inline

Alias to overloaded methods Append.

Template Parameters

TCheck	Defaults to CHK, which is the normal invocation mode. If NC is given, checks are omitted. (The specific behavior depends on the overloaded Append method that is called.)
TAppendable	The type of parameter source.

Parameters

src	The source object to append a string representation for.

Returns: *this to allow concatenated calls.

Definition at line 1327 of file tastring.inl.

◆ _() [3/3]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK>

TAString & alib::strings::TAString< TChar, TAllocator >::_	(	const TString< TChar > &	src,
		integer	regionStart,
		integer	regionLength = MAX_LEN )

inline

Alias method of Append(const TString<TChar>&, integer, integer).
Provided for compatibility with C# and Java versions of ALib.

Template Parameters

TCheck Chooses checking or non-checking implementation. Defaults to CHK.

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. Defaults to MAX_LEN

Returns: *this to allow concatenated calls.

Definition at line 1341 of file tastring.inl.

◆ Append() [1/7]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK>

TAString & alib::strings::TAString< TChar, TAllocator >::Append ( characters::IsCharacter auto src )

inline

Appends a single character of a different type. If this string is narrow, the given character is UTF-8 encoded.

Template Parameters

TCheck Defaults to CHK, which is the normal invocation mode. Here, nothing is appended if the given character is 0, but still this instance will switch to empty state if it was nulled before. If NC is given, src is not checked for being 0.

Parameters

src	The character value to append. Only values of types that satisfy the concept IsCharacter are accepted.

Returns: *this to allow concatenated calls.

Definition at line 1268 of file tastring.inl.

◆ Append() [2/7]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK, typename TAppendable>

TAString & alib::strings::TAString< TChar, TAllocator >::Append ( const TAppendable & src )

inline

Appends a string-representation of the given object src of template type T to this AString. Type T needs to satisfy the concept IsAppendable, which is achieved by specializing the type trait AppendableTraits accordingly.

See also: See chapter 5.1 Appending Custom Types of this module's Programmer's Manual for more information.

Template Parameters

TCheck	Defaults to CHK, which is the normal invocation mode. If after the append operation this string is still nulled, an initial buffer is allocated and the state of this instance changes to empty. If NC is given, a nulled string may remain nulled.
TAppendable	The type of parameter src.

Parameters

src	The object to "stringify" and append.

Returns: *this to allow concatenated calls.

Definition at line 1188 of file tastring.inl.

◆ Append() [3/7]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK>

TAString & alib::strings::TAString< TChar, TAllocator >::Append	(	const TChar *	src,
		integer	srcLength )

inline

Appends an array of the same character type.

Template Parameters

TCheck Defaults to CHK, which is the normal invocation mode. If <false>, no nullptr check is done on parameter src. Also, this object would not lose a nulled state when the given cstring portion is empty.

Parameters

src	A pointer to the start of the array to append.
srcLength	The length of the string.

Returns: *this to allow concatenated calls.

Definition at line 1101 of file tastring.inl.

◆ Append() [4/7]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK, typename TCharSrc>

TAString & alib::strings::TAString< TChar, TAllocator >::Append	(	const TCharSrc *	src,
		integer	srcLength )

inline

Appends an array of an incompatible character type.

Template Parameters

TCharSrc	The character type of the given array.
TCheck	Defaults to CHK, which is the normal invocation mode. If `<false>`, no nullptr check is done on parameter src. Also, this object would not lose a nulled state when the given cstring portion is empty.

Parameters

src	A pointer to the start of the array to append.
srcLength	The length of the string.

Returns: *this to allow concatenated calls.

Definition at line 788 of file tastring.inl.

◆ Append() [5/7]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK>

TAString & alib::strings::TAString< TChar, TAllocator >::Append	(	const TString< TChar > &	src,
		integer	regionStart,
		integer	regionLength = MAX_LEN )

inline

Appends a region of another String. The checking version adjusts the given region to the bounds of the source string.

Note: When using the non-checking version, parameter regionLength must be set explicitly to the correct value (instead of using the default value).

Template Parameters

TCheck Chooses checking or non-checking implementation. Defaults to CHK.

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. Defaults to MAX_LEN

Returns: *this to allow concatenated calls.

Definition at line 1144 of file tastring.inl.

◆ Append() [6/7]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK, typename TStringSource>

TAString & alib::strings::TAString< TChar, TAllocator >::Append ( const TStringSource & src )

inline

Appends string-like types which satisfy either of the concepts IsImplicitArraySource IsImplicitZTArraySource.

Template Parameters

TCheck	Defaults to CHK, which is the normal invocation mode. If NC is given, a nulled string may remain nulled, and if the character buffer received from src is `nullptr`, this method has undefined behavior.
TStringSource	The type of parameter src.

Parameters

src	The string-type object to append.

Returns: *this to allow concatenated calls.

Definition at line 1211 of file tastring.inl.

◆ Append() [7/7]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK>

TAString & alib::strings::TAString< TChar, TAllocator >::Append ( TChar src )

inline

Appends a single character of compatible type.

Template Parameters

TCheck Defaults to CHK, which is the normal invocation mode. Here, nothing is appended if the given character is 0, but still this instance will switch to empty state if it was nulled before. If NC is given, src is not checked for being 0.

Parameters

src	The character object to append.

Returns: *this to allow concatenated calls.

Definition at line 1240 of file tastring.inl.

◆ begin() [1/2]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

iterator alib::strings::TAString< TChar, TAllocator >::begin ( )

inline

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

Returns: The start of this string.

Definition at line 2001 of file tastring.inl.

◆ begin() [2/2]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

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 1952 of file string.inl.

◆ Capacity()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

integer alib::strings::TAString< TChar, TAllocator >::Capacity ( ) const

inline

The size of the internal buffer (this is excluding the trailing '\0' character) which is reserved to terminate the string if needed. In other words, the internal memory available is the size returned here plus one.

Returns: The size of the allocated buffer.

Definition at line 588 of file tastring.inl.

◆ dbgCheck()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

void alib::strings::TAString< TChar, TAllocator >::dbgCheck ( ) const

Checks this object's state. This method is internally invoked with almost every other method of this class, but only if the configuration macro ALIB_DEBUG_STRINGS is true.
Invocations to this method should be performed using macro ALIB_STRING_DBG_CHK.

See also: For (a little) more information see 6.4 Debugging Strings of this module's Programmer's Manual

◆ DbgDisableBufferReplacementWarning()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

void alib::strings::TAString< TChar, TAllocator >::DbgDisableBufferReplacementWarning ( )

inline

Used to disable warnings that are by default raised in debug-compilations of method SetBuffer.

Note: In release-compilations this inline method is empty and will be optimized out.

See also: See method SetBuffer for more information.

Definition at line 241 of file tastring.inl.

◆ Delete()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK>

TAString & alib::strings::TAString< TChar, TAllocator >::Delete	(	integer	regionStart,
		integer	regionLength = MAX_LEN )

inline

Removes a region from the string by moving the remaining string behind the region to the region start and adjusting the string's length.

A range check is performed and the region is cut to fit to the string. The non-checking version (TCheck = NC) omits the check, but still allows leaving parameter regionLength as default (respectively allows the sum of parameters regionStart and regionLength to be longer than the length of this AString). In this case, this string is cut starting from index regionStart.

Note: See also methods Reset, DeleteStart and DeleteEnd.

Template Parameters

TCheck Defaults to CHK, which is the normal invocation mode. If <false> is added to the method name, the start of the region is not adjusted to the string's bounds.

Parameters

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

Returns: *this to allow concatenated calls.

Definition at line 1575 of file tastring.inl.

◆ DeleteEnd() [1/2]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

TAString & alib::strings::TAString< TChar, TAllocator >::DeleteEnd ( const TString< TChar > & deleteIfMatch )

inline

Deletes the given string from the end of this string. If this string does not end with the given string, nothing is done.

Parameters

deleteIfMatch The string to be deleted at the end.

Returns: *this to allow concatenated calls.

Definition at line 1696 of file tastring.inl.

◆ DeleteEnd() [2/2]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK>

TAString & alib::strings::TAString< TChar, TAllocator >::DeleteEnd ( integer regionLength )

inline

Reduces the length of the string by the given number of characters.

Template Parameters

TCheck Defaults to CHK, which is the normal invocation mode. If <false> is added to the method name, no parameter checks are performed and any given value is just subtracted from the current length.

Parameters

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

Returns: *this to allow concatenated calls.

Definition at line 1670 of file tastring.inl.

◆ DeleteStart() [1/2]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

TAString & alib::strings::TAString< TChar, TAllocator >::DeleteStart ( const TString< TChar > & deleteIfMatch )

inline

Deletes the given string from the start of this string. If this string does not start with the given string, nothing is done.

Parameters

deleteIfMatch The string to be deleted at the start.

Returns: *this to allow concatenated calls.

Definition at line 1653 of file tastring.inl.

◆ DeleteStart() [2/2]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK>

TAString & alib::strings::TAString< TChar, TAllocator >::DeleteStart ( integer regionLength )

inline

Deletes the given number of characters from the start of the string by moving the rest of the string to the start and adjusting the string's length.

Template Parameters

TCheck Defaults to CHK, which is the normal invocation mode. If <false> is added to the method name, no parameter checks are performed.

Parameters

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

Returns: *this to allow concatenated calls.

Definition at line 1624 of file tastring.inl.

◆ DetectLength()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

integer alib::strings::TAString< TChar, TAllocator >::DetectLength ( integer offset = 0 )

inline

Searches termination character '\0' and sets the corresponding length of the string. In debug-compilations, the detected length is smaller or equal to the buffer's capacity.

This method may be used in situations, where the strings's buffer is exposed to other libraries (for example, many operating system calls), which internally fill a given character buffer, zero-terminate it, but just do not return it's length.

Parameters

offset The offset for searching the termination byte '\0'. Defaults to 0. Using this parameter allows faster detection in the case a minimum length is known.

Returns: Returns the new length of this string for convenience.

Definition at line 720 of file tastring.inl.

◆ end() [1/2]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

iterator alib::strings::TAString< TChar, TAllocator >::end ( )

inline

Returns an iterator pointing behind this string.

Returns: The end of this string.

Definition at line 2005 of file tastring.inl.

◆ end() [2/2]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

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 1960 of file string.inl.

◆ EnsureRemainingCapacity()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

void alib::strings::TAString< TChar, TAllocator >::EnsureRemainingCapacity ( integer 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.

Definition at line 561 of file tastring.inl.

◆ GrowBufferAtLeastBy()

template<typename TChar, typename TAllocator>

void alib::strings::TAString< TChar, TAllocator >::GrowBufferAtLeastBy ( integer minimumGrowth )

Increases the allocation size by either 50% of the current capacity or by the value provided, whichever is higher.

Parameters

minimumGrowth The desired minimum growth of length.

Definition at line 80 of file tastringimpl.inl.

◆ HasInternalBuffer()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

bool alib::strings::TAString< TChar, TAllocator >::HasInternalBuffer ( ) const

inline

Returns true, if the buffer was allocated by this class itself. If the buffer was set using SetBuffer(TChar*,integer,integer,lang::Responsibility) with parameter responsibility given as Responsibility::KeepWithSender (and not automatically replaced, yet, because it became too small) then false is returned.

Note: Derived class LocalString will report false here. This sounds wrong on the first sight, as the buffer is allocated by an 'internal' member. But from an AString's perspective, class LocalString works on an 'external' buffer.

Returns: true if the buffer is internally allocated and will be deleted with the deletion of this object. False otherwise.

Definition at line 602 of file tastring.inl.

◆ InsertAt()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK>

TAString & alib::strings::TAString< TChar, TAllocator >::InsertAt	(	const TString< TChar > &	src,
		integer	pos )

inline

Inserts the given string at the given position. If the position is not between 0 and the length of the target, nothing is inserted. The latter is only asserted in case the template parameter TCheck is not set to NC.

Note: To insert a string with replacing a different one at the same time, use the method ReplaceSubstring". @tparam TCheck Chooses checking or non-checking implementation. Defaults to CHK.

Parameters

src	The String to insert.
pos	The position to insert src.

Returns: *this to allow concatenated calls.

Definition at line 1436 of file tastring.inl.

◆ InsertChars() [1/2]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK>

TAString & alib::strings::TAString< TChar, TAllocator >::InsertChars	(	TChar	c,
		integer	qty )

inline

Appends the given character c qty-times. The non-checking version does not check parameter qty to be greater than zero.

Template Parameters

TCheck Defaults to CHK, which chooses the checking version of the method.

Parameters

c	The character to insert qty times.
qty	The quantity of characters to insert.

Returns: *this to allow concatenated calls.

Definition at line 1504 of file tastring.inl.

◆ InsertChars() [2/2]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK>

TAString & alib::strings::TAString< TChar, TAllocator >::InsertChars	(	TChar	c,
		integer	qty,
		integer	pos )

inline

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

The non-checking version does not check the position to be in a valid range and the qty to be greater than zero.

Template Parameters

TCheck Defaults to CHK, which chooses the checking version of the method.

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.

Definition at line 1531 of file tastring.inl.

◆ InsertUninitialized()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK>

TAString & alib::strings::TAString< TChar, TAllocator >::InsertUninitialized	(	integer	pos,
		integer	size )

inline

Inserts the given number of uninitialized characters at the given position. If the position is not between 0 and the length of the target, nothing is inserted. The latter is only asserted in case the template parameter TCheck is not set to NC.

Note: The usage of other Insert-methods is preferred. This method is efficient in cases when the replacement consists of different parts and external assembly prior to the replacement should be avoided.

Template Parameters

TCheck Chooses checking or non-checking implementation. Defaults to CHK.

Parameters

pos	The position to insert src.
size	The number of characters to insert.

Returns: *this to allow concatenated calls.

Definition at line 1475 of file tastring.inl.

◆ NewLine()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

TAString & alib::strings::TAString< TChar, TAllocator >::NewLine ( )

inline

Appends platform-specific new line character(s) by appending literal string NEW_LINE.

Returns: *this to allow concatenated calls.

Definition at line 1229 of file tastring.inl.

◆ operator T()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename T>

alib::strings::TAString< TChar, TAllocator >::operator T ( ) const

constexpr

Templated implicit cast operator constructing an instance of type T from this string instance.

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. Deduced by the compiler.

Returns: A value of type T.

◆ operator+=()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TAppendable>

TAString & alib::strings::TAString< TChar, TAllocator >::operator+= ( const TAppendable & src )

inline

Alias to overloaded methods Append.
When this operator is used, template parameter TCheck of the Append-method called is set to CHK.

Note: According to the C++ idiom, this class is considered a container rather than a stream. Therefore, this operator is included for the sake of completeness and compatibiltiy with class std::string which (only!) defines this operator. However, the differences in operator associativity and precedence rules in C++ affect how operator+= behaves in chained expressions. Specifically, this operator is left-associative, meaning expressions are evaluated from left to right. As a result, chaining multiple += operations requires explicit parentheses to avoid compilation errors and ensure the correct evaluation order.; For example:
myString += "hello" += "world"; // Compilation error: parentheses are required

(myString += "hello") += "world"; // Correct.

myString << "hello" << "world"; // Correct without parentheses; Because operator<< typically expresses a streaming-like behavior, it avoids such ambiguity or precedence issues and is more straightforward for chaining multiple append operations. Hence, it is recommended to prefer << over += when performing multiple appends within a single expression.

Template Parameters

TAppendable The type of parameter source.

Parameters

src	The object of type T to append.

Returns: *this to allow concatenated calls.

Definition at line 1387 of file tastring.inl.

◆ operator<<()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TAppendable>

TAString & alib::strings::TAString< TChar, TAllocator >::operator<< ( const TAppendable & src )

inline

Alias to overloaded methods Append.
When this operator is used, template parameter TCheck of the Append-method called is set to CHK.

Template Parameters

TAppendable The type of parameter source.

Parameters

src	The object of type T to append.

Returns: *this to allow concatenated calls.

Definition at line 1353 of file tastring.inl.

◆ operator=()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

TAString & alib::strings::TAString< TChar, TAllocator >::operator= ( const TAString< TChar, TAllocator > & copy )

inline

Copy assign operator. If the given other AString is nulled, this object becomes nulled. Otherwise, this string is cleared and the given other string is appended.

See also: For details why no other assignment operators exists for this class, note paragraph Copy/Move Constructor and Assignment of this class's reference documentation.

Parameters

copy	The object to copy the contents from.

Returns: *this to allow concatenated calls.

Definition at line 464 of file tastring.inl.

◆ operator[]() [1/2]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

TChar & alib::strings::TAString< TChar, TAllocator >::operator[] ( integer idx )

inline

Provides read/write access to single characters. Overrides operator[] returning a reference to a TChar value, which allows changing the character stored.

Attention: No parameter check is performed (other than an assertions in debug-compilation of ALib). See String::operator[] for details.

Parameters

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

Returns: If the character contained (or, if lvalue the one to set).

Definition at line 678 of file tastring.inl.

◆ operator[]() [2/2]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

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 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 472 of file string.inl.

◆ pop_back()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

TChar alib::strings::TAString< TChar, TAllocator >::pop_back ( )

inlineconstexpr

Pops one character from the end of this string.
With debug-compilations, an assertion is raised in case this string is empty.

Returns: The character that got removed.

Definition at line 2023 of file tastring.inl.

◆ push_back()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

void alib::strings::TAString< TChar, TAllocator >::push_back ( TChar ch )

inlineconstexpr

Appends the given character to this AString.
Needed, for example, to make this type compatible with std::back_insert_iterator.

Parameters

ch	The character to append to the end of this string.

Definition at line 2018 of file tastring.inl.

◆ rbegin() [1/2]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

reverse_iterator alib::strings::TAString< TChar, TAllocator >::rbegin ( )

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 2009 of file tastring.inl.

◆ rbegin() [2/2]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

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 1968 of file string.inl.

◆ rend() [1/2]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

reverse_iterator alib::strings::TAString< TChar, TAllocator >::rend ( )

inline

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

Returns: The character before this string.

Definition at line 2013 of file tastring.inl.

◆ rend() [2/2]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

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 1972 of file string.inl.

◆ ReplaceRegion()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK>

TAString & alib::strings::TAString< TChar, TAllocator >::ReplaceRegion	(	TChar	c,
		integer	regionStart,
		integer	regionLength )

inline

Replaces a region in the string with the given character. The given region is adjusted to this string's bounds. If the adjusted region is empty, nothing is done.

The non-checking version does not adjust the region.

Template Parameters

TCheck Chooses checking or non-checking implementation. Defaults to CHK.

Parameters

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

Returns: *this to allow concatenated calls.

Definition at line 1837 of file tastring.inl.

◆ ReplaceSubstring()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK>

TAString & alib::strings::TAString< TChar, TAllocator >::ReplaceSubstring	(	const TString< TChar > &	src,
		integer	regionStart,
		integer	regionLength )

inline

Replaces a region in this object with a given string. The given region is adjusted to this string's bounds.

The non-checking version does not adjust the region and raises an ALib error in debug-compilations if the given region is out of bounds.

Template Parameters

TCheck Chooses checking or non-checking implementation. Defaults to CHK.

Parameters

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

Returns: *this to allow concatenated calls.

Definition at line 1786 of file tastring.inl.

◆ Reset() [1/2]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

TAString & alib::strings::TAString< TChar, TAllocator >::Reset ( )

inline

Sets the length of this string to zero. A nulled object remains nulled.

Returns: *this to allow concatenated calls.

Definition at line 1395 of file tastring.inl.

◆ Reset() [2/2]

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK, typename TAppendable>

TAString & alib::strings::TAString< TChar, TAllocator >::Reset ( const TAppendable & src )

inline

Sets the length of the string to zero and then invokes one of the overloaded methods Append.

Template Parameters

TCheck	Defaults to CHK, which is the normal invocation mode. The value is used with the invocation of method Append.
TAppendable	The type of parameter source.

Parameters

src	The source of type TAppendable to append.

Returns: *this to allow concatenated calls.

Definition at line 1407 of file tastring.inl.

◆ Reverse()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK>

TAString & alib::strings::TAString< TChar, TAllocator >::Reverse	(	integer	regionStart = 0,
		integer	regionLength = MAX_LEN )

inline

Reverses the order of the characters of this string (or a region hereof).

Parameters

regionStart	Start of the region to be reversed. Defaults to 0
regionLength	Length of the region to be reversed. Defaults to MAX_LEN.

Returns: *this to allow concatenated calls.

Definition at line 1961 of file tastring.inl.

◆ SearchAndReplace() [1/2]

template<typename TChar, typename TAllocator>

integer alib::strings::TAString< TChar, TAllocator >::SearchAndReplace	(	const TString< TChar > &	needle,
		const TString< TChar > &	replacement,
		integer	startIdx = 0,
		integer	maxReplacements = strings::MAX_LEN,
		lang::Case	sensitivity = lang::Case::Sensitive,
		integer	endIdx = strings::MAX_LEN )

Replaces up to maxReplacements occurrences of string needle found at or behind position startIdx by string replacement .

Parameters

needle	The string to be searched and replaced.
replacement	The replacement string.
startIdx	The index where the search starts. Optional and defaults 0.
maxReplacements	The maximum number of replacements to perform. Optional and defaults to MAX_LEN.
sensitivity	Case sensitivity of the comparison. Optional and defaults to Case::Sensitive.
endIdx	The index where the search ends. Precisely, the index of the first character that is not tested to be the start of replacement. Defaults to MAX_LEN.

Returns: The number of replacements that where performed.

Definition at line 373 of file tastringimpl.inl.

◆ SearchAndReplace() [2/2]

template<typename TChar, typename TAllocator>

integer alib::strings::TAString< TChar, TAllocator >::SearchAndReplace	(	TChar	needle,
		TChar	replacement,
		integer	startIdx = 0,
		integer	endIdx = strings::MAX_LEN )

Replaces all occurrences of character needle found at or behind position startIdx by character replacement.

Parameters

needle	The character to search.
replacement	The replacement character.
startIdx	The index where the search ends. Optional and defaults to `0`.
endIdx	The index where the search ends. Precisely, the index of the first character that is not replaced. Defaults to MAX_LEN.

Returns: The number of replacements that where performed.

Definition at line 346 of file tastringimpl.inl.

◆ SetBuffer() [1/2]

template<typename TChar, typename TAllocator>

void alib::strings::TAString< TChar, TAllocator >::SetBuffer ( integer newCapacity )

Resizes the 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 disposed and the object's state is nulled.
If the current buffer's life-cycle is managed externally (e.g., was set using SetBuffer(TChar*,integer,integer,lang::Responsibility) with parameter responsibility being Responsibility::KeepWithSender), this method will replace the buffer by a new one, even if the new requested size is the same as the external buffer's size. In other words, the only case when this method does not replace the current buffer is when the current buffer's life-cycle is (already) internally managed and it has the same size than what is requested.
In this C++ version of ALib, the true allocation size is one character larger than what is given with parameter newCapacity. This allows method Terminate to add a termination character without checking (and eventually reallocating and copying) an internally managed buffer.

Any method of this class that extends the length of the string will directly or indirectly invoke this method, when the current buffer size is not sufficient. If a future string length, which is the result of more than one concatenation of data to an AString is predictable, then it is advisable to reserve the allocated size before performing the planned concatenations, by invoking this method. This is to avoid unnecessary allocations and data copy operations.

If an external buffer is set, in debug-compilations a warning is raised, because usually it is not wanted that an external buffer becomes replaced during the growth of a string.
Such warnings can be switched off using the method DbgDisableBufferReplacementWarning. For example, in some situations it might be taken into account that instances of derived type LocalString sometimes may grow more than average and in such a case, a heap-allocated buffer replaces a local one. By placing a call to method DbgDisableBufferReplacementWarning, the code explicitly hints to that possibility and is well-readable. In release-compilations no warnings are issued and method DbgDisableBufferReplacementWarning is optimized out.

Parameters

newCapacity The new capacity of the internal buffer.

Definition at line 112 of file tastringimpl.inl.

◆ SetBuffer() [2/2]

template<typename TChar, typename TAllocator>

void alib::strings::TAString< TChar, TAllocator >::SetBuffer	(	TChar *	extBuffer,
		integer	extBufferSize,
		integer	extLength = 0,
		lang::Responsibility	responsibility = lang::Responsibility::KeepWithSender )

This method replaces the current buffer with the one provided.

The following rules apply:

If a nullptr is provided, the current buffer is released.
If the provided buffer is not nullptr, its size given with parameter extBufferSize has to be at least 1 for providing the space for a termination character.
After the operation, Capacity will report extBufferSize - 1.
Optional parameter responsibility can be used to pass the responsibility for the deletion of the buffer to this object.
The length of the content provided with parameter extLength must not exceed the value of parameter extBufferSize -1.
In no event any data of an existing buffer is copied into the new one. The rationale here is that in most use cases, this is not needed. Should this be desired, then the contents has to be copied "manually" before invoking this method.

The internal buffer allocation is performed with methods void * allocate(size_t&, size_t) , void * reallocate(void*, size_t, size_t&, size_t) and void free(void*, size_t) . The latter two are also used on external buffers that are provided with this method in case parameter responsibility is given as Responsibility::Transfer, because in this case such an externally created buffer is considered to have been allocated using the same instance of template type TAllocator. Consequently, it has to be ensured that the given piece of memory is "compatible" in this respect.

Parameters

extBuffer	The external buffer to use.
extBufferSize	The size of the given buffer.
extLength	The length of any content located in the given buffer that should be used. Has to be smaller or equal to extBufferSize -1 to preserve space for a trailing '\0'.
responsibility	If `Responsibility::Transfer`, the given buffer will be deleted by this object when a new buffer is set or it is deleted itself. Defaults to `Responsibility::KeepWithSender` which denotes that the life-cycle of the given external buffer is managed elsewhere.

Definition at line 242 of file tastringimpl.inl.

◆ SetCharAt()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK>

void alib::strings::TAString< TChar, TAllocator >::SetCharAt	(	integer	idx,
		TChar	c )

inline

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

Note: The C++ language would allow to declare this method const, as it does not manipulate the data of the class itself but a character in the buffer pointer.
In exceptional cases, to manipulate the contents of const AString, use method VBuffer() like in the following sample:
const AString myAString( "Hello" );

// this would not compile because AString::SetCharAt() is not declared const....

//myAString.SetCharAt( 1, 'e' );

// ...but method VBuffer() is declared const.

myAString.VBuffer()[1]= 'e';

Template Parameters

TCheck Performs a range check on the given index and a check for illegal setting of termination character '\0' anywhere else but at idx==length.

Parameters

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

Definition at line 655 of file tastring.inl.

◆ SetLength()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

void alib::strings::TAString< TChar, TAllocator >::SetLength ( integer newLength )

inline

Sets a new length for this string.

In debug-compilations, given newLength is checked to be positive and smaller or equal to the buffer's capacity.

In the (frequent) situation that the given length is shorter (or equal) to the current length, for better readability, the use of the method ShortenTo instead of this method is recommended. Extending the length of the string should be done only in rare cases, when the string buffer was modified "externally" after retrieving it using VBuffer.

Parameters

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

Definition at line 699 of file tastring.inl.

◆ SetNull()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

void alib::strings::TAString< TChar, TAllocator >::SetNull ( )

inline

Invokes SetBuffer(0).

Definition at line 605 of file tastring.inl.

◆ ShortenBy()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

TAString & alib::strings::TAString< TChar, TAllocator >::ShortenBy ( integer charsToRemove )

inline

Same as ShortenTo, but accepts a value interpreted as the difference to the current length.

Parameters

charsToRemove The number of characters to remove.

Returns: *this to allow concatenated calls.

Definition at line 765 of file tastring.inl.

◆ ShortenTo()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

TAString & alib::strings::TAString< TChar, TAllocator >::ShortenTo ( integer newLength )

inline

Sets the length of the string to a shorter (or equal) value.

In release-compilations, this method has the same simple inline implementation as SetLength, it just sets the internal field length to the given value. The reason for the method's existence is primarily readability of the code: The name expresses that the given newLength is shorter than the current length.

In debug-compilations, an error is raised if the length provided is longer than the current length. An equal value is accepted.

In situations when it is sure that a new length is equal or shorter to the existing one, the use of this method is recommended over the use of SetLength. This is especially true for the frequent use case where a "base string" should be restored after one or more concatenations had been performed.

Parameters

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

Returns: *this to allow concatenated calls.

Definition at line 747 of file tastring.inl.

◆ Terminate()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

const TChar * alib::strings::TAString< TChar, TAllocator >::Terminate ( ) const

inlineconstexpr

Writes a zero-termination character '\0' to the end of the used part of the internal string buffer and returns the pointer to the start. In other words, this function returns the represented string as a "cstring".

One implementation detail of this class is that it always ensures that the internal buffer's capacity is sufficient for a termination character. This way, using this method will not reallocate the string and the method can be invoked on constant objects.

The explicit invocation of this method can often be omitted, due to the availability of the definition of an implicit cast operator to const TChar, which inlines a call to this method.

Returns: The pointer to the zero-terminated character buffer.

Definition at line 620 of file tastring.inl.

◆ ToLower()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK>

TAString & alib::strings::TAString< TChar, TAllocator >::ToLower	(	integer	regionStart = 0,
		integer	regionLength = MAX_LEN )

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 MAX_LEN.

Returns: *this to allow concatenated calls.

Definition at line 1935 of file tastring.inl.

◆ ToUpper()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

template<typename TCheck = CHK>

TAString & alib::strings::TAString< TChar, TAllocator >::ToUpper	(	integer	regionStart = 0,
		integer	regionLength = MAX_LEN )

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 MAX_LEN.

Returns: *this to allow concatenated calls.

Definition at line 1908 of file tastring.inl.

◆ Trim()

template<typename TChar, typename TAllocator>

TAString< TChar, TAllocator > & alib::strings::TAString< TChar, TAllocator >::Trim ( const TCString< TChar > & trimChars = CStringConstantsTraits<TChar>::DefaultWhitespaces() )

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

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

Parameters

trimChars Pointer to a zero-terminated set of characters to be omitted. Defaults to DEFAULT_WHITESPACES.

Returns: *this to allow concatenated calls.

Definition at line 324 of file tastringimpl.inl.

◆ TrimAt()

template<typename TChar, typename TAllocator>

integer alib::strings::TAString< TChar, TAllocator >::TrimAt	(	integer	idx,
		const TCString< TChar > &	trimChars = CStringConstantsTraits<TChar>::DefaultWhitespaces() )

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 idx given, this value can only be smaller or equal to idx. If idx 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 DEFAULT_WHITESPACES.

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

Definition at line 301 of file tastringimpl.inl.

◆ TrimEnd()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

TAString & alib::strings::TAString< TChar, TAllocator >::TrimEnd ( const TCString< TChar > & trimChars = CStringConstantsTraits<TChar>::DefaultWhitespaces() )

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 Pointer to a zero-terminated set of characters to be omitted. Defaults to DEFAULT_WHITESPACES.

Returns: *this to allow concatenated calls.

Definition at line 1759 of file tastring.inl.

◆ TrimStart()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

TAString & alib::strings::TAString< TChar, TAllocator >::TrimStart ( const TCString< TChar > & trimChars = CStringConstantsTraits<TChar>::DefaultWhitespaces() )

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 Pointer to a zero-terminated set of characters to be omitted. Defaults to DEFAULT_WHITESPACES.

Returns: *this to allow concatenated calls.

Definition at line 1738 of file tastring.inl.

◆ VBuffer()

template<typename TChar, typename TAllocator = lang::HeapAllocator>

TChar * alib::strings::TAString< TChar, TAllocator >::VBuffer ( ) const

inline

The internal buffer character array provided as non constant character pointer.

See also: Chapter Write Access to the Buffer of the reference documentation of this class.

Returns: The internal buffer array.

Definition at line 637 of file tastring.inl.

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

Description:

Public Type Index:

Public Method Index:

Protected Type Index:

Protected Field Index:

Protected Method Index:

Type Definition Details:

◆ AllocatorType

◆ allocBase

◆ base

◆ iterator

◆ reverse_iterator

Field Details:

◆ capacity

◆ dbgWarnWhenExternalBufferIsReplaced

◆ debugLastAllocRequest

Constructor(s) / Destructor Details:

◆ TAString() [1/7]

◆ TAString() [2/7]

◆ TAString() [3/7]

◆ TAString() [4/7]

◆ TAString() [5/7]

◆ TAString() [6/7]

◆ TAString() [7/7]

◆ ~TAString()

Method Details:

◆ _() [1/3]

◆ _() [2/3]

◆ _() [3/3]

◆ Append() [1/7]

◆ Append() [2/7]

◆ Append() [3/7]

◆ Append() [4/7]

◆ Append() [5/7]

◆ Append() [6/7]

◆ Append() [7/7]

◆ begin() [1/2]

◆ begin() [2/2]

◆ Capacity()

◆ dbgCheck()

◆ DbgDisableBufferReplacementWarning()

◆ Delete()

◆ DeleteEnd() [1/2]

◆ DeleteEnd() [2/2]

◆ DeleteStart() [1/2]

◆ DeleteStart() [2/2]

◆ DetectLength()

◆ end() [1/2]

◆ end() [2/2]

◆ EnsureRemainingCapacity()

◆ GrowBufferAtLeastBy()

◆ HasInternalBuffer()

◆ InsertAt()

◆ InsertChars() [1/2]

◆ InsertChars() [2/2]

◆ InsertUninitialized()

◆ NewLine()

◆ operator T()

◆ operator+=()

◆ operator<<()

◆ operator=()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ pop_back()

◆ push_back()

◆ rbegin() [1/2]

◆ rbegin() [2/2]

◆ rend() [1/2]

◆ rend() [2/2]

◆ ReplaceRegion()

◆ ReplaceSubstring()

◆ Reset() [1/2]

◆ Reset() [2/2]

◆ Reverse()

◆ SearchAndReplace() [1/2]

◆ SearchAndReplace() [2/2]

◆ SetBuffer() [1/2]

◆ SetBuffer() [2/2]

◆ SetCharAt()

◆ SetLength()