Get Involved

String

A String object owns a single block of memory allocated on the heap. The memory block is freed when the String is destroyed.

String objects often contain UTF-8-encoded text, but this is isn't a requirement. In general, a String can hold any kind of data. For example, FileSystem::loadBinary returns raw file contents in a String object.

Even though String objects aren't required to contain text, they provide many member functions to help manipulate text, such as trim(), splitByte() and upperAsc(). These text manipulation functions are generally intended to work with UTF-8-encoding strings, but most of them will also work with any 8-bit format compatible with ASCII, such as ISO 8859-1 or Windows-1252.

When a String object does contain text, the text string is generally not 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.

Several String functions accept byte offset arguments, such as subStr(), left() and right(). Be aware that when a StringView contains UTF-8-encoded text, byte offsets are not necessarily the same as the number of characters (Unicode points) encoded by the string. 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::String() [code]

Constructs an empty string.

  String::String(StringView other) [code]
  String::String(const String& other) [code]
  String::String(const char* s) [code]
  String::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(String&& other) [code]

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

  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.

template <typename = void>
void String::operator=(StringView 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 String::operator=(const String& other) [code]

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

String::operator const StringView&() const [code]

Conversion operator. Makes String implicitly convertible to StringView.

 const StringView& String::view() const [code]

Explicitly creates a StringView. No new memory is allocated by this function.

 void String::clear() [code]

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

void String::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 MemOutStream instead, then convert to String at the final step by calling MemOutStream::moveToString().

 static String 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 String::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.

 static String String::adopt(char* bytes, u32 numBytes) [code]

Returns a String that takes ownership of the memory block at bytes. This memory block must have been allocated on the heap.

 char* String::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 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 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.

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

Subscript operators with runtime bounds checking.

 const char& String::back(s32 ofs = -1) const [code]
 char& String::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