Description:

template<typename TChar, integer TCapacity, typename TAllocator = lang::HeapAllocator>
class alib::strings::TLocalString< TChar, TCapacity, TAllocator >

This type specializes class AString by adding a character array member of templated size which is used as the "external" string buffer. The single motivation for the use of this class is performance optimization.

Assembled character strings often have a rather short lifetime and are disposed quickly after their usage. If the maximum length of the assembled string is known, such strings may be created as local values of this type, with that maximum length given as template parameter TCapacity. With that, the allocation and de-allocation of heap memory (or whatever is used with the provided allocator) for the string is omitted and allocation and destruction of the local string is performed in constant time O(1).

But even if an instance of this class is allocated (instead of being a local variable on the stack), in common cases, still a performance improvement applies. This is due to the fact that besides the class object itself, no second memory allocation for the string buffer is performed.

If during the use of an instance of this class the buffer's fixed TCapacity is exceeded, a new buffer is allocated from the given allocator, just as it is always done with growing strings managed in AString objects. This means, the use of this class is safe and no restrictions apply. Of course, if possible, for performance-critical code sections, the predefined size TCapacity should be chosen large enough to allow the internal buffer to survive the use.
With debug-builds of ALib, parent class AString optionally (and by default) raises a warning if an external buffer is replaced by a new (heap) allocation. (Note that from an AString perspective, this class's internal field buffer is an external character array). With use cases that do not allow foreseeing a maximum buffer size, the warning has to be disabled by invoking DbgDisableBufferReplacementWarning.

For more information on warnings, see AString::SetBuffer.

With the provision of an assignment operator, the explicit restriction of parent class to not allow assignments is lifted with this type.

Note

For commonly used sizes and character types, some convenient typedefs exists in namespace alib, which use HeapAllocator. These type definitions are:

String8, String16, String32 ... String1K, String2K, String4K,
NString8, NString16, NString32 ... NString1K, NString2K, NString4K, and
WString8, WString16, WString32 ... WString1K, WString2K, WString4K.

Template Parameters

TChar	The character type of this string. Alias names for specializations of this class are provided in namespace alib with type definitions LocalString<TCapacity>, NLocalString<TCapacity>, WLocalString<TCapacity>, XLocalString<TCapacity>, ComplementLocalString<TCapacity> and StrangeLocalString<TCapacity>.
TCapacity	The capacity of the string buffer allocated locally "inside" the class.
TAllocator	The allocator type to use. Defaults to HeapAllocator.

Definition at line 63 of file localstring.inl.

Inheritance diagram for alib::strings::TLocalString< TChar, TCapacity, TAllocator >:

[legend]

Collaboration diagram for alib::strings::TLocalString< TChar, TCapacity, TAllocator >:

[legend]

Public Method Index:
constexpr	TLocalString ()

template<typename TAppendable>
	TLocalString (const TAppendable &src)

	TLocalString (const TLocalString &copy)

constexpr	TLocalString (TAllocator &pAllocator)

	TLocalString (TLocalString &&move) noexcept

template<typename TAppendable>
TLocalString &	operator= (const TAppendable &src)

TLocalString &	operator= (const TLocalString &copy)

TLocalString &	operator= (TLocalString &&move)

Public Method Index: inherited from alib::strings::TAString< TChar, lang::HeapAllocator >
constexpr	TAString ()
	Constructs an empty, nulled AString (does not allocate a buffer).

	TAString (const TAppendable &src)

	TAString (const TAString &copy)

constexpr	TAString (lang::HeapAllocator &pAllocator)

	TAString (TAString &&move) noexcept

	~TAString () noexcept
	Destructs an AString object. An internally allocated buffer will be deleted.

const_iterator	begin () const

const_iterator	end () const

constexpr	operator T () const

constexpr	operator T () const

constexpr	operator T () const

constexpr	operator T () const

TAString &	operator= (const TAString &copy)

TChar	operator[] (integer idx) const

const_reverse_iterator	rbegin () const

const_reverse_iterator	rend () const

void	dbgCheck () const

void	DbgDisableBufferReplacementWarning ()

ALIB_DLL void	SetBuffer (integer newCapacity)

ALIB_DLL void	SetBuffer (TChar *extBuffer, integer extBufferSize, integer extLength=0, lang::Responsibility responsibility=lang::Responsibility::KeepWithSender)

void	EnsureRemainingCapacity (integer spaceNeeded)

ALIB_DLL void	GrowBufferAtLeastBy (integer minimumGrowth)

integer	Capacity () const

bool	HasInternalBuffer () const

void	SetNull ()
	Invokes SetBuffer(0).

constexpr const TChar *	Terminate () const

TChar *	VBuffer () const

void	SetCharAt (integer idx, TChar c)

TChar &	operator[] (integer idx)

TChar	operator[] (integer idx) const

void	SetLength (integer newLength)

void	DetectLength ()

TAString &	ShortenTo (integer newLength)

TAString &	Append (const TCharSrc *src, integer srcLength)

TAString &	Append (const TChar *src, integer srcLength)

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

TAString &	Append (const TAppendable &src)

TAString &	Append (const TStringSource &src)

TAString &	Append (TChar src)

TAString &	Append (characters::IsCharacter auto src)

TAString &	NewLine ()

TAString &	_ (const TAppendable &src)

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

TAString &	operator<< (const TAppendable &src)

TAString &	operator+= (const TAppendable &src)

TAString &	_ ()

TAString &	Reset ()

TAString &	Reset (const TAppendable &src)

TAString &	InsertAt (const TString< TChar > &src, integer pos)

TAString &	InsertChars (TChar c, integer qty)

TAString &	InsertChars (TChar c, integer qty, integer pos)

TAString &	Delete (integer regionStart, integer regionLength=MAX_LEN)

TAString &	DeleteStart (integer regionLength)

TAString &	DeleteStart (const TString< TChar > &deleteIfMatch)

TAString &	DeleteEnd (integer regionLength)

TAString &	DeleteEnd (const TString< TChar > &deleteIfMatch)

ALIB_DLL TAString &	Trim (const TCString< TChar > &trimChars=CStringConstantsTraits< TChar >::DefaultWhitespaces())

ALIB_DLL integer	TrimAt (integer idx, const TCString< TChar > &trimChars=CStringConstantsTraits< TChar >::DefaultWhitespaces())

TAString &	TrimStart (const TCString< TChar > &trimChars=CStringConstantsTraits< TChar >::DefaultWhitespaces())

TAString &	TrimEnd (const TCString< TChar > &trimChars=CStringConstantsTraits< TChar >::DefaultWhitespaces())

iterator	begin ()

iterator	end ()

reverse_iterator	rbegin ()

reverse_iterator	rend ()

constexpr void	push_back (TChar ch)

constexpr TChar	pop_back ()

TAString &	ReplaceSubstring (const TString< TChar > &src, integer regionStart, integer regionLength)

TAString &	ReplaceRegion (TChar c, integer regionStart, integer regionLength)

ALIB_DLL integer	SearchAndReplace (TChar needle, TChar replacement, integer startIdx=0, integer endIdx=strings::MAX_LEN)

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

TAString &	ToUpper (integer regionStart=0, integer regionLength=MAX_LEN)

TAString &	ToLower (integer regionStart=0, integer regionLength=MAX_LEN)

TAString &	Reverse (integer regionStart=0, integer regionLength=MAX_LEN)

const_iterator	begin () const

const_iterator	end () const

const_reverse_iterator	rbegin () const

const_reverse_iterator	rend () const

Public Method Index: inherited from alib::strings::TString< TChar >
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

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

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

std::size_t	Hashcode () const

std::size_t	HashcodeIgnoreCase () const

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

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

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

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)

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

bool	AdjustRegion (integer &regionStart, integer &regionLength) const

Public Method Index: inherited from alib::lang::AllocatorMember< lang::HeapAllocator >
	AllocatorMember ()=delete
	Deleted default constructor. (The allocator has to be given with construction)

	AllocatorMember (lang::HeapAllocator &pAllocator) noexcept

AllocatorInterface< lang::HeapAllocator >	AI () const noexcept

lang::HeapAllocator &	GetAllocator () const noexcept

Protected Type Index:
using	base = TAString<TChar, TAllocator>
	The base AString-type.

using	sBase = TString<TChar>
	The base String-type.

Protected Type Index: inherited from alib::strings::TAString< TChar, lang::HeapAllocator >
using	allocBase
	The allocator type that TAllocator specifies.

using	base
	The base string-type.

Protected Field Index:
TChar	localBuffer [TCapacity]

Protected Field Index: inherited from alib::strings::TAString< TChar, lang::HeapAllocator >
integer	capacity

bool	dbgWarnWhenExternalBufferIsReplaced

integer	debugLastAllocRequest

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
	A reference to the allocator.

Additional Inherited Members
Public Type Index: inherited from alib::strings::TAString< TChar, lang::HeapAllocator >
using	AllocatorType
	Exposes the allocator type specified by template parameter TAllocator.

using	iterator

using	reverse_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	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.

using	const_iterator = TRandomAccessIterator<const TChar>

using	const_reverse_iterator = std::reverse_iterator<const_iterator>

Public Type Index: inherited from alib::lang::AllocatorMember< lang::HeapAllocator >
using	AllocatorType
	Exposes the allocator type.

Protected Method Index: inherited from alib::strings::TAString< TChar, lang::HeapAllocator >
constexpr	TAString (lang::HeapAllocator &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>
ALIB_DLL integer	indexOfString (const TString &needle, integer startIdx, integer endIdx) const

Type Definition Details:

◆ base

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

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

protected

The base AString-type.

Definition at line 70 of file localstring.inl.

◆ sBase

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

using alib::strings::TLocalString< TChar, TCapacity, TAllocator >::sBase = TString<TChar>

protected

The base String-type.

Definition at line 73 of file localstring.inl.

Field Details:

◆ localBuffer

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

TChar alib::strings::TLocalString< TChar, TCapacity, TAllocator >::localBuffer[TCapacity]

protected

The internal buffer with size specified by the template parameter TCapacity. Passed as an external buffer to parent class AString.

Definition at line 77 of file localstring.inl.

Constructor(s) / Destructor Details:

◆ TLocalString() [1/5]

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

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

inlineconstexpr

Constructs an empty LocalString. Inherited field buffer will be set as an the external buffer of parent AString. Unlike all other ALib string classes, objects of this type are not nulled after default construction.

Parameters

pAllocator The allocator to use.

Definition at line 91 of file localstring.inl.

◆ TLocalString() [2/5]

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

alib::strings::TLocalString< TChar, TCapacity, TAllocator >::TLocalString ( )

inlineconstexpr

Constructs an empty LocalString. Inherited field buffer will be set as an the external buffer of parent AString. Unlike all other ALib string classes, objects of this type are not nulled after default construction.

Definition at line 103 of file localstring.inl.

◆ TLocalString() [3/5]

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

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

inline

Copy constructor. Copies the string data of parameter copy to this instance

Parameters

copy	The object to copy the contents from.

Definition at line 112 of file localstring.inl.

◆ TLocalString() [4/5]

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

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

inlinenoexcept

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

Parameters

move	The object to move.

Definition at line 125 of file localstring.inl.

◆ TLocalString() [5/5]

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

template<typename TAppendable>

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

inline

Constructs this instance and invokes parent's method Append to create a string representation of the given "appendable" object src.

See also: Manual chapter 5.1 Appending Custom Types for more information about which types are supported and how external, user-defined types can be made compatible to this implicit constructor.

Template Parameters

TAppendable The type of parameter src that has a specialization of functor AppendableTraits.

Parameters

src	The source to take the buffer and length from of template type T.

Definition at line 231 of file localstring.inl.

Method Details:

◆ operator=() [1/3]

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

template<typename TAppendable>

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

inline

Assign operator. Invokes inherited method Reset(const TAppendable&).

Template Parameters

TAppendable The type of parameter source.

Parameters

src	The source of type TAppendable to append.

Returns: *this to allow concatenated calls.

Definition at line 248 of file localstring.inl.

◆ operator=() [2/3]

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

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

inline

Copy assign operator. Copies the contents of the given object copy.

Parameters

copy	The object to copy the contents from.

Returns: *this to allow concatenated calls.

Definition at line 163 of file localstring.inl.

◆ operator=() [3/3]

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

TLocalString & alib::strings::TLocalString< TChar, TCapacity, TAllocator >::operator= ( TLocalString< TChar, TCapacity, TAllocator > && move )

inline

Move assign operator. Copies the contents of the given object copy.

Parameters

move	The object to move the contents from.

Returns: *this to allow concatenated calls.

Definition at line 181 of file localstring.inl.

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

localstring.inl

Description:

Public Method Index:

Protected Type Index:

Protected Field Index:

Additional Inherited Members

Type Definition Details:

◆ base

◆ sBase

Field Details:

◆ localBuffer

Constructor(s) / Destructor Details:

◆ TLocalString() [1/5]

◆ TLocalString() [2/5]

◆ TLocalString() [3/5]

◆ TLocalString() [4/5]

◆ TLocalString() [5/5]

Method Details:

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]