The string object supports a number of operators, and has several class methods and supporting global functions to facilitate the manipulation of strings.
Unless otherwise stated, all methods and functions work on the individual bytes in the string. They do not attempt to understand encoded characters, e.g. UTF-8 encoded characters that can take up to 4 bytes.
= assignment
The assignment operator copies the content of the right hand string into the left hand string.
Assignment of primitive types is allowed, which will do a default transformation of the primitive to a string.
+, += concatenation
The concatenation operator appends the content of the right hand string to the end of the left hand string.
Concatenation of primitives types is allowed, which will do a default transformation of the primitive to a string.
==, != equality
Compares the content of the two strings.
<, >, <=, >= comparison
Compares the content of the two strings. The comparison is done on the byte values in the strings, which may not correspond to alphabetical comparisons for some languages.
[] index operator
The index operator gives access to a single byte in the string.
uint length() const
Returns the length of the string.
void resize(uint)
Sets the length of the string.
bool isEmpty() const
Returns true if the string is empty, i.e. the length is zero.
string substr(uint start = 0, int count = -1) const
Returns a string with the content starting at start and the number of bytes given by count. The default arguments will return the whole string as the new string.
void insert(uint pos, const string &in other)
Inserts another string other at position pos in the original string.
void erase(uint pos, int count = -1)
Erases a range of characters from the string, starting at position pos and counting count characters.
int findFirst(const string &in str, uint start = 0) const
Find the first occurrence of the value str in the string, starting at start. If no occurrence is found a negative value will be returned.
int findLast(const string &in str, int start = -1) const
Find the last occurrence of the value str in the string. If start is informed the search will begin at that position, i.e. any potential occurrence after that position will not be searched. If no occurrence is found a negative value will be returned.
int findFirstOf(const string &in chars, int start = 0) const
int findFirstNotOf(const string &in chars, int start = 0) const
int findLastOf(const string &in chars, int start = -1) const
int findLastNotOf(const string &in chars, int start = -1) const
The first variant finds the first character in the string that matches on of the characters in chars, starting at start. If no occurrence is found a negative value will be returned.
The second variant finds the first character that doesn't match any of those in chars. The third and last variant are the same except they start the search from the end of the string.
int regexFind(const string &in regex, uint start = 0, uint &out lengthOfMatch = void) const
This function uses the popular ECMAscript syntax to find matches using regular expressions. To learn about the exact syntax do a search for C++ ECMAScript syntax on the internet.
The search works on a byte-by-byte basis, so UTF-8 characters above the standard ASCII aren't classified as letters, since they occupy multple bytes. However, since all bytes in the multibyte sequence are above 127 there is at least no risk of unexpected matches.
Here's an example of how to match a word that potentially contains characters beyond the standard ASCII:
string str = 'Jönsson';
uint length;
int pos = str.regexFind('[[:alpha:]\x80-\xff]+', 0, length);
array<string>@ split(const string &in delimiter) const
Splits the string in smaller strings where the delimiter is found.
string join(const array<string> &in arr, const string &in delimiter)
Concatenates the strings in the array into a large string, separated by the delimiter.
uint scan(const string&in str, ?&out ...)
Parses the string for subsequent values of the type matching the type of each argument. All primitive types and the string type are supported.
Returns the number of values that were successfully parsed.
uint scanned = scan('123 3.14 hello', i, f, s);
int64 parseInt(const string &in str, uint base = 10, uint &out byteCount = 0)
uint64 parseUInt(const string &in str, uint base = 10, uint &out byteCount = 0)
Parses the string for an integer value. The base can be 10 or 16 to support decimal numbers or hexadecimal numbers. If byteCount is provided it will be set to the number of bytes that were considered as part of the integer value.
double parseFloat(const string &in, uint &out byteCount = 0)
Parses the string for a floating point value. If byteCount is provided it will be set to the number of bytes that were considered as part of the value.
string format(const string&in fmt, const ?&in ...)
Formats a string with multiple values. The logic will replace each {} found in the fmt string with the corresponding argument. Arguments can be given as any of the primitive types or the the string type.
string result = format('{} {} {}', 123, true, 'hello');
string formatInt(int64 val, const string &in options = '', uint width = 0)
string formatUInt(uint64 val, const string &in options = '', uint width = 0)
string formatFloat(double val, const string &in options = '', uint width = 0, uint precision = 0)
The format functions takes a string that defines how the number should be formatted. The string is a combination of the following characters:
Examples:
// Left justify number in string with 10 characters string justified = formatInt(number, 'l', 10); // Create hexadecimal representation with capital letters, right justified string hex = formatInt(number, 'H', 10); // Right justified, padded with zeroes and two digits after decimal separator string num = formatFloat(number, '0', 8, 2);
1.14.0