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
getposition, counting from end if < 0gets the character at a certain position (() if the position is not valid)
set1) 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)
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
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
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 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_string1) 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 individual characters, returning an array of characters
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
crop1) 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
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
chars method and property1) (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

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.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;
}