Header file:<ply-base.h>Namespace:plyStrings

Plywood strings are general-purpose blocks of memory allocated from the heap. They're often used to manipulate text, but they can store binary data as well. There are three main classes for working with strings:

• String owns a block of memory and frees it when the destructor is called.
• StringView is a read-only view into a block of memory.
• MutStringView is a read-write view into a block of memory.

These classes all use 32-bit integers for indexing, which means they can refereance a maximum of roughly 4 GB of memory.

Plywood strings aren't null-terminated unless you add an explicit null byte to the end. This is sometimes necessary when passing strings to legacy functions that expect a null terminator.

String str = "Hello, world!";
// The legacy function 'puts' expects a null terminator:
puts((str + '\0').bytes());

These classes aren't thread-safe. Functions that read from the same string can be called concurrently from separate threads, but functions that modify the same string must not be called concurrently.

Common String Methods

The following member functions are implemented in both String and StringView:

Accessing String Bytes

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

Subscript operator with runtime bounds checking. Can be used to read individual bytes or modify indvidual bytes (for String only). If index is out of range, an assert will be triggered.

String str = "Hello, world!";
char c = str[4];  // 'o'
str[0] = 'J';     // "Jello, world!"

char& back(s32 ofs)
const char& back(s32 ofs) const

Returns a reference to a byte relative to the end of the string. By default, returns the last byte. Pass -2 for the second-to-last byte, and so on.

char* begin()
const char* begin() const

Returns a pointer to the first byte of the string. Suitable for range-for iteration.

char* end()
const char* end() const

Returns a pointer to one past the last byte of the string. Suitable for range-for iteration.

String str = "Hello";
for (char c : str) {
    // Iterates over 'H', 'e', 'l', 'l', 'o'
}

Examining String Contents

bool isEmpty() const

Returns true if the string contains no bytes.

bool startsWith(StringView arg) const

Returns true if the string begins with the specified prefix.

bool endsWith(StringView arg) const

Returns true if the string ends with the specified suffix.

s32 find(StringView substr,  u32 startPos) const

Searches for the first occurrence of substr starting from startPos. Returns the index of the first match, or -1 if not found.

s32 find(const MatchFunc& matchFunc,  u32 startPos) const

Searches for the first byte that satisfies the match function starting from startPos. Returns the index of the first match, or -1 if not found.

s32 reverseFind(StringView substr,  s32 startPos) const

Searches backwards for the last occurrence of substr starting from startPos (or the end if -1). Returns the index of the match, or -1 if not found.

s32 reverseFind(const MatchFunc& matchFunc,  s32 startPos) const

Searches backwards for the last byte that satisfies the match function. Returns the index of the match, or -1 if not found.

Creating Subviews

StringView substr(u32 start) const

Returns a view of the substring starting at start and extending to the end of the string.

StringView substr(u32 start,  u32 numBytes) const

Returns a view of the substring starting at start with length numBytes.

StringView left(u32 numBytes) const

Returns a view of the first numBytes bytes of the string.

StringView shortenedBy(u32 numBytes) const

Returns a view of the string with numBytes removed from the end.

StringView right(u32 numBytes) const

Returns a view of the last numBytes bytes of the string.

StringView trim(bool,  bool left,  bool right) const

Returns a view with matching characters removed from both ends. By default, trims whitespace characters.

StringView trimLeft(bool) const

Returns a view with matching characters removed from the beginning. By default, trims whitespace.

StringView trimRight(bool) const

Returns a view with matching characters removed from the end. By default, trims whitespace.

Creating New Strings

String upper() const

Returns a new string with all ASCII lowercase letters converted to uppercase. Non-ASCII bytes are unchanged.

String lower() const

Returns a new string with all ASCII uppercase letters converted to lowercase. Non-ASCII bytes are unchanged.

Array<StringView> split(StringView separator) const

Splits the string at each occurrence of separator and returns an array of views.

String join(ArrayView<const StringView> comps) const

Joins an array of string components using this string as the separator.

String operator+(StringView other)

Returns a new string with the contents of this string followed by the contents of other.

Pattern Matching

template <typename... Args> bool match(StringView pattern,  const Args&& args)

Matches the string against a pattern containing {} placeholders. If the match succeeds, captured values are written to the output arguments.

String

The String class owns a block of memory allocated from the Plywood heap. The memory is freed when the String object is destroyed.

String objects are movable, copyable and construct to an empty string by default. In addition to the common string functions listed in the previous section, they provide the following member functions:

Type Conversions

String(StringView other)

Constructs a new string by copying the contents of a StringView.

String(const char* s)

Constructs a string from a null-terminated C string. The characters are copied into a newly allocated memory block except for the null terminator.

operator StringView() const

Implicitly converts the string to a StringView. This allows String objects to be passed directly to functions that expect StringView parameters.

Modifying String Contents

void clear()

Frees the internal memory block and resets to an empty state.

void operator+=(StringView other)

Appends the bytes from other to this string, reallocating if necessary.

void resize(u32 numBytes)

Resizes the string to the specified length, reallocating if necessary. New bytes are uninitialized.

char* release()

Releases ownership of the internal memory block and returns a pointer to it. The caller is responsible for freeing the memory later using Heap::free.

Creating New Strings

static String allocate(u32 numBytes)

Allocates a new string of the specified size. The contents are uninitialized.

static String adopt(char* bytes,  u32 numBytes)

Creates a String object that takes ownership of an existing buffer. The buffer must have been allocated from the Plywood heap and will be freed when the String is destroyed.

Formatting

static String format(StringView fmt,  const Args& args)

Creates a formatted string using {} placeholders. Arguments are converted to text and substituted in order.

[TBD]

static String fromDateTime(const DateTime& dateTime)

Creates a string representation of a DateTime object using a format string. See the Time and Date chapter for format specifiers.

StringView

By convention, Plywood passes StringView to functions by value instead of by reference, since copying a StringView doesn't copy the underlying bytes.

[TBD]

MutStringView

By convention, Plywood passes MutStringView objects to functions by value instead of by reference.

[TBD]