String Functions

String functions are scalar functions that perform an operation on a string input value and return a string
or numeric value.

Functio
n Syntax Purpose

strlen int strlen(string) Returns the length of a string in bytes, as an integer number.

midstr string Returns a part of the string starting at arg2, arg3 bytes long.
midstr(string, int,
arg2 is counted from 1 (not 0).
int)

midstru string Returns a part of the string starting at character or surrugate arg2, arg3
midstru(string, int) characters, or surrogates long.

string
midstru(string, int,
int)

leftstr string leftstr(string, Returns arg2 bytes from the left of the arg1. If arg1 is shorter than the
int) value of arg2, the complete string is returned.

rightstr string Returns arg2 bytes from the right of the arg1. If arg1 is shorter than
rightstr(string, int) the value of arg2, the complete string is returned.

rightsru string return arg2 characters from the right of string. If arg1 is shorter than
rightstru(string, arg2 characters, the complete string is returned.
int)

instr int instr(string, Returns the position of the first occurrence of the second string within
string) the first string (>
Functio
n Syntax Purpose

= 1) or 0, if the second string is not contained in the first.

instru int instru(string, return the character position of the first occurrence of the second
string) string within the first string (>= 1) or 0, if the second string is not
contained in the first. This assumes inputs to be unicode expressed in
utf-8, if the input is not encoded this way, the result is less
meaningful.

hextoraw string Convert a hexadecimal representation of bytes to a string of bytes.

hextoraw(string) The hexadecimal string may contain 0-9, upper or lowercase a-f and
no spaces between the two digits of a byte; spaces between bytes are
allowed.

rawtohex string convert a string of bytes to its hexadecimal representation.

rawtohex(string)
The output contains only 0-9 and (upper case) A-F, no spaces and is
twice as many bytes as the original string.

ltrim string ltrim(string) removes a whitespace prefix from a string. The Whitespace characters
may be specified in an optional argument. This function operates on
string ltrim(string,
raw bytes of the UTF8-string and has no knowledge of multi byte
string)
codes (you may not specify multi byte whitespace characters).

rtrim string rtrim(string) removes trailing whitespace from a string. The Whitespace characters
may be specified in an optional argument. This function operates on
string rtrim(string,
raw bytes of the UTF8-string and has no knowledge of multi byte
string)
codes (you may not specify multi byte whitespace characters).

trim string trim(string) removes whitespace from the beginning and end of a string. These
should be equivalent:
string trim(string,
string)
Functio
n Syntax Purpose

- trim(s) = ltrim(rtrim(s))

- trim(s1, s2) = ltrim(rtrim(s1, s2), s2)

lpad string lpad(string, add whitespace to the left of a string. A second string argument
int) specifies the whitespace, which is added repeatedly until the string
has reached the intended length. If no second string argument is
string lpad(string,
specified, chr(32) (' ') gets added. This function operated on UTF-8
int, string)
bytes and has no knowledge of unicode characters (neither for the
whitespace string nor for length computation).

rpad string rpad(string, add whitespace to the end of a string. A second string argument
int) specifies the whitespace, which is added repeatedly until the string
has reached the intended length. If no second string argument is
string rpad(string,
specified, chr(32) (' ') gets added. This function operated on UTF-8
int, string)
bytes and has no knowledge of unicode characters (neither for the
whitespace string nor for length computation).

replace string replace every occurrence of arg2 in arg1 with arg3 and return the
replace(string, resulting string
string, string)

upper string upper(string) return an all upper case version of the string. Unlike most other string
functions, this also attempts to convert unicode characters in CESU
encoding beside the usual a-z.

lower string lower(string) return an all lower case version of the string. Unlike most other string
functions, this also attempts to convert unicode characters in CESU
encoding beside the usual A-Z.

rightstru string return arg2 characters from the right of string. If arg1 is shorter than
Functio
n Syntax Purpose

rightstru(string, arg2 characters, the complete string is returned.

int)

chars chars(string) return the number of characters in a string. This returns the number of
characters in an UTF-8 encoded string. In a CESU-8 encoded string, it
returns the number of 16-bit words of that string if it were encoded if
UTF-16.

charpos charpos(string, int) return the position of the nth character in a string (n starting with 1).
The string is interpreted as UTF-8 as it is in the preceding chars()
function.