String

A String object owns a single block of memory, allocated on the heap, that is generally intended (but not required) to contain UTF-8-encoded text. Many String functions also work with text in any 8-bit format compatible with ASCII, such as ISO 8859-1 or Windows-1252. The memory block is freed when the String is destroyed.

The String class uses the same memory representation as Buffer but provides member functions suitable for string manipulation, such as trim(), split() and concatenation using the + operator.

String objects are not automatically null-terminated. If you need a null-terminated string (for example, to pass to a third-party library), you must add a null terminator byte to the string yourself. The null terminator then counts towards the number of bytes in numBytes. A convenience function withNullTerminator() is provided for this.

Strictly speaking, String objects are not required to contain text, though many member functions expect it. Internally, a String just contains a sequence of bytes. The main reason to prefer a variable of type String over Buffer is to express the intention for the allocated memory to contain text and/or for the convenience of having the String member functions available.

For more information, see Unicode Support.

Header File

#include <ply-runtime/container/String.h>

Also included from <ply-runtime/Base.h>.

Data Members

char* bytes [code]

The bytes.

u32 numBytes [code]

The number of bytes.

Member Functions

String() [code]

Constructs an empty string.

String(StringView other) [code]
String(const String& other) [code]
String(const char* s) [code]
String(char u) [code]

Each of these constructors constructs a copy of its argument. A new memory block is allocated on the heap and the contents of the argument are copied into it.

String(String&& other) [code]

Move constructor. The other is reset to an empty string.

String(HybridString&& other) [code]

Conditionally moves or copies from other. If other owns its memory, the new String takes ownership of that memory and other is reset to an empty string. If other does not own its memory, a new memory block is allocated on the heap and the contents of other are copied into it.

void operator=(const String& other) [code]

Copy assignment operator. If this String already owns a memory block, it is destroyed. A new memory block is allocated on the heap and the contents of other are copied into it.

void operator=(String&& other) [code]

Move assignment operator. If this String already owns a memory block, it is destroyed. other is reset to an empty string.

static String moveFromBuffer(Buffer&& buffer) [code]

Converts a Buffer to a String. No new memory is allocated by this function. The returned String takes ownership of the memory block previously owned by buffer, and buffer is reset to an empty buffer.

String str = String::moveFromBuffer(std::move(buffer));
operator const StringView&() const [code]

Conversion operator. Makes String implicitly convertible to StringView.

const StringView& view() const [code]
const ConstBufferView& bufferView() const [code]
const BufferView& bufferView() [code]

Explicitly creates a StringView, BufferView or ConstBufferView into the given string. No new memory is allocated by these functions.

void clear() [code]

If this String owns a memory block, it is destroyed and the String is reset to an empty string.

void operator+=(StringView other) [code]

Appends the contents of other to this string. This function performs a heap reallocation each time it is called. If you wish to concatenate several strings together, consider using a StringWriter instead, then convert to String at the final step by calling StringWriter::moveToString().

static String allocate(u32 numBytes) [code]

Returns a String that owns a newly allocated block of memory. The contents of the memory block are uninitialized. Note that this is a static function; the new String is returned explicitly.

String str = String::allocate(100);
void resize(u32 numBytes) [code]

Resize the owned memory block. If numBytes is greater than the current size, new space added to the memory block is left uninitialized.

char* release() [code]

Returns a pointer to the owned memory block while releasing ownership. The String is reset to an empty string.

template <typename Args>
static String format(StringView fmt, const Args& args) [code]

Template function that expands the format string fmt using the given arguments and returns a new String containing the result.

String str = String::format("The answer is {}.\n", 42);

For more information, see Converting Values to Text.

template <typename T>
static String from(const T& value) [code]

Template function that converts the provided argument to a string.

String s = String::from(123.456);

For more information, see Converting Values to Text.

static String fromChunks(ChunkCursor&& start) [code]
static String fromChunks(ChunkCursor&& start, const ChunkCursor& end) [code]

Returns a String that owns a newly allocated block of memory containing a copy of the data contained in some (possible multiple) chunks. The first form of fromChunks copies all the data from start up to the end of the chunk list. The second form copies all the data between start and end.

The first argument must be an rvalue reference to a ChunkCursor which might be moved from (reset to an empty state) as a result of this call. This requirement enables an optimization: If start is the sole reference to the start of a single ChunkListNode, no data is copied; instead, the chunk's memory block is truncated and ownership is passed directly to the Buffer. To satisfy this requirement, either use std::move() or pass a temporary copy of a ChunkCursor.

This function is used internally by StringOutStream::moveToString().

const char& operator[](u32 index) const [code]
char& operator[](u32 index) [code]

Subscript operators with runtime bounds checking.

const char& back(s32 ofs = -1) const [code]
char& back(s32 ofs = -1) [code]

Reverse subscript operators with runtime bounds checking. ofs must be less than zero. By default, returns the last byte in the string. Equivalent to str[str.numBytes + ofs].

Members Inherited From ply::StringMixin

  • template <typename T>
    T to(const T& defaultValue = subst::createDefault<T>()) const
  • explicit operator bool() const
  • bool isEmpty() const
  • StringView subStr(u32 start) const
  • StringView subStr(u32 start, u32 numBytes) const
  • StringView left(u32 numBytes) const
  • StringView shortenedBy(u32 numBytes) const
  • StringView right(u32 numBytes) const
  • friend s32 compare(const Derived& str0, const Derived& str1)
  • bool operator<(StringView other) const
  • bool operator==(StringView src) const
  • bool operator!=(StringView src) const
  • String operator+(StringView other) const
  • String operator*(u32 count) const
  • s32 findByte(char matchByte, u32 startPos = 0) const
  • template <typename MatchFuncOrChar>
    s32 findByte(const MatchFuncOrChar& matchFuncOrByte, u32 startPos = 0) const
  • template <typename MatchFuncOrChar>
    s32 rfindByte(const MatchFuncOrChar& matchFuncOrByte, u32 startPos) const
  • template <typename MatchFuncOrChar>
    s32 rfindByte(const MatchFuncOrChar& matchFuncOrByte) const
  • bool startsWith(StringView arg) const
  • bool endsWith(StringView arg) const
  • StringView trim(bool* matchFunc(char) = isWhite, bool left = true, bool right = true) const
  • StringView ltrim(bool* matchFunc(char) = isWhite) const
  • StringView rtrim(bool* matchFunc(char) = isWhite) const
  • String join(ArrayView<const StringView> comps) const
  • Array<StringView> splitByte(char sep) const
  • String upperAsc() const
  • String lowerAsc() const
  • String reversedBytes() const
  • String reversedUTF8() const
  • String filterBytes(char* filterFunc(char)) const
  • bool includesNullTerminator() const
  • HybridString withNullTerminator() const
  • StringView withoutNullTerminator() const
  • template <typename Hasher>
    void appendTo(Hasher& hasher) const