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:
Method SetBuffer provides a boolean parameter that also allows leting an object of this class take control on 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 than 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 AppendableTraits.
The concept is described in detail with chapter 5.1 Appending Custom Types of this module's Programmer's Manual.
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, as prototyped with Allocator. |
Definition at line 173 of file tastring.inl.
Public Type Index: | |
using | AllocatorType = TAllocator |
Exposes the allocator type specified by template parameter TAllocator. | |
![]() | |
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> |
![]() | |
using | AllocatorType = TAllocator |
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 ©) | |
constexpr | TAString (TAllocator &pAllocator) |
TAString (TAString &&move) noexcept | |
~TAString () noexcept | |
Destructs an AString object. An internally allocated buffer will be deleted. | |
template<typename T> requires ( alib::characters::IsImplicitArrayCast<T, TChar> && !alib::strings::NoAutoCastTraits< TAString<TChar,TAllocator>, characters::Policy::Implicit, std::remove_cv_t<T> >::value) | |
constexpr | operator T () const |
template<typename T> requires ( alib::characters::IsExplicitArrayCast <T, TChar> && !alib::characters::IsImplicitZTArrayCast<T, TChar> && !alib::strings::NoAutoCastTraits< TAString<TChar,TAllocator>, characters::Policy::ExplicitOnly, std::remove_cv_t<T> >::value ) | |
constexpr | operator T () const |
template<typename T> requires ( !alib::characters::IsImplicitArrayCast <T, TChar> && alib::characters::IsImplicitZTArrayCast<T, TChar> && !alib::strings::NoAutoCastTraits< TAString<TChar,TAllocator>, characters::Policy::Implicit, std::remove_cv_t<T> >::value ) | |
constexpr | operator T () const |
template<typename T> requires ( !alib::characters::IsExplicitArrayCast <T, TChar> && alib::characters::IsExplicitZTArrayCast<T, TChar> && !alib::strings::NoAutoCastTraits< TAString<TChar,TAllocator>, characters::Policy::ExplicitOnly, std::remove_cv_t<T> >::value ) | |
constexpr | operator T () const |
TAString & | operator= (const TAString ©) |
Debug Features | |
void | dbgCheck () const |
void | DbgDisableBufferReplacementWarning () |
Memory allocation and buffer access | |
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 |
Writable Buffer Access | |
TChar * | VBuffer () const |
template<typename TCheck = CHK> | |
void | SetCharAt (integer idx, TChar c) |
TChar & | operator[] (integer idx) |
void | SetLength (integer newLength) |
void | DetectLength () |
TAString & | ShortenTo (integer newLength) |
TChar | operator[] (integer idx) const |
Append-Methods | |
template<typename TCheck = CHK, typename TCharSrc> requires ( characters::IsCharacter<TCharSrc> && !std::same_as<TCharSrc,TChar> ) | |
TAString & | Append (const TCharSrc *src, integer srcLength) |
template<typename TCheck = CHK> | |
TAString & | Append (const TChar *src, integer srcLength) |
template<typename TCheck = CHK> | |
TAString & | Append (const TString< TChar > &src, integer regionStart, integer regionLength=MAX_LEN) |
template<typename TCheck = CHK, typename TAppendable> requires alib::strings::IsAppendable<TAppendable, TChar,TAllocator> | |
TAString & | Append (const TAppendable &src) |
template<typename TCheck = CHK, typename TStringSource> requires ( alib::characters::IsImplicitZTArraySource<TStringSource, characters::ZTType<TStringSource>> || alib::characters::IsImplicitArraySource <TStringSource, characters::Type<TStringSource>> ) | |
TAString & | Append (const TStringSource &src) |
TAString & | NewLine () |
template<typename TCheck = CHK> | |
TAString & | Append (TChar src) |
template<typename TCheck = CHK> | |
TAString & | Append (characters::IsCharacter auto src) |
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 TAppendable> | |
TAString & | operator<< (const TAppendable &src) |
template<typename TAppendable> | |
TAString & | operator+= (const TAppendable &src) |
Insert and Delete | |
TAString & | Reset () |
template<typename TCheck = CHK, typename TAppendable> | |
TAString & | Reset (const TAppendable &src) |
TAString & | _ () |
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 & | Delete (integer regionStart, integer regionLength=MAX_LEN) |
template<typename TCheck = CHK> | |
TAString & | DeleteStart (integer regionLength) |
TAString & | DeleteStart (const TString< TChar > &deleteIfMatch) |
template<typename TCheck = CHK> | |
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()) |
std::iterator_traits | |
iterator | begin () |
iterator | end () |
reverse_iterator | rbegin () |
reverse_iterator | rend () |
constexpr void | push_back (TChar ch) |
constexpr TChar | pop_back () |
![]() | |
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 > ©) | |
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 > ©) |
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 ®ionStart, integer ®ionLength) const |
![]() | |
AllocatorMember ()=delete | |
Deleted default constructor. (The allocator has to be given with construction) | |
AllocatorMember (TAllocator &pAllocator) noexcept | |
AllocatorInterface< TAllocator > | AI () const noexcept |
TAllocator & | GetAllocator () const noexcept |
Protected Type Index: | |
using | allocBase = lang::AllocatorMember<TAllocator> |
The allocator type that TAllocator specifies. | |
using | base = TString<TChar> |
The base string-type. | |
Protected Field Index: | |
integer | capacity |
bool | dbgWarnWhenExternalBufferIsReplaced = true |
integer | debugLastAllocRequest =0 |
![]() | |
const TChar * | buffer |
integer | length |
![]() | |
TAllocator & | allocator |
A reference to the allocator. | |
Protected Method Index: | |
constexpr | TAString (TAllocator &pAllocator, TChar *extBuffer, integer extBufferSize) |
constexpr | TAString (TChar *extBuffer, integer extBufferSize) |
![]() | |
template<lang::Case TSensitivity = lang::Case::Sensitive> | |
ALIB_DLL integer | indexOfString (const TString &needle, integer startIdx, integer endIdx) const |
using alib::strings::TAString< TChar, TAllocator >::AllocatorType = TAllocator |
Exposes the allocator type specified by template parameter TAllocator.
Definition at line 305 of file tastring.inl.
|
protected |
The allocator type that TAllocator specifies.
Definition at line 184 of file tastring.inl.
|
protected |
The base string-type.
Definition at line 181 of file tastring.inl.
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 2115 of file tastring.inl.
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 2118 of file tastring.inl.
|
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 191 of file tastring.inl.
|
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.
Definition at line 230 of file tastring.inl.
|
protected |
Used to check if previous grow request was exactly what is now the length.
This field is available only if code selection symbol ALIB_DEBUG_STRINGS is set.
Definition at line 199 of file tastring.inl.
|
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.
pAllocator | The allocator to use. |
extBuffer | The external buffer to use. |
extBufferSize | The capacity of the given buffer. |
Definition at line 271 of file tastring.inl.
|
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.
extBuffer | The external buffer to use. |
extBufferSize | The capacity of the given buffer. |
Definition at line 295 of file tastring.inl.
|
inlineexplicitconstexpr |
Constructs an empty, nulled AString (does not allocate a buffer).
Definition at line 311 of file tastring.inl.
|
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.
pAllocator | The allocator to use. |
Definition at line 322 of file tastring.inl.
|
inlineexplicit |
Copy constructor that allocates memory and copies the contents of the given object.
copy | The object to copy. |
Definition at line 330 of file tastring.inl.
|
inlinenoexcept |
Move constructor. See Copy/Move Constructor and Assignment for details.
move | The object to move. |
Definition at line 343 of file tastring.inl.
|
inlineexplicit |
Constructs the object and uses Append to create a string representation of the given object.
TAppendable | The type of parameter source that has a specialization of functor AppendableTraits. |
src | The source object to append to this string. |
Definition at line 385 of file tastring.inl.
|
inlinenoexcept |
Destructs an AString object. An internally allocated buffer will be deleted.
Definition at line 393 of file tastring.inl.
|
inline |
Sets the length of the string to zero. Same as method Reset. Provided for compatibility with C# and Java versions of ALib.
*this
to allow concatenated calls. Definition at line 1532 of file tastring.inl.
|
inline |
Alias to overloaded methods Append.
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. |
src | The source object to append a string representation for. |
*this
to allow concatenated calls. Definition at line 1441 of file tastring.inl.
|
inline |
Alias method of Append(const TString<TChar>&, integer, integer).
Provided for compatibility with C# and Java versions of ALib.
TCheck | Chooses checking or non-checking implementation. Defaults to CHK. |
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 |
*this
to allow concatenated calls. Definition at line 1455 of file tastring.inl.
|
inline |
Appends a single character of a different type. If this string is narrow, the given character is UTF-8 encoded.
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 . |
src | The character value to append. Only values of types that satisfy the concept IsCharacter are accepted. |
*this
to allow concatenated calls. Definition at line 1378 of file tastring.inl.
|
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.
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. |
src | The object to "stringify" and append. |
*this
to allow concatenated calls. Definition at line 1294 of file tastring.inl.
|
inline |
Appends an array of the same character type.
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. |
src | A pointer to the start of the array to append. |
srcLength | The length of the string. |
*this
to allow concatenated calls. Definition at line 1197 of file tastring.inl.
|
inline |
Appends an array of an incompatible character type.
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. |
src | A pointer to the start of the array to append. |
srcLength | The length of the string. |
*this
to allow concatenated calls. Definition at line 851 of file tastring.inl.
|
inline |
Appends a region of another String. The checking version adjusts the given region to the bounds of the source string.
TCheck | Chooses checking or non-checking implementation. Defaults to CHK. |
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 |
*this
to allow concatenated calls. Definition at line 1245 of file tastring.inl.
|
inline |
Appends string-like types which satisfy either of the concepts IsImplicitArraySource IsImplicitZTArraySource.
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. |
src | The string-type object to append. |
*this
to allow concatenated calls. Definition at line 1318 of file tastring.inl.
|
inline |
Appends a single character of compatible type.
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 . |
src | The character object to append. |
*this
to allow concatenated calls. Definition at line 1349 of file tastring.inl.
|
inline |
Returns an iterator pointing to a constant character at the start of this string.
Definition at line 2126 of file tastring.inl.
|
inline |
Returns an iterator pointing to a constant character at the start of this string.
Definition at line 2158 of file string.inl.
|
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.
Definition at line 640 of file tastring.inl.
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 compiler-symbol ALIB_DEBUG_STRINGS is true
.
Invocations to this method should be performed using macro ALIB_STRING_DBG_CHK.
|
inline |
Used to disable warnings that are by default raised in debug-compilations of method SetBuffer.
Definition at line 245 of file tastring.inl.
|
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.
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. |
regionStart | The start of the region to delete. |
regionLength | The length of the region to delete. Defaults to MAX_LEN. |
*this
to allow concatenated calls. Definition at line 1664 of file tastring.inl.
|
inline |
Deletes the given string from the end of this string. If this string does not end with the given string, nothing is done.
deleteIfMatch | The string to be deleted at the end. |
*this
to allow concatenated calls. Definition at line 1803 of file tastring.inl.
|
inline |
Reduces the length of the string by the given number of characters.
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. |
regionLength | The length of the region at the end to delete. |
*this
to allow concatenated calls. Definition at line 1772 of file tastring.inl.
|
inline |
Deletes the given string from the start of this string. If this string does not start with the given string, nothing is done.
deleteIfMatch | The string to be deleted at the start. |
*this
to allow concatenated calls. Definition at line 1754 of file tastring.inl.
|
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.
TCheck | Defaults to CHK, which is the normal invocation mode. If <false> is added to the method name, no parameter checks are performed. |
regionLength | The length of the region at the start to delete. |
*this
to allow concatenated calls. Definition at line 1720 of file tastring.inl.
|
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 the (seldom) situation, 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.
Definition at line 789 of file tastring.inl.
|
inline |
Returns an iterator pointing behind this string.
Definition at line 2130 of file tastring.inl.
|
inline |
Returns an iterator pointing behind this string.
Definition at line 2166 of file string.inl.
|
inline |
Ensures that the capacity of the internal buffer meets or exceeds the actual length plus the given growth value.
spaceNeeded | The desired growth of the length of the string represented by this. |
Definition at line 612 of file tastring.inl.
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.
minimumGrowth | The desired minimum growth of length. |
Definition at line 80 of file tastringimpl.inl.
|
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.
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.true
if the buffer is internally allocated and will be deleted with the deletion of this object. False otherwise. Definition at line 658 of file tastring.inl.
|
inline |
Inserts the given string at given position. If the position is not between 0 and the length of the target, nothing is inserted.
TCheck | Chooses checking or non-checking implementation. Defaults to CHK. |
src | The String to insert. |
pos | The position to insert src. |
*this
to allow concatenated calls. Definition at line 1552 of file tastring.inl.
|
inline |
Appends the given character c qty-times. The non-checking version does not check parameter qty to be greater than zero.
TCheck | Defaults to CHK, which chooses the checking version of the method. |
c | The character to insert qty times. |
qty | The quantity of characters to insert. |
*this
to allow concatenated calls. Definition at line 1587 of file tastring.inl.
|
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.
TCheck | Defaults to CHK, which chooses the checking version of the method. |
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. |
*this
to allow concatenated calls. Definition at line 1616 of file tastring.inl.
|
inline |
Appends platform-specific new line character(s) by appending literal string NEW_LINE.
*this
to allow concatenated calls. Definition at line 1338 of file tastring.inl.
|
inlineconstexpr |
Templated implicit cast operator
constructing an instance of type T from this string instance. This operator requires the type T satisfying the concept IsImplicitZTArrayCast.
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.
T | The type to implicitly cast this instance to. Deduced by the compiler. |
Definition at line 427 of file tastring.inl.
|
inlineexplicitconstexpr |
Templated explicit cast operator
constructing an instance of type T from this string instance. This operator requires the type T satisfying the concept IsExplicitZTArrayCast.
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.
T | The type to implicitly cast this instance to. Deduced by the compiler. |
Definition at line 450 of file tastring.inl.
|
inlineconstexpr |
Templated implicit cast operator
constructing an instance of type T from this string instance. This operator requires the type T satisfying the concept IsImplicitZTArrayCast.
Custom types can be enabled for this operator by specializing the traits-type ZTArrayTraits, which is used for both; the implementation of the concept, and the implementation of this operator itself.
T | The type to implicitly cast this instance to. Deduced by the compiler. |
Definition at line 472 of file tastring.inl.
|
inlineexplicitconstexpr |
Templated explicit cast operator
constructing an instance of type T from this string instance. This operator requires the type T satisfying the concept IsExplicitZTArrayCast.
Custom types can be enabled for this operator by specializing the traits-type ZTArrayTraits, which is used for both; the implementation of the concept, and the implementation of this operator itself.
T | The type to explicitly cast this instance to. Deduced by the compiler. |
Definition at line 497 of file tastring.inl.
|
inline |
Alias to overloaded methods Append.
When this operator is used, template parameter TCheck of the Append-method called is set to CHK.
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.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.TAppendable | The type of parameter source. |
src | The object of type T to append. |
*this
to allow concatenated calls. Definition at line 1501 of file tastring.inl.
|
inline |
Alias to overloaded methods Append.
When this operator is used, template parameter TCheck of the Append-method called is set to CHK.
TAppendable | The type of parameter source. |
src | The object of type T to append. |
*this
to allow concatenated calls. Definition at line 1467 of file tastring.inl.
|
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.
copy | The object to copy the contents from. |
*this
to allow concatenated calls. Definition at line 513 of file tastring.inl.
|
inline |
Provides read/write access to single characters. Overrides String::operator[] returning a reference to a TChar value, which allows changing the character stored.
idx | The index of the character within this object's buffer. |
Definition at line 749 of file tastring.inl.
|
inline |
Reads a character at a given index.
const
) version of this operator, returning a a reference to the character to provide write access. Such reference to a character could not be given if the index was out of range. This way, a check in the derived type could likewise not be implemented.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.idx | The index of the character within this object's buffer. |
Definition at line 493 of file string.inl.
|
inlineconstexpr |
Pops one character from the end of this string.
With debug-compilations, an assertion is raised in case this string is empty.
Definition at line 2148 of file tastring.inl.
|
inlineconstexpr |
Appends the given character to this AString.
Needed, for example, to make this type compatible with std::back_insert_iterator
.
ch | The character to append to the end of this string. |
Definition at line 2143 of file tastring.inl.
|
inline |
Returns a reverse iterator pointing to a constant character at the end of this string.
Definition at line 2134 of file tastring.inl.
|
inline |
Returns a reverse iterator pointing to a constant character at the end of this string.
Definition at line 2174 of file string.inl.
|
inline |
Returns a reverse iterator pointing before the start of this string.
Definition at line 2138 of file tastring.inl.
|
inline |
Returns a reverse iterator pointing before the start of this string.
Definition at line 2178 of file string.inl.
|
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.
TCheck | Chooses checking or non-checking implementation. Defaults to CHK. |
regionStart | The start of the region |
regionLength | The length of the region |
c | The character to set in the region. |
*this
to allow concatenated calls. Definition at line 1950 of file tastring.inl.
|
inline |
Replaces a region in this object by 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.
TCheck | Chooses checking or non-checking implementation. Defaults to CHK. |
src | The replacement string. |
regionStart | The start of the region. |
regionLength | The length of the region. |
*this
to allow concatenated calls. Definition at line 1896 of file tastring.inl.
|
inline |
Sets the length of this string to zero. A nulled object remains nulled.
*this
to allow concatenated calls. Definition at line 1509 of file tastring.inl.
|
inline |
Sets the length of the string to zero and then invokes one of the overloaded methods Append.
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. |
src | The source of type TAppendable to append. |
*this
to allow concatenated calls. Definition at line 1521 of file tastring.inl.
|
inline |
Reverses the order of the characters of this string (or a region hereof).
regionStart | Start of the region to be reversed. Defaults to 0 |
regionLength | Length of the region to be reversed. Defaults to MAX_LEN. |
*this
to allow concatenated calls. Definition at line 2082 of file tastring.inl.
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 .
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. |
Definition at line 388 of file tastringimpl.inl.
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.
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. |
Definition at line 360 of file tastringimpl.inl.
void alib::strings::TAString< TChar, TAllocator >::SetBuffer | ( | integer | newCapacity | ) |
Resizes the buffer to meet exactly the given size.
The following rules apply:
0
, then the currently allocated buffer will be disposed and the object's state is nulled.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.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 method DbgDisableBufferReplacementWarning. For example, in some situation it might be taken into account that instances of derived type LocalString sometimes may grow more than average and in such 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.
newCapacity | The new capacity of the internal buffer. |
Definition at line 114 of file tastringimpl.inl.
void alib::strings::TAString< TChar, TAllocator >::SetBuffer | ( | TChar * | extBuffer, |
integer | extBufferSize, | ||
integer | extLength = 0, | ||
lang::Responsibility | responsibility = lang::Responsibility::KeepWithSender ) |
This methods replaces the current buffer with the one provided.
The following rules apply:
nullptr
is provided, the current buffer is released.nullptr
, its size given with parameter extBufferSize has to be at least 1
for providing the space for a termination character.- 1
.-1
.The internal buffer allocation is performed with methods Allocator::allocate, Allocator::reallocate and Allocator::free. 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 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.
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 249 of file tastringimpl.inl.
|
inline |
Sets the character at the given index. A range check is performed. If this fails, nothing is done.
const
, as it does not manipulate the data of the class itself but a character in the buffer pointer.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. |
idx | The index of the character to write. |
c | The character to write. |
Definition at line 721 of file tastring.inl.
|
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 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.
newLength | The new length of the AString. Must be between 0 and Capacity. |
Definition at line 771 of file tastring.inl.
|
inline |
Invokes SetBuffer(0).
Definition at line 664 of file tastring.inl.
|
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.
newLength | The new length of this AString. Must be between 0 and the current length. |
*this
to allow concatenated calls. Definition at line 816 of file tastring.inl.
|
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.
Definition at line 682 of file tastring.inl.
|
inline |
Converts all or a region of characters in the Buffer to lower case.
regionStart | Start of the region to be converted. Defaults to 0 |
regionLength | Length of the region to be converted. Defaults to MAX_LEN. |
*this
to allow concatenated calls. Definition at line 2052 of file tastring.inl.
|
inline |
Converts all or a region of characters in the Buffer to upper case.
regionStart | Start of the region to be converted. Defaults to 0 |
regionLength | Length of the region to be converted. Defaults to MAX_LEN. |
*this
to allow concatenated calls. Definition at line 2021 of file tastring.inl.
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.
trimChars | Pointer to a zero-terminated set of characters to be omitted. Defaults to DEFAULT_WHITESPACES. |
*this
to allow concatenated calls. Definition at line 336 of file tastringimpl.inl.
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.
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. |
Definition at line 312 of file tastringimpl.inl.
|
inline |
All characters defined in given set are removed at the end of this string.
trimChars | Pointer to a zero-terminated set of characters to be omitted. Defaults to DEFAULT_WHITESPACES. |
*this
to allow concatenated calls. Definition at line 1868 of file tastring.inl.
|
inline |
All characters defined in given set are removed at the beginning of this string.
trimChars | Pointer to a zero-terminated set of characters to be omitted. Defaults to DEFAULT_WHITESPACES. |
*this
to allow concatenated calls. Definition at line 1846 of file tastring.inl.
|
inline |
The internal buffer character array provided as non constant character pointer.
Definition at line 700 of file tastring.inl.