Standard String Functions

The following standard methods (mostly defined in the MoreStringPackage but excluded when 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
is_empty method and propertynonereturns true if the string is empty
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
min
  1. first character/string
  2. second character/string
    		returns the smaller of two characters/strings
    max
    1. first character/string
    2. second character/string
      		returns the larger of two characters/strings
      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.

      Building Strings

      Strings can be built from segments via the + operator.

      OperatorDescription
      string += itemconvert the item into a string, then append it to the first string
      string + itemconvert the item into a string, then concatenate them as a new string
      item + stringconvert 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.

      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

      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.

      OperatorDescription
      +, +=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;