string class by value built-in

Text string

A mutable sequence of bytes, usually holding UTF-8 text. Strings are value types, so assigning one string to another makes a copy. Lengths, positions and indices are counted in bytes, not characters. Numbers and booleans can be assigned to or concatenated with a string directly, see formatInt() and formatFloat() for control over the formatting.

Constructors

string()
Creates an empty string
string(const string&in)
Creates a copy of another string

Functions

bool empty() const
Returns true if the string has no content
void erase(uint pos, int count = -1)
Removes a part of the string
int findFirst(const string&in, uint start = 0) const
Finds the first occurrence of a substring
int findFirstNotOf(const string&in, uint start = 0) const
Finds the first byte that is none of the given characters
int findFirstOf(const string&in, uint start = 0) const
Finds the first byte that is one of the given characters
int findLast(const string&in, int start = -1) const
Finds the last occurrence of a substring
int findLastNotOf(const string&in, int start = -1) const
Finds the last byte that is none of the given characters
int findLastOf(const string&in, int start = -1) const
Finds the last byte that is one of the given characters
void insert(uint pos, const string&in other)
Inserts another string at the given position
void resize(uint)
Changes the length of the string
array<string>@ split(const string&in) const
Splits the string into parts at every occurrence of a delimiter
string substr(uint start = 0, int count = -1) const
Returns a part of the string

Operators

string opAdd(const string&in) const +
Returns a new string with another string appended
string opAdd(double) const +
Returns a new string with a number appended as text
string opAdd(float) const +
Returns a new string with a number appended as text
string opAdd(int64) const +
Returns a new string with an integer appended as decimal text
string opAdd(uint64) const +
Returns a new string with an unsigned integer appended as decimal text
string opAdd(bool) const +
Returns a new string with true or false appended
string opAdd_r(double) const +
Returns a new string with a number prepended as text
string opAdd_r(float) const +
Returns a new string with a number prepended as text
string opAdd_r(int64) const +
Returns a new string with an integer prepended as decimal text
string opAdd_r(uint64) const +
Returns a new string with an unsigned integer prepended as decimal text
string opAdd_r(bool) const +
Returns a new string with true or false prepended
string& opAddAssign(const string&in) +=
Appends another string
string& opAddAssign(double) +=
Appends a number converted to text
string& opAddAssign(float) +=
Appends a number converted to text
string& opAddAssign(int64) +=
Appends an integer converted to decimal text
string& opAddAssign(uint64) +=
Appends an unsigned integer converted to decimal text
string& opAddAssign(bool) +=
Appends true or false
string& opAssign(const string&in other) =
Replaces the content with a copy of another string
string& opAssign(double) =
Replaces the content with a number converted to text
string& opAssign(float) =
Replaces the content with a number converted to text
string& opAssign(int64) =
Replaces the content with an integer converted to decimal text
string& opAssign(uint64) =
Replaces the content with an unsigned integer converted to decimal text
string& opAssign(bool) =
Replaces the content with true or false
int opCmp(const string&in) const <
Compares two strings, used by the <, <=, > and >= operators
bool opEquals(const string&in) const ==
Returns whether both strings have the same content
uint8& opIndex(uint) []
Accesses a single byte of the string
const uint8& opIndex(uint) const []
Reads a single byte of the string

Properties

uint length read-only
Length of the string in bytes

Function documentation

void string::erase(uint pos, int count = -1)

Removes a part of the string

Parameters
pos Byte position of the first removed byte
count Number of bytes to remove, or -1 for the rest of the string

A position greater than string::length raises a script exception. A negative count, or one that reaches past the end, removes everything up to the end.

int string::findFirst(const string&in, uint start = 0) const

Finds the first occurrence of a substring

Parameters
start Byte position where the search begins, a position past the end finds nothing
Returns Byte position of the match, or -1 if not found

Searches for the given substring from start towards the end.

int string::findFirstNotOf(const string&in, uint start = 0) const

Finds the first byte that is none of the given characters

Parameters
start Byte position where the search begins
Returns Byte position of the match, or -1 if not found

The first argument is a set of characters to skip, e.g. " \t" to find the first non-blank character.

int string::findFirstOf(const string&in, uint start = 0) const

Finds the first byte that is one of the given characters

Parameters
start Byte position where the search begins, a position past the end finds nothing
Returns Byte position of the match, or -1 if not found

The first argument is a set of characters, any of which counts as a match.

int string::findLast(const string&in, int start = -1) const

Finds the last occurrence of a substring

Parameters
start Last byte position where a match may begin, -1 or any position past the end searches the whole string
Returns Byte position of the match, or -1 if not found

Searches for the given substring backwards, only matches that begin at start or before it are found.

int string::findLastNotOf(const string&in, int start = -1) const

Finds the last byte that is none of the given characters

Parameters
start Byte position where the backward search begins, -1 or any position past the end searches the whole string
Returns Byte position of the match, or -1 if not found

The first argument is a set of characters to skip, e.g. " \t" to find the last non-blank character.

int string::findLastOf(const string&in, int start = -1) const

Finds the last byte that is one of the given characters

Parameters
start Byte position where the backward search begins, -1 or any position past the end searches the whole string
Returns Byte position of the match, or -1 if not found

The first argument is a set of characters, any of which counts as a match.

void string::insert(uint pos, const string&in other)

Inserts another string at the given position

Parameters
pos Byte position where the text is inserted
other Text to insert

A position greater than string::length raises a script exception, a position equal to it appends.

void string::resize(uint)

Changes the length of the string

Takes the new length in bytes. A shorter length cuts the string, a longer one pads it with zero bytes.

array<string>@ string::split(const string&in) const

Splits the string into parts at every occurrence of a delimiter

Returns New array of the parts

The delimiters themselves are not included. Adjacent delimiters, or one at the start or the end, produce empty parts, so the result always has one more element than there are delimiters. An empty delimiter returns the whole string as the only element.

string string::substr(uint start = 0, int count = -1) const

Returns a part of the string

Parameters
start Byte position where the part begins
count Number of bytes to take, or -1 for the rest of the string

A start at or past the end gives an empty string. A negative count, or one that reaches past the end, takes everything up to the end.

Operator documentation

string& string::opAssign(const string&in other) =

Replaces the content with a copy of another string

If other is a SSO instance, the copy is as well, otherwise a copy is allocated using the default

operator new[] 

. The actual string size isn't taken into account. See Small string optimization for more information.

string& string::opAssign(double) =

Replaces the content with a number converted to text

Uses up to 6 decimal places with trailing zeros removed, but always keeps one digit after the decimal point.

string& string::opAssign(float) =

Replaces the content with a number converted to text

Uses up to 6 decimal places with trailing zeros removed, but always keeps one digit after the decimal point.

int string::opCmp(const string&in) const <

Compares two strings, used by the <, <=, > and >= operators

Returns Negative value if this string sorts first, zero if both are equal, positive value otherwise

Compares byte by byte, so uppercase letters sort before lowercase ones.

bool string::opEquals(const string&in) const ==

Returns whether both strings have the same content

The comparison is exact and case-sensitive.

uint8& string::opIndex(uint) []

Accesses a single byte of the string

The byte can be read and changed in place. An index equal to or greater than string::length raises a script exception.

const uint8& string::opIndex(uint) const []

Reads a single byte of the string

An index equal to or greater than string::length raises a script exception.

Property documentation

uint string::length read-only

Length of the string in bytes

Read-only, use string::resize() to change it. A character outside ASCII takes more than one byte in UTF-8.