Standard String Functions¶

The following standard methods operate on strings (and possibly characters).

Function	Parameter(s)	Description
`len` method and property	none	returns the number of characters (not number of bytes) in the string
`bytes` method and property	none	returns the number of bytes making up the UTF-8 string; for strings containing only ASCII characters, this is much faster than `len`
`is_empty` method and property	none	returns `true` if the string is empty
`to_blob`	none	converts the string into an UTF-8 encoded byte-stream and returns it as a BLOB.
`to_chars`	none	splits the string by individual characters, returning them as an array
`get`	position, counting from end if < 0	gets the character at a certain position (`()` if the position is not valid)
`set`	position, counting from end if < 0 new character	sets a certain position to a new character (no effect if the position is not valid)
`pad`	target length character/string to pad	pads the string with a character or a string to at least a specified length
`append`, `+=` operator	item to append	adds the display text of an item to the end of the string
`remove`	character/string to remove	removes a character or a string from the string
`pop`	(optional) number of characters to remove, none if ≤ 0, entire string if ≥ length	removes the last character (if no parameter) and returns it (`()` if empty); otherwise, removes the last number of characters and returns them as a string
`clear`	none	empties the string
`truncate`	target length	cuts off the string at exactly a specified number of characters
`to_upper`	none	converts the string/character into upper-case as a new string/character and returns it
`to_lower`	none	converts the string/character into lower-case as a new string/character and returns it
`make_upper`	none	converts the string/character into upper-case
`make_lower`	none	converts the string/character into lower-case
`trim`	none	trims the string of whitespace at the beginning and end
`contains`	character/sub-string to search for	checks if a certain character or sub-string occurs in the string
`starts_with`	string	returns `true` if the string starts with a certain string
`ends_with`	string	returns `true` if the string ends with a certain string
`min`	first character/string second character/string	returns the smaller of two characters/strings
`max`	first character/string second character/string	returns the larger of two characters/strings
`index_of`	character/sub-string to search for (optional) start position, counting from end if < 0, end if ≥ length	returns the position that a certain character or sub-string occurs in the string, or −1 if not found
`sub_string`	start position, counting from end if < 0 (optional) number of characters to extract, none if ≤ 0, to end if omitted	extracts a sub-string
`sub_string`	range of characters to extract, from beginning if ≤ 0, to end if ≥ length	extracts a sub-string
`split`	none	splits the string by whitespaces, returning an array of string segments
`split`	position to split at (in number of characters), counting from end if < 0, end if ≥ length	splits the string into two segments at the specified character position, returning an array of two string segments
`split`	delimiter character/string (optional) maximum number of segments, 1 if < 1	splits the string by the specified delimiter, returning an array of string segments
`split_rev`	delimiter character/string (optional) maximum number of segments, 1 if < 1	splits the string by the specified delimiter in reverse order, returning an array of string segments
`crop`	start position, counting from end if < 0 (optional) number of characters to retain, none if ≤ 0, to end if omitted	retains only a portion of the string
`crop`	range of characters to retain, from beginning if ≤ 0, to end if ≥ length	retains only a portion of the string
`replace`	target character/sub-string replacement character/string	replaces a sub-string with another
`chars` method and property	(optional) start position, counting from end if < 0 (optional) number of characters to iterate, none if ≤ 0	allows iteration of the characters inside the string

Beware that functions that involve indexing into a string to get at individual characters, e.g. sub_string, require walking through the entire UTF-8 encoded bytes stream to extract individual Unicode characters and counting them, which can be slow for long strings.

Building Strings¶

strings can be built from segments via the + operator.

Operator	Description
string `+=` item	convert the item into a string, then append it to the first string
string `+` item	convert the item into a string, then concatenate them as a new string
item `+` string	convert the item into a string, then concatenate them as a new string

let x = 42;

// Build string with '+'
let s = "The answer is: " + x + "!!!";

// Prints: "The answer is: 42!!!"
print(s);

Standard Operators Between Strings and/or Characters¶

The following standard operators inter-operate between strings and/or characters.

When one (or both) of the operands is a character, it is first converted into a one-character string before running the operator.

Operator	Description
`+`, `+=`	character/string concatenation
`-`, `-=`	remove [character](../../strings-chars.md/sub-string from string
`==`	equals to
`!=`	not equals to
`>`	greater than
`>=`	greater than or equals to
`<`	less than
`<=`	less than or equals to

Interop with BLOB's¶

For convenience, when a BLOB is appended to a string, or vice versa, it is treated as a UTF-8 encoded byte stream and automatically first converted into the appropriate string value.

That is because it is rarely useful to append a BLOB into a string, but extremely useful to be able to directly manipulate UTF-8 encoded text.

Operator	Description
`+`, `+=`	append a BLOB (as a UTF-8 encoded byte stream) to the end of the string
`+`	concatenate a BLOB (as a UTF-8 encoded byte stream) with a string

Examples¶

let full_name == " Bob C. Davis ";
full_name.len == 14;

full_name.trim();
full_name.len == 12;
full_name == "Bob C. Davis";

full_name.pad(15, '$');
full_name.len == 15;
full_name == "Bob C. Davis$$$";

let n = full_name.index_of('$');
n == 12;

full_name.index_of("$$", n + 1) == 13;

full_name.sub_string(n, 3) == "$$$";
full_name.sub_string(n..n+3) == "$$$";

full_name.truncate(6);
full_name.len == 6;
full_name == "Bob C.";

full_name.replace("Bob", "John");
full_name.len == 7;
full_name == "John C.";

full_name.contains('C') == true;
full_name.contains("John") == true;

full_name.crop(5);
full_name == "C.";

full_name.crop(0, 1);
full_name == "C";

full_name.clear();
full_name.len == 0;