ALib C++ Library
Library Version: 2312 R0
Documentation generated by doxygen
Protected Fields | List of all members
TAString< TChar > Class Template Reference

#include <astring.hpp>

Inheritance diagram for TAString< TChar >:
[legend]
Collaboration diagram for TAString< TChar >:
[legend]

Class Description

template<typename TChar>
class aworx::lib::strings::TAString< TChar >


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 to let an object of this class take control on a buffer provided from outside. In this case, the buffer is considered an internal buffer, rather than an external one.

The default constructor creates a nulled AString which does not dispose about 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.

On 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 T_Append.

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

Template Parameters
TCharThe character type.
Alias names for specializations of this class using character types character, nchar, wchar, xchar, complementChar and strangeChar are provided in namespace aworx with type definitions AString, NAString, WAString, XAString, ComplementAString and StrangeAString.

Definition at line 27 of file astring.hpp.

Public Methods

Constructors, Destructor and Assignment

constexpr TAString ()
 
 TAString (const TAString &copy)
 
 TAString (TAString &&move) noexcept
 
template<class TAppendable >
 TAString (const TAppendable &src)
 
 ~TAString () noexcept
 
template<typename TCharArray >
 operator TCharArray () const
 
template<typename TCharArray >
 operator TCharArray () const
 
TAStringoperator= (const TAString &copy)
 
Memory allocation and buffer access

ALIB_API void SetBuffer (integer newCapacity)
 
ALIB_API void SetBuffer (TChar *extBuffer, integer extBufferSize, integer extLength=0, Responsibility responsibility=Responsibility::KeepWithSender)
 
void EnsureRemainingCapacity (integer spaceNeeded)
 
void GrowBufferAtLeastBy (integer minimumGrowth)
 
integer Capacity () const
 
bool HasInternalBuffer () const
 
void SetNull ()
 
const TChar * Terminate () const
 
Writable Buffer Access

TChar * VBuffer () const
 
template<bool TCheck = true>
ALIB_WARNINGS_IGNORE_IF_CONSTEXPR void SetCharAt (integer idx, TChar c)
 
TChar & operator[] (integer idx)
 
void SetLength (integer newLength)
 
TAStringShortenTo (integer newLength)
 
Appending Strings

template<bool TCheck = true, typename TCharSrc >
TAStringAppend (const TCharSrc *src, integer srcLength)
 
template<bool TCheck = true>
TAStringAppend (const TChar *src, integer srcLength)
 
template<bool TCheck = true>
TAStringAppend (const TString< TChar > &src, integer regionStart, integer regionLength=MAX_LEN)
 
template<bool TCheck = true>
TAString_ (const TString< TChar > &src, integer regionStart, integer regionLength=MAX_LEN)
 
TAStringNewLine ()
 
AppendString

template<bool TCheck = true, typename TAppendable >
TAStringAppend (const TAppendable &src)
 
template<bool TCheck = true, class TAppendable >
TAString_ (const TAppendable &src)
 
template<class TAppendable >
TAStringoperator<< (const TAppendable &src)
 
Insert and Delete

TAStringReset ()
 
template<bool TCheck = true, typename TAppendable >
TAStringReset (const TAppendable &src)
 
TAString_ ()
 
template<bool TCheck = true>
TAStringInsertAt (const TString< TChar > &src, integer pos)
 
template<bool TCheck = true>
TAStringInsertChars (TChar c, integer qty)
 
template<bool TCheck = true>
TAStringInsertChars (TChar c, integer qty, integer pos)
 
template<bool TCheck = true>
TAStringDelete (integer regionStart, integer regionLength=MAX_LEN)
 
template<bool TCheck = true>
TAStringDeleteStart (integer regionLength)
 
template<bool TCheck = true>
TAStringDeleteEnd (integer regionLength)
 
ALIB_API TAStringTrim (const TCString< TChar > &trimChars=TT_StringConstants< TChar >::DefaultWhitespaces())
 
ALIB_API integer TrimAt (integer idx, const TCString< TChar > &trimChars=TT_StringConstants< TChar >::DefaultWhitespaces())
 
TAStringTrimStart (const TCString< TChar > &trimChars=TT_StringConstants< TChar >::DefaultWhitespaces())
 
TAStringTrimEnd (const TCString< TChar > &trimChars=TT_StringConstants< TChar >::DefaultWhitespaces())
 
Replace

template<bool TCheck = true>
TAStringReplaceSubstring (const TString< TChar > &src, integer regionStart, integer regionLength)
 
template<bool TCheck = true>
TAStringReplaceRegion (TChar c, integer regionStart, integer regionLength)
 
ALIB_API integer SearchAndReplace (TChar needle, TChar replacement, integer startIdx=0)
 
ALIB_API integer SearchAndReplace (const TString< TChar > &needle, const TString< TChar > &replacement, integer startIdx=0, integer maxReplacements=MAX_LEN, Case sensitivity=Case::Sensitive)
 
template<bool TCheck = true>
TAStringToUpper (integer regionStart=0, integer regionLength=MAX_LEN)
 
template<bool TCheck = true>
TAStringToLower (integer regionStart=0, integer regionLength=MAX_LEN)
 
template<bool TCheck = true>
TAStringReverse (integer regionStart=0, integer regionLength=MAX_LEN)
 
- Public Methods inherited from TString< TChar >
constexpr TString () noexcept=default
 
constexpr TString (const TString &) noexcept=default
 
constexpr TString (TString &&) noexcept=default
 
TStringoperator= (const TString &) noexcept=default
 
TStringoperator= (TString &&) noexcept=default
 
constexpr TString (const TChar *pBuffer, integer pLength) noexcept
 
template<typename TCharArray >
constexpr TString (const TCharArray &src)
 
template<typename TCharArray >
 operator TCharArray () const
 
template<typename TCharArray >
 operator TCharArray () const
 
template<bool TCheck = true>
ALIB_WARNINGS_IGNORE_IF_CONSTEXPR TString< TChar > Substring (integer regionStart, integer regionLength=MAX_LEN) const
 
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<bool TCheck = true>
TChar CharAt (integer idx) const
 
template<bool TCheck = true>
TChar CharAtStart () const
 
template<bool TCheck = true>
TChar CharAtEnd () const
 
TChar operator[] (integer idx) const
 
std::size_t Hashcode () const
 
std::size_t HashcodeIgnoreCase () const
 
template<Case TSensitivity = Case::Sensitive>
bool Equals (const TString< TChar > &rhs) const
 
template<bool TCheck = true, Case TSensitivity = Case::Sensitive>
int CompareTo (const TString< TChar > &rhs) const
 
template<bool TCheck = true, Case TSensitivity = Case::Sensitive>
int CompareTo (const TString &rhs, integer rhsRegionStart, integer rhsRegionLength=MAX_LEN) const
 
template<bool TCheck = true, Case TSensitivity = Case::Sensitive>
int CompareTo (const TString &rhs, integer rhsRegionStart, integer rhsRegionLength, integer regionStart, integer regionLength=MAX_LEN) const
 
template<bool TCheck = true, Case TSensitivity = Case::Sensitive>
bool ContainsAt (const TString &needle, integer pos) const
 
template<bool TCheck = true, Case TSensitivity = Case::Sensitive>
bool StartsWith (const TString &needle) const
 
template<bool TCheck = true, Case TSensitivity = Case::Sensitive>
bool EndsWith (const TString &needle) const
 
template<bool TCheck = true>
integer IndexOf (TChar needle, integer startIdx=0) const
 
template<bool TCheck = true>
integer IndexOf (TChar needle, integer regionStart, integer regionLength) const
 
integer IndexOfOrLength (TChar needle) const
 
template<bool TCheck = true>
ALIB_WARNINGS_ALLOW_UNSAFE_BUFFER_USAGE integer IndexOfOrLength (TChar needle, integer startIdx) const
 
template<bool TCheck = true>
ALIB_WARNINGS_RESTORE integer LastIndexOf (TChar needle, integer startIndex=MAX_LEN) const
 
template<Inclusion TInclusion, bool TCheck = true>
integer IndexOfAny (const TString &needles, integer startIdx=0) const
 
template<Inclusion TInclusion, bool TCheck = true>
integer LastIndexOfAny (const TString &needles, integer startIdx=MAX_LEN) const
 
template<bool TCheck = true, Case TSensitivity = Case::Sensitive>
integer IndexOf (const TString &needle, integer startIdx=0) const
 
template<bool TCheck = true>
integer IndexOfFirstDifference (const TString &needle, Case sensitivity=Case::Sensitive, integer idx=0) const
 
integer IndexOfSegmentEnd (TChar opener, TChar closer, integer idx) const
 
template<bool TCheck = true>
integer CountChar (TChar needle, integer startPos=0) const
 
template<bool TCheck = true>
integer CountChar (TChar needle, TChar omit, integer startPos) const
 
template<bool TCheck = true, Case TSensitivity = Case::Sensitive>
integer Count (const TString &needle, integer startPos=0) const
 
template<bool TCheck = true, Case TSensitivity = 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
 
bool AdjustRegion (integer &regionStart, integer &regionLength) const
 
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
 
 TString (ConstIterator &start, ConstIterator &end)
 

Protected Fields

integer capacity
 
- Protected Fields inherited from TString< TChar >
const TChar * buffer
 
integer length
 

Debug Methods/Types

integer debugLastAllocRequest =0
 
bool dbgWarnWhenExternalBufferIsReplaced = true
 
void dbgCheck () const
 
void DbgDisableBufferReplacementWarning ()
 
constexpr TAString (TChar *extBuffer, integer extBufferSize)
 

std::iterator_traits

using Iterator = typename TString< TChar >::template TRandomAccessIterator< TChar >
 
using ReverseIterator = std::reverse_iterator< Iterator >
 
ALIB_WARNINGS_ALLOW_UNSAFE_BUFFER_USAGE Iterator begin ()
 
Iterator end ()
 
ALIB_WARNINGS_RESTORE ReverseIterator rbegin ()
 
ReverseIterator rend ()
 

Additional Inherited Members

- Public Types inherited from TString< TChar >
using ConstIterator = TRandomAccessIterator< const TChar >
 
using ConstReverseIterator = std::reverse_iterator< ConstIterator >
 
- Protected Methods inherited from TString< TChar >
template<Case TSensitivity = Case::Sensitive>
ALIB_API integer indexOfString (const TString &needle, integer startIdx) const
 

Member Typedef Documentation

◆ Iterator

using Iterator = typename TString<TChar>::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 1932 of file astring.hpp.

◆ ReverseIterator

using ReverseIterator = std::reverse_iterator<Iterator>

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

Definition at line 1935 of file astring.hpp.

Constructor & Destructor Documentation

◆ TAString() [1/5]

constexpr TAString ( TChar *  extBuffer,
integer  extBufferSize 
)
inlineexplicitconstexprprotected

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

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

Definition at line 384 of file astring.hpp.

◆ TAString() [2/5]

constexpr TAString ( )
inlineexplicitconstexpr

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

Definition at line 401 of file astring.hpp.

◆ TAString() [3/5]

TAString ( const TAString< TChar > &  copy)
inlineexplicit

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

Parameters
copyThe object to copy.

Definition at line 411 of file astring.hpp.

◆ TAString() [4/5]

TAString ( TAString< TChar > &&  move)
inlinenoexcept

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

Parameters
moveThe object to move.

Definition at line 425 of file astring.hpp.

◆ TAString() [5/5]

TAString ( const TAppendable &  src)
inlineexplicit

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

Template Parameters
TAppendableThe type of parameter source that has a specialization of functor T_Append.
Parameters
srcThe source object to append to this string.

Definition at line 468 of file astring.hpp.

◆ ~TAString()

~TAString ( )
inlinenoexcept

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

Definition at line 478 of file astring.hpp.

Member Function Documentation

◆ _() [1/3]

TAString& _ ( )
inline

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

Returns
*this to allow concatenated calls.

Definition at line 1337 of file astring.hpp.

◆ _() [2/3]

TAString& _ ( const TAppendable &  src)
inline

Alias to method Append(const TAppendable&).
Provided for compatibility with C# and Java versions of ALib.

Template Parameters
TCheckDefaults to true which is the normal invocation mode. If <false> is added to the method name, checks are omitted.
TAppendableThe type of parameter source.
Parameters
srcThe source object to append a string representation for.
Returns
*this to allow concatenated calls.

Definition at line 1277 of file astring.hpp.

◆ _() [3/3]

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

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

Template Parameters
TCheckChooses checking or non-checking implementation. Defaults to true.
Parameters
srcThe String to append.
regionStartThe start of the region in src to append.
regionLengthThe maximum length of the region in src to append. Defaults to MAX_LEN
Returns
*this to allow concatenated calls.

Definition at line 1048 of file astring.hpp.

◆ Append() [1/4]

TAString& Append ( const TAppendable &  src)
inline

Templated method that accepts references and pointers to objects of "appendable types". The latter are types that a specialization of functor T_Append exists for and with that have a corresponding method to create a string representation of a source object.
In addition arbitrary string types, hence types that a specialization of TMP struct T_CharArray or T_ZTCharArray exists for, are accepted.
Finally, single characters of different width are may be passed to this method.

The method has aliases with operator<<(const TAppendable&) and method _(const TAppendable&). The latter is provided for compatibility with C# and Java versions of ALib.

See also
See chapter 5.1 Appending Custom Types of this module's Programmer's Manual for more information.
Template Parameters
TCheckDefaults to true which is the normal invocation mode. If <false> is added to the method name, checks are omitted. The type of checks omitted depend on the type of TAppendable. In case of provision of pointers, no check for nullptr are made.
TAppendableThe type of parameter source.
Parameters
srcThe source of type TAppendable to append.
Returns
*this to allow concatenated calls.

Definition at line 1254 of file astring.hpp.

◆ Append() [2/4]

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

Appends an array of the same character type.

Template Parameters
TCheckDefaults to true which is the normal invocation mode. If <false>, no nullptr check is done on parameter src. Also, this object would not loose a nulled state when the given cstring portion is empty.
Parameters
srcA pointer to the start of the array to append.
srcLengthThe length of the string.
Returns
*this to allow concatenated calls.

Definition at line 953 of file astring.hpp.

◆ Append() [3/4]

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

Appends an incompatible character array.

Template Parameters
TCharSrcThe character type of the given array.
TCheckDefaults to true which is the normal invocation mode. If <false>, no nullptr check is done on parameter src. Also, this object would not loose a nulled state when the given cstring portion is empty.
Parameters
srcA pointer to the start of the array to append.
srcLengthThe length of the string.
Returns
*this to allow concatenated calls.

◆ Append() [4/4]

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

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

Note
When using the non-checking version, parameter regionLength must be set explicitly to the correct value (instead of using the default value).
Template Parameters
TCheckChooses checking or non-checking implementation. Defaults to true.
Parameters
srcThe String to append.
regionStartThe start of the region in src to append.
regionLengthThe maximum length of the region in src to append. Defaults to MAX_LEN
Returns
*this to allow concatenated calls.

Definition at line 1004 of file astring.hpp.

◆ begin()

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

Returns
The start of this string.

Definition at line 1940 of file astring.hpp.

◆ Capacity()

integer Capacity ( ) const
inline

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

Returns
The size of the allocated buffer.

Definition at line 718 of file astring.hpp.

◆ dbgCheck()

void dbgCheck ( ) const

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

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

◆ DbgDisableBufferReplacementWarning()

void DbgDisableBufferReplacementWarning ( )
inline

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

Note
In release-compilations this inline method is empty and will be optimized out.
See also
See method SetBuffer for more information.

Definition at line 361 of file astring.hpp.

◆ Delete()

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

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

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

Note
See also methods Reset, DeleteStart and DeleteEnd.
Template Parameters
TCheckDefaults to true which is the normal invocation mode. If <false> is added to the method name, the start of the region is not adjusted to the string's bounds.
Parameters
regionStartThe start of the region to delete.
regionLengthThe length of the region to delete. Defaults to MAX_LEN.
Returns
*this to allow concatenated calls.

Definition at line 1482 of file astring.hpp.

◆ DeleteEnd()

TAString& DeleteEnd ( integer  regionLength)
inline

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

Template Parameters
TCheckDefaults to true which is the normal invocation mode. If <false> is added to the method name, no parameter checks are performed and any given value is just subtracted from the current length.
Parameters
regionLengthThe length of the region at the end to delete.
Returns
*this to allow concatenated calls.

Definition at line 1581 of file astring.hpp.

◆ DeleteStart()

TAString& DeleteStart ( integer  regionLength)
inline

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

Template Parameters
TCheckDefaults to true which is the normal invocation mode. If <false> is added to the method name, no parameter checks are performed.
Parameters
regionLengthThe length of the region at the start to delete.
Returns
*this to allow concatenated calls.

Definition at line 1539 of file astring.hpp.

◆ end()

Iterator end ( )
inline

Returns an iterator pointing behind this string.

Returns
The end of this string.

Definition at line 1944 of file astring.hpp.

◆ EnsureRemainingCapacity()

void EnsureRemainingCapacity ( integer  spaceNeeded)
inline

Ensures that the capacity of the internal buffer meets or exceeds the actual length plus the given growth value.

Parameters
spaceNeededThe desired growth of the length of the string represented by this.

Definition at line 688 of file astring.hpp.

◆ GrowBufferAtLeastBy()

void GrowBufferAtLeastBy ( integer  minimumGrowth)

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

Parameters
minimumGrowthThe desired minimum growth of length.

Definition at line 74 of file astring.cpp.

◆ HasInternalBuffer()

bool HasInternalBuffer ( ) const
inline

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

Note
Derived class LocalString will report false here. This sounds wrong on the first sight, as the buffer is allocated by an 'internal' member. But from an AString's perspective, class LocalString works on an 'external' buffer.
Returns
true if the buffer is internally allocated and will be deleted with the deletion of this object. False otherwise.

Definition at line 738 of file astring.hpp.

◆ InsertAt()

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

Inserts the given string at given position. If the position is not between 0 and the length of the target, nothing is inserted.

Note
To insert a string with replacing a different one at the same time, use ReplaceSubstring(src, pos, regionLength).
Template Parameters
TCheckChooses checking or non-checking implementation. Defaults to true.
Parameters
srcThe String to insert.
posThe position to insert src.
Returns
*this to allow concatenated calls.

Definition at line 1358 of file astring.hpp.

◆ InsertChars() [1/2]

TAString& InsertChars ( TChar  c,
integer  qty 
)
inline

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

Template Parameters
TCheckDefaults to true, which chooses the checking version of the method.
Parameters
cThe character to insert qty times.
qtyThe quantity of characters to insert.
Returns
*this to allow concatenated calls.

Definition at line 1397 of file astring.hpp.

◆ InsertChars() [2/2]

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

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

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

Template Parameters
TCheckDefaults to true, which chooses the checking version of the method.
Parameters
cThe character to insert qty times.
qtyThe quantity of characters to insert.
posThe index in this object where c is inserted qty times.
Returns
*this to allow concatenated calls.

Definition at line 1430 of file astring.hpp.

◆ NewLine()

TAString& NewLine ( )
inline

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

Returns
*this to allow concatenated calls.

Definition at line 1058 of file astring.hpp.

◆ operator TCharArray() [1/2]

operator TCharArray ( ) const
inline

Implicit cast operator to objects of type TCharArray.
This operator is available for all custom types that have an accordingly specialized version of TMP struct T_CharArray and/or T_ZTCharArray defined. In the latter case, method Terminate is invoked prior to the conversion.

The cast is applicable only if no specialization of TMP struct T_SuppressAutoCast auto casts exists, that suppresses implicit casts.

More information about casting ALib string types to other types is provided with chapter 3.2 Casting Strings To Other Types this module's Programmer's Manual.

Template Parameters
TCharArrayThe custom type to implicitly convert this object to.
Returns
A value of custom string type.

◆ operator TCharArray() [2/2]

operator TCharArray ( ) const
inlineexplicit

Explicit cast operator to objects of type TCharArray.
This operator is available for all custom types that have an accordingly specialized version of TMP struct T_CharArray and/or T_ZTCharArray defined. In the latter case, method Terminate is invoked prior to the conversion.

The cast is applicable only if no specialization of TMP struct T_SuppressAutoCast auto casts exists, that suppresses explicit casts.

More information about casting ALib string types to other types is provided with chapter 3.2 Casting Strings To Other Types this module's Programmer's Manual.

Template Parameters
TCharArrayThe custom type to explicitly convert this object to.
Returns
A value of custom string type.

◆ operator<<()

TAString& operator<< ( const TAppendable &  src)
inline

Alias operator invoking Append<true>(const TAppendable&).

Template Parameters
TAppendableThe type of parameter source.
Parameters
srcThe object of type T to append.
Returns
*this to allow concatenated calls.

Definition at line 1290 of file astring.hpp.

◆ operator=()

TAString& operator= ( const TAString< TChar > &  copy)
inline

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

See also
For details why no other assignment operators exists for this class, note paragraph Copy/Move Constructor and Assignment of this class's reference documentation.
Parameters
copyThe object to copy the contents from.
Returns
*this to allow concatenated calls.

Definition at line 584 of file astring.hpp.

◆ operator[]()

TChar& operator[] ( integer  idx)
inline

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

Attention
No parameter check is performed (other than an assertions in debug-compilation of ALib). See String::operator[] for details.
Parameters
idxThe index of the character within this object's buffer.
Returns
If the character contained (or, if lvalue the one to set).

Definition at line 844 of file astring.hpp.

◆ rbegin()

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

Returns
The last character of this string.

Definition at line 1950 of file astring.hpp.

◆ rend()

ReverseIterator rend ( )
inline

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

Returns
The character before this string.

Definition at line 1954 of file astring.hpp.

◆ ReplaceRegion()

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

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

The non-checking version does not adjust the region.

Template Parameters
TCheckChooses checking or non-checking implementation. Defaults to true.
Parameters
regionStartThe start of the region
regionLengthThe length of the region
cThe character to set in the region.
Returns
*this to allow concatenated calls.

Definition at line 1755 of file astring.hpp.

◆ ReplaceSubstring()

TAString& ReplaceSubstring ( const TString< TChar > &  src,
integer  regionStart,
integer  regionLength 
)
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 assertion in debug-compilations if the given region is out of bounds.

Template Parameters
TCheckChooses checking or non-checking implementation. Defaults to true.
Parameters
srcThe replacement string.
regionStartThe start of the region.
regionLengthThe length of the region.
Returns
*this to allow concatenated calls.

Definition at line 1700 of file astring.hpp.

◆ Reset() [1/2]

TAString& Reset ( )
inline

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

Returns
*this to allow concatenated calls.

Definition at line 1304 of file astring.hpp.

◆ Reset() [2/2]

TAString& Reset ( const TAppendable &  src)
inline

Sets the length of the string to zero and then invokes Append(const TAppendable&).

Template Parameters
TCheckDefaults to true which is the normal invocation mode. The value is used with the invocation of method Append.
TAppendableThe type of parameter source.
Parameters
srcThe source of type TAppendable to append.
Returns
*this to allow concatenated calls.

Definition at line 1322 of file astring.hpp.

◆ Reverse()

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

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

Parameters
regionStartStart of the region to be reversed. Defaults to 0
regionLengthLength of the region to be reversed. Defaults to MAX_LEN.
Returns
*this to allow concatenated calls.

Definition at line 1891 of file astring.hpp.

◆ SearchAndReplace() [1/2]

integer SearchAndReplace ( const TString< TChar > &  needle,
const TString< TChar > &  replacement,
integer  startIdx = 0,
integer  maxReplacements = MAX_LEN,
Case  sensitivity = Case::Sensitive 
)

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

Parameters
needleThe string to be searched and replaced.
replacementThe replacement string.
startIdxThe index where the search starts. Optional and defaults 0.
maxReplacementsThe maximum number of replacements to perform. Optional and defaults to MAX_LEN.
sensitivityCase sensitivity of the comparison. Optional and defaults to Case::Sensitive.
Returns
The number of replacements that where performed.

Definition at line 357 of file astring.cpp.

◆ SearchAndReplace() [2/2]

integer SearchAndReplace ( TChar  needle,
TChar  replacement,
integer  startIdx = 0 
)

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

Parameters
needleThe character to search.
replacementThe replacement character.
startIdxThe index where the search starts. Optional and defaults 0.
Returns
The number of replacements that where performed.

Definition at line 330 of file astring.cpp.

◆ SetBuffer() [1/2]

void SetBuffer ( integer  newCapacity)

Resizes the buffer to meet exactly the given size.

The following rules apply:

  • The string represented by this instance is copied to the new buffer. If this is larger than the new buffer size, the string is cut at the end to fit.
  • If the desired new size is 0, then the currently allocated buffer will be disposed and the object's state is nulled.
  • If the current buffer's life-cycle is managed externally (e.g. was set using SetBuffer(TChar*,integer,integer, Responsibility) with parameter responsibility being Responsibility::KeepWithSender), this method will replace the buffer by a new one, even if the new requested size is the same as the external buffer's size. In other words, the only case when this method does not replace the current buffer is when the current buffer's life-cycle is (already) internally managed and it has the same size than what is requested.
  • In this C++ version of ALib, the true allocation size is one character larger than what is given with parameter newCapacity. This allows method Terminate to add a termination character without checking (and eventually reallocating and copying) an internally managed buffer.

Any method of this class that extends the length of the string will directly or indirectly invoke this method, when the current buffer size is not sufficient. If a future string length, which is the result of more than one concatenation of data to an AString is predictable, then it is advisable to reserve the allocated size prior to 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 issued, 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.

Parameters
newCapacityThe new capacity of the internal buffer.

Definition at line 107 of file astring.cpp.

◆ SetBuffer() [2/2]

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

This methods replaces the current buffer with the one provided.

The following rules apply:

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

The internal buffer allocation is performed with methods std::malloc, std::realloc and std::free. The latter two are also used on external buffers that are provided with this method if parameter responsibility is given as Responsibility::Transfer, because in this case such externally created buffer is considered an internal one. Consequently, it has to be assured that the given chunk of memory is "compatible" with these methods.

Parameters
extBufferThe external buffer to use.
extBufferSizeThe size of the given buffer.
extLengthThe 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'.
responsibilityIf 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 225 of file astring.cpp.

◆ SetCharAt()

ALIB_WARNINGS_IGNORE_IF_CONSTEXPR void SetCharAt ( integer  idx,
TChar  c 
)
inline

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

Note
The C++ language would allow to declare this method const, as it does not manipulate the data of the class itself but a character in the buffer pointer.
In exclamation cases, to manipulate the contents of const AString, use method VBuffer() like in the following sample:
const AString myAString( "Hello" );
// this would not compile because AString::SetCharAt() is not declared const....
//myAString.SetCharAt( 1, 'e' );
// ...but method VBuffer() is declared const.
myAString.VBuffer()[1]= 'e';
Template Parameters
TCheckPerforms a range check on the given index and a check for illegal setting of termination character '\0' anywhere else but at idx==length.
Parameters
idxThe index of the character to write.
cThe character to write.

Definition at line 812 of file astring.hpp.

◆ SetLength()

void SetLength ( integer  newLength)
inline

Sets a new length for this string.

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

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

Parameters
newLengthThe new length of the AString. Must be between 0 and Capacity.

Definition at line 870 of file astring.hpp.

◆ SetNull()

void SetNull ( )
inline

Invokes SetBuffer(0).

Definition at line 746 of file astring.hpp.

◆ ShortenTo()

TAString& ShortenTo ( integer  newLength)
inline

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

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

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

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

Parameters
newLengthThe new length of this AString. Must be between 0 and the current length.
Returns
*this to allow concatenated calls.

Definition at line 900 of file astring.hpp.

◆ Terminate()

const TChar* Terminate ( ) const
inline

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

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

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

Returns
The pointer to the zero-terminated character buffer.

Definition at line 766 of file astring.hpp.

◆ ToLower()

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

Converts all or a region of characters in the Buffer to lower case.

Parameters
regionStartStart of the region to be converted. Defaults to 0
regionLengthLength of the region to be converted. Defaults to MAX_LEN.
Returns
*this to allow concatenated calls.

Definition at line 1858 of file astring.hpp.

◆ ToUpper()

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

Converts all or a region of characters in the Buffer to upper case.

Parameters
regionStartStart of the region to be converted. Defaults to 0
regionLengthLength of the region to be converted. Defaults to MAX_LEN.
Returns
*this to allow concatenated calls.

Definition at line 1824 of file astring.hpp.

◆ Trim()

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

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

See also
Method TrimAt to remove whitespaces at arbitrary places in the string.
Parameters
trimCharsPointer to a zero terminated set of characters to be omitted. Defaults to DefaultWhitespaces.
Returns
*this to allow concatenated calls.

Definition at line 306 of file astring.cpp.

◆ TrimAt()

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

All characters defined in given set at, left of and right of the given index are removed from the string.
The method returns index of the first character of those characters that were behind the trimmed region. With legal idx given, this value can only be smaller or equal to idx. If idx is out of bounds, the length of the string is returned.

Parameters
idxThe index to perform the trim operation at. Has to be between zero and Length() -1.
trimCharsPointer to a zero terminated set of characters to be omitted. Defaults to DefaultWhitespaces.
Returns
The index of the first character of those characters that were behind the trimmed region.

Definition at line 283 of file astring.cpp.

◆ TrimEnd()

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

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

See also
Method TrimAt to remove whitespaces at arbitrary places in the string.
Parameters
trimCharsPointer to a zero terminated set of characters to be omitted. Defaults to DefaultWhitespaces.
Returns
*this to allow concatenated calls.

Definition at line 1671 of file astring.hpp.

◆ TrimStart()

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

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

See also
Method TrimAt to remove whitespaces at arbitrary places in the string.
Parameters
trimCharsPointer to a zero terminated set of characters to be omitted. Defaults to DefaultWhitespaces.
Returns
*this to allow concatenated calls.

Definition at line 1647 of file astring.hpp.

◆ VBuffer()

TChar* VBuffer ( ) const
inline

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

See also
Chapter Write Access to the Buffer of the reference documentation of this class.
Returns
The internal buffer array.

Definition at line 788 of file astring.hpp.

Member Data Documentation

◆ capacity

integer capacity
protected

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

Definition at line 307 of file astring.hpp.

◆ dbgWarnWhenExternalBufferIsReplaced

bool dbgWarnWhenExternalBufferIsReplaced = true
protected

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

See also
See method DbgDisableBufferReplacementWarning for more information.

Definition at line 348 of file astring.hpp.

◆ debugLastAllocRequest

integer debugLastAllocRequest =0
protected

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

Definition at line 319 of file astring.hpp.


The documentation for this class was generated from the following files:
aworx::AString
lib::strings::TAString< character > AString
Type alias in namespace aworx.
Definition: strings/fwds.hpp:135