[W]String and [W]StringBuffer

[W]String is a value class that contains an array of characters (or bytes in case of String). It is designed to have fast copy operations. The array of characters is zero terminated. String provides non-mutable access to the array of characters. String variant stores 8 bit characters (or bytes), whereas WString is storing 16 bit unicode characters.

StringBuffer is a class related to String that serves as mutable buffer.

[W]String common methods

Removes count element starting at position at.

Replace character at position at with chr.

Sets the number of characters (length) to at.

Returns the number of characters.

Same as GetCount() == 0.

Returns a position of character equal to chr greater or equal to from, or -1 if not found.

Returns a position of last character equal to chr lower or equal to from, or -1 if not found.

Returns a position of last character equal to chr, or -1 if not found.

Returns a position of substring of len characters s greater or equal to from, or -1 if not found.

Same as Find(strlen(s), s, from).

Same as Find(s.GetLength(), s, from).

Returns true if string starts with len characters s.

Same as StartsWith(s, strlen(s)).

Same as StartsWith(s, s.GetLength()).

Returns true if string ends with len characters s.

Same as EndsWith(s, strlen(s)).

Same as EndsWith(s, s.GetLength()).

Empties the string.

Reduces memory used by string to minimum (size optimization).

Preallocates enough memory to hold len (speed optimization).

Returns a pointer to the first character.

Returns a pointer to the ending zero.

Returns a pointer to the last character or to the ending zero if there are no characters in string.

const String& operator+=([w]char c)

Appends single character. This operations has constant amortized time (in other words, internal space used by implementation grows exponentially, like with Vector or std::vector).

const [W]String& operator+=(const [w]char *s)

Appends a zero terminated string.

void Cat(const [W]String& s)

const [W]String& operator+=(const [W]String& s)

Appends another strings.

Appends character c count times.

Appends string s with len. (There can be zeros in s).

Same as Cat(s, lim - s).

void Cat(const [W]String& s, int len)

Appends len characters from s.

[W]String& Cat()

Returns *this. This very specific functions is used to create strings "in-place" when calling other functions, e.g. Foo(String().Cat() << a << " = " << b). Note that simple Foo(String() << a << " = " << b) does not work with standard C++ as you cannot pass temporary as non-const parameter of "<<".

[W]String& operator=(const [w]char *s)

Assigns zero terminated string.

[W]String& operator=(const [W]String& s)

Assigns another string. This operations is relatively fast and does not depend on the length of string.

String& operator=([W]StringBuffer& b)

Assigns the content of [W]StringBuffer. After the operation, sources is empty.

String& operator<<=(const String& s)

"Deep" assignment. It is equivalent of standard assignment followed by Shrink operation (in other words, internal buffer gets reallocated to the exact size of source).

Insert character c at position at.

void Insert(int at, const [W]String& s)

Insert character s at position at.

Inserts first l characters of s at position at.

Inserts zero terminated  s at position at.

[W]String Mid(int pos, int length) const

Returns the substring starting at pos of length characters.

[W]String Mid(int pos) const

Inserts a substring starting at pos till the end of string.

[W]String Right(int count) const

Returns last count characters.

[W]String Left(int count) const

Returns firs count characters (same as Mid(0, count)).

bool IsEqual(const [W]String& s) const

True if strings are equal.

True if strings are equal. s is zero terminated.

int Compare(const [W]String& s) const

Lexicographic comparison, return -1 if this string is lower, 0 for equality, 1 if this string is greater. Individual characters are compared as unsigned integer values.

Lexicographic comparison with zero terminated s.

Return a immutable pointer to zero terminated sequence of characters with string's content (a pointer to String internal buffer). This pointer is only valid until next modifying operation on string (destructor included).

Returns first character of string or 0 if string is empty.

Returns i character of string.

Returns true if String is special value returned by GetVoid.

static [W]String GetVoid()

Returns special Void value. This value is same as empty string, but IsVoid method returns true for it. It can be used in special scenarios where client code needs to distinguish between two empty values (let us say Void is "more empty"...). For example, LoadFile returns Void string if file failed to load, but normal empty string if it is empty.

const [W]String& ToString() const

Returns *this. Useful because ToString is standard method to convert concrete type to text, used by AsString template (and therefore by operator << as well).

Constructs empty [W]String.

[W]String(const Nuller&)

Constructs empty [W]String. This variant is important to allow assigning Null to String (which is same as assigning the empty String).

Copy constructor.

Constructor form zero terminated string.

Constructs a string equal to first n characters of s.

Constructs a string equal to first n characters of s.

Constructs a string equal to first lim - s characters of s.

Constructs a string consisting of  count characters chr.

[W]String([W]StringBuffer& b)

Constructs a string from b. b is emptied by this operation.

friend void Swap(String& a, String& b)

Optimized swap operation.

String(const std::string& s)

Constructor to achieve minimal STL compatibility.

String specific methods

void Cat(const byte *s, int len)

Appends len bytes starting at s to String.

Return a immutable pointer to zero terminated sequence of bytes with string's content (a pointer to String internal buffer). This pointer is only valid until next modifying operation on string (destructor included).

WString ToWString() const

Convert String to WString using current default charset.

String(const byte *s, int n)

Constructs string equal to first n bytes of s.

WString specific methods

String ToString() const

Converts WString to String using current default charset. Also serves as standard text conversion (for AsString and operator<< templates).

[W]StringBuffer methods

Returns a pointer to the buffer of characters. Mutating operations invalidate this pointer.

Returns Begin() + GetCount(). Mutating operations invalidate this pointer.

Appends single character.

Appends count characters c.

Appends len characters of s.

Returns the number of characters in the buffer.

 len

Returns a pointer to the buffer of characters. Mutating operations invalidate this pointer.

Clears the content of StringBuffer.

Preallocates internal buffer (avoids resizing of internal buffer up to alloc characters).

Same as SetCount(strlen(Begin())). Useful for converting C strings returned from system to String.

void operator=([W]String& s)

Assigns content of s to StringBuffer. Clears s.

Constructs empty buffer.

Constructs buffer of length characters.

Buffer([W]String& text)

Assigns content of s to StringBuffer. Clears s.

Buffer([W]String& text, int length)

Assigns content of s to StringBuffer and trims the length. Clears s.