Built-in String Functions

Standard Functions

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

FunctionNot available underParameter(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
pad1) target length
2) character/string to pad
pads the string with a character or a string to at least a specified length
appendcharacter/string to appendadds a character or a string to the end of another string
removecharacter/string to removeremoves a character or a string from the string
clearnoneempties the string
truncatetarget lengthcuts off the string at exactly a specified number of characters
containscharacter/sub-string to search forchecks if a certain character or sub-string occurs in the string
index_of1) character/sub-string to search for
2) (optional) start index, counting from end if < 0, end if ≥ length
returns the index that a certain character or sub-string occurs in the string, or −1 if not found
sub_string1) start index, counting from end if < 0
2) (optional) number of characters to extract, none if < 0
extracts a sub-string (to the end of the string if length is not specified)
splitno_indexnonesplits the string by individual characters, returning an array of characters
splitno_indexPosition 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
splitno_index1) 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_revno_index1) 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
crop1) start index, counting from end if < 0
2) (optional) number of characters to retain, none if < 0
retains only a portion of the string
replace1) target character/sub-string
2) replacement character/string
replaces a sub-string with another
trimnonetrims the string of whitespace at the beginning and end

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

Examples


#![allow(unused)]
fn main() {
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.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;
}