Standard String Functions

The following standard methods (mostly defined in the MoreStringPackage but excluded if using a raw Engine) operate on strings (and possibly characters).

FunctionParameter(s)Description
len method and propertynonereturns the number of characters (not number of bytes) in the string
bytes method and propertynonereturns the number of bytes making up the UTF-8 string; for strings containing only ASCII characters, this is much faster than len
to_blob
(not available under no_index)		noneconverts the string into an UTF-8 encoded byte-stream and returns it as a BLOB.
to_chars
(not available under no_index)		nonesplits the string by individual characters, returning them as an array
getposition, counting from end if < 0gets the character at a certain position (() if the position is not valid)
set
  1. position, counting from end if < 0
  2. new character
sets a certain position to a new character (no effect if the position is not valid)
pad
  1. target length
  2. character/string to pad
pads the string with a character or a string to at least a specified length
append, += operatoritem to appendadds the display text of an item to the end of the string
removecharacter/string to removeremoves a character or a string from the string
pop(optional) number of characters to remove, none if ≤ 0, entire string if ≥ lengthremoves the last character (if no parameter) and returns it (() if empty); otherwise, removes the last number of characters and returns them as a string
clearnoneempties the string
truncatetarget lengthcuts off the string at exactly a specified number of characters
to_uppernoneconverts the string/character into upper-case as a new string/character and returns it
to_lowernoneconverts the string/character into lower-case as a new string/character and returns it
make_uppernoneconverts the string/character into upper-case
make_lowernoneconverts the string/character into lower-case
trimnonetrims the string of whitespace at the beginning and end
containscharacter/sub-string to search forchecks if a certain character or sub-string occurs in the string
starts_withstringreturns true if the string starts with a certain string
ends_withstringreturns true if the string ends with a certain string
index_of
  1. character/sub-string to search for
  2. (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
  1. start position, counting from end if < 0
  2. (optional) number of characters to extract, none if ≤ 0, to end if omitted
extracts a sub-string
sub_stringrange of characters to extract, from beginning if ≤ 0, to end if ≥ lengthextracts a sub-string
split
(not available under no_index)		nonesplits the string by whitespaces, returning an array of string segments
split
(not available under no_index)		position to split at (in number of characters), counting from end if < 0, end if ≥ lengthsplits the string into two segments at the specified character position, returning an array of two string segments
split
(not available under no_index)
  1. delimiter character/string
  2. (optional) maximum number of segments, 1 if < 1
splits the string by the specified delimiter, returning an array of string segments
split_rev
(not available under no_index)
  1. delimiter character/string
  2. (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
  1. start position, counting from end if < 0
  2. (optional) number of characters to retain, none if ≤ 0, to end if omitted
retains only a portion of the string
croprange of characters to retain, from beginning if ≤ 0, to end if ≥ lengthretains only a portion of the string
replace
  1. target character/sub-string
  2. replacement character/string
replaces a sub-string with another
chars method and property
  1. (optional) start position, counting from end if < 0
  2. (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.

Standard Operators

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.

OperatorDescription
+, +=character/string concatenation
-, -=remove character/sub-string from string
==equals to
!=not equals to
>greater than
>=greater than or equals to
<less than
<=less than or equals to

For convenience, when BLOB’s are appended to a string, it is treated as UTF-8 encoded data 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.

OperatorDescription
+, +=
(not available under no_index)		append a BLOB (as a UTF-8 encoded string) to 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;