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 on the in an allocator instead of being a local variable on the stack, still some performance improvements apply, because 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 to foresee a maximum buffer size, the warning has to be disabled by invoking DbgDisableBufferReplacementWarning.

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

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 66 of file localstring.hpp.

#include <localstring.hpp>

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

[legend]

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

[legend]

Public Method Index:
constexpr	TLocalString ()

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

	TLocalString (const TLocalString &copy)

constexpr	TLocalString (TAllocator &pAllocator)

	TLocalString (TLocalString &&move) noexcept

TLocalString &	operator= (const TLocalString &copy)

TLocalString &	operator= (TLocalString &&move)

Public Method Index: inherited from 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.

	operator TCharArray () const

	operator TCharArray () const

TAString &	operator= (const TAString &copy)

void	dbgCheck () const

void	DbgDisableBufferReplacementWarning ()

ALIB_API void	SetBuffer (integer newCapacity)

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

void	EnsureRemainingCapacity (integer spaceNeeded)

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

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 &	_ (const TString< TChar > &src, integer regionStart, integer regionLength=MAX_LEN)

TAString &	_ (const TAppendable &src)

TAString &	NewLine ()

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_API TAString &	Trim (const TCString< TChar > &trimChars=TT_CStringConstants< TChar >::DefaultWhitespaces())

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

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

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

Iterator	begin ()

Iterator	end ()

ALIB_WARNINGS_RESTORE ReverseIterator	rbegin ()

ReverseIterator	rend ()

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

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

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

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

ConstIterator	begin () const

ALIB_WARNINGS_ALLOW_UNSAFE_BUFFER_USAGE ConstIterator	end () const

ALIB_WARNINGS_RESTORE ConstReverseIterator	rbegin () const

ConstReverseIterator	rend () const

Public Method Index: inherited from TString< TChar >
constexpr	TString () noexcept=default
	Defaulted default constructor.

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

template<typename TCharArray >
constexpr	TString (const TCharArray &src)

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

	TString (ConstIterator &start, ConstIterator &end)

template<typename TAllocator , typename TEnableIf = typename TAllocator::ChainedAllocator>
	TString (TAllocator &allocator, const TString< TChar > &copy)

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

template<typename TCharArray >
	operator TCharArray () const

template<typename TCharArray >
	operator TCharArray () const

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

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>
ALIB_WARNINGS_ALLOW_UNSAFE_BUFFER_USAGE integer	IndexOfOrLength (TChar needle, integer startIdx) const

template<typename TCheck = CHK>
ALIB_WARNINGS_RESTORE 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_API uint64_t	ParseDecDigits (integer startIdx=0, integer *newIdx=nullptr) const

ALIB_API 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_API 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_API 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_API 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_API 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_API 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 >
void	Allocate (TAllocator &allocator, const TString< TChar > &copy)

template<typename TAllocator >
void	Free (TAllocator &allocator)

ConstIterator	begin () const

ConstIterator	cbegin () const

ALIB_WARNINGS_ALLOW_UNSAFE_BUFFER_USAGE ConstIterator	end () const

ConstIterator	cend () const

ALIB_WARNINGS_RESTORE ConstReverseIterator	rbegin () const

ConstReverseIterator	rend () const

ConstReverseIterator	crbegin () const

ConstReverseIterator	crend () const

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

Public Method Index: inherited from 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 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 TAString< TChar, lang::HeapAllocator >
integer	capacity

bool	dbgWarnWhenExternalBufferIsReplaced

integer	debugLastAllocRequest

Protected Field Index: inherited from TString< TChar >
const TChar *	buffer

integer	length

Protected Field Index: inherited from AllocatorMember< lang::HeapAllocator >
lang::HeapAllocator &	allocator
	A reference to the allocator.

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

using	Iterator

using	ReverseIterator
	Same as Iterator, but working from the end to the start of the string.

Public Type Index: inherited from TString< TChar >
using	CharType = TChar
	Expose template parameter TChar to the outer world.

using	ConstIterator = TRandomAccessIterator<const TChar>

using	ConstReverseIterator = std::reverse_iterator<ConstIterator>

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

Protected Method Index: inherited from TAString< TChar, lang::HeapAllocator >
constexpr	TAString (lang::HeapAllocator &pAllocator, TChar *extBuffer, integer extBufferSize)

constexpr	TAString (TChar *extBuffer, integer extBufferSize)

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

Type Definition Details:

◆ base

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

using base = TAString<TChar, TAllocator>

protected

The base AString-type.

Definition at line 73 of file localstring.hpp.

◆ sBase

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

using sBase = TString<TChar>

protected

The base String-type.

Definition at line 76 of file localstring.hpp.

Field Details:

◆ localBuffer

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

TChar 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 80 of file localstring.hpp.

Constructor(s) / Destructor Details:

◆ TLocalString() [1/5]

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

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 94 of file localstring.hpp.

◆ TLocalString() [2/5]

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

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 106 of file localstring.hpp.

◆ TLocalString() [3/5]

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

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 115 of file localstring.hpp.

Here is the call graph for this function:

◆ TLocalString() [4/5]

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

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 128 of file localstring.hpp.

Here is the call graph for this function:

◆ TLocalString() [5/5]

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

template<class TAppendable >

TLocalString ( const TAppendable & src )

inline

Constructs this instance and invokes parent's method Append to create a string representation of 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 T_Append.

Parameters

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

Definition at line 234 of file localstring.hpp.

Here is the call graph for this function:

Method Details:

◆ operator=() [1/2]

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

TLocalString & 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 166 of file localstring.hpp.

Here is the call graph for this function:

◆ operator=() [2/2]

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

TLocalString & 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 184 of file localstring.hpp.

Here is the call graph for this function:

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

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/2]

◆ operator=() [2/2]