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
-
The bytes.
-
The number of bytes.
Member Functions
-
Constructs an empty string.
-
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.
-
Move constructor. The
other
is reset to an empty string. -
Conditionally moves or copies from
other
. Ifother
owns its memory, the newString
takes ownership of that memory andother
is reset to an empty string. Ifother
does not own its memory, a new memory block is allocated on the heap and the contents ofother
are copied into it. -
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 ofother
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 toStringView
. -
Explicitly creates a
StringView
. No new memory is allocated by this function. -
If this
String
owns a memory block, it is destroyed and theString
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 aMemOutStream
instead, then convert toString
at the final step by callingMemOutStream::moveToString()
. -
Returns a
String
that owns a newly allocated block of memory. The contents of the memory block are uninitialized. Note that this is astatic
function; the newString
is returned explicitly.String str = String::allocate(100);
-
Resize the owned memory block. If
numBytes
is greater than the current size, new space added to the memory block is left uninitialized. -
Returns a
String
that takes ownership of the memory block atbytes
. This memory block must have been allocated on the heap. -
Returns a pointer to the owned memory block while releasing ownership. The
String
is reset to an empty string. -
Template function that expands the format string
fmt
using the given arguments and returns a newString
containing the result.String str = String::format("The answer is {}.\n", 42);
For more information, see Converting Values to Text.
-
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.
-
Reverse subscript operators with runtime bounds checking.
ofs
must be less than zero. By default, returns the last byte in the string. Equivalent tostr[str.numBytes + ofs]
.
Members Inherited From ply::StringMixin
template <typename T>
T StringMixin::to(const T& defaultValue = subst::createDefault<T>()) const
explicit StringMixin::operator bool() const
bool StringMixin::isEmpty() const
StringView StringMixin::subStr(u32 start) const
StringView StringMixin::subStr(u32 start, u32 numBytes) const
StringView StringMixin::left(u32 numBytes) const
StringView StringMixin::shortenedBy(u32 numBytes) const
StringView StringMixin::right(u32 numBytes) const
String StringMixin::operator+(StringView other) const
String StringMixin::operator*(u32 count) const
s32 StringMixin::findByte(char matchByte, u32 startPos = 0) const
template <typename MatchFuncOrChar>
s32 StringMixin::findByte(const MatchFuncOrChar& matchFuncOrByte, u32 startPos = 0) const
template <typename MatchFuncOrChar>
s32 StringMixin::rfindByte(const MatchFuncOrChar& matchFuncOrByte, u32 startPos) const
template <typename MatchFuncOrChar>
s32 StringMixin::rfindByte(const MatchFuncOrChar& matchFuncOrByte) const
bool StringMixin::startsWith(StringView arg) const
bool StringMixin::endsWith(StringView arg) const
StringView StringMixin::trim(bool* matchFunc(char) = isWhite, bool left = true, bool right = true) const
StringView StringMixin::ltrim(bool* matchFunc(char) = isWhite) const
StringView StringMixin::rtrim(bool* matchFunc(char) = isWhite) const
String StringMixin::join(ArrayView<const StringView> comps) const
auto StringMixin::splitByte(char sep) const
String StringMixin::upperAsc() const
String StringMixin::lowerAsc() const
String StringMixin::reversedBytes() const
String StringMixin::reversedUTF8() const
String StringMixin::filterBytes(char* filterFunc(char)) const
bool StringMixin::includesNullTerminator() const
HybridString StringMixin::withNullTerminator() const
StringView StringMixin::withoutNullTerminator() const