Documentation

String Functions
Prev Chapter 1. Intrinsic Functions Next

String Functions

This section contains the intrinsic functions that are used for working together with string values.

.instr()

Prototype

.instr( <sourcetext> , <searchtext> )

Return types

.nul, .inf, integer

Description

Returns the one-based position of the first occurrence of one string within another. If the substring is not found then zero is returned.

Parameters

sourcetext
Type nameResult for an expression of this type in this parameter
.nul The result will be .nul
.inf The result will be .inf, unless the second parameter is .nul
string The string to find the substring in
searchtext
Type nameResult for an expression of this type in this parameter
.nul The result will be .nul
.inf The result will be .inf, unless the first parameter is .nul
string The substring to search for. If this is the empty string then the return value will be 0, unless the first parameter is .nul or .inf

.len()

Prototype

.len( <sourcetext> )

Return types

.nul, .inf, integer

Description

Determines the length of a string.

Parameters

sourcetext
Type nameResult for an expression of this type in this parameter
.nul The result will be .nul
.inf The result will be .inf
string The string to return the length of

.like1()

Description

Compares a string with a pattern and returns .true if the string matches the pattern, or .false otherwise.

Prototype

.like1 ( string , string )

Parameters

ParameterDefault valueType nameDescription
 None string The string to test against the pattern.
 None string The pattern to test the string against. The string is matched against the pattern on a character by character basis, with the exception of the * wildcard described below. The string is considered to match the pattern is every character in it is matched by the characters in the pattern, and neither has any characters in excess. Matching can be performed either in a case sensitive mode, or a case insensitive mode. With the exception of the special pattern characters described below, a character in the string matches a character in the pattern if either the characters are the same, or if case insensitive testing is being done and the characters are the same when converted to lower case. The special pattern characters are:

  • ^ = toggles between case sensitive and case insensitive testing. The initial case sensitivity setting is always case insensitive.

  • ? = matches any character, but the character must exist.

  • * = matches any number of any characters, including no characters.

  • [ = starts a range specifier. A range specifier gives a number of characters, any of which may match a character from the string, for example the range "[abc]" matches either "a", "b" or "c". If case insensitive testing is being done, then it also matches "A" "B" and "C". Within a range there are some characters with special meanings:

    • ] = indicates the end of the range.

    • [ = indicates that the next character is to be interpreted literally as part of the range, and any special meaning is to be overlooked. For example the pattern "[[[]" is the only way to match only the string "[", and "[[]]" is the only way to match only the string "]"

    • - = indicates that a contiguous range is being included in the range. If '-' is the first character in the range then all characters up to the value of the next character in the range are included, for example the pattern "[-9]" matches all characters up to and including the character '9'. If '-' is the last character in the range then all characters including or greater than the previous character are included in the range, for example the pattern "[A-]" matches all characters above or equal to character 'A'. If '-' is the only character in the range then any character from the string is a match, i.e. the pattern "[-]" is equivalent to the pattern "?". If the character '-' has another character both before and after it (as would normally be the case) then the range includes every character between the lower valued and the higher valued of these characters, for example the pattern "[A-Z]" matches all characters in the upper case roman alphabet. If a range is specified and case insensitive testing is being done, then a character in the string is compared with the characters in the range and the lower case of the character from the string is compared with the lower case of each character in the range. The conversion to lower case is done AFTER contiguous ranges have been calculated, which may be different from calculating contiguous ranges after converting to lower case.

.lstr()

Prototype

.lstr( <sourcetext> ; <count> )

Return types

.nul, .inf, string

Description

Extracts characters from the beginning of a string

Parameters

sourcetext
Type nameResult for an expression of this type in this parameter
.nul The result will be .nul
.inf The result will be .inf, unless the second parameter is .nul
string The string to extract the beginning characters from
count
Type nameResult for an expression of this type in this parameter
.nul The result will be .nul
.inf The result is the whole first parameter
integer The number of characters to extract. If this is negative no characters are returned. If it is greater than the length of the string then the whole string is returned

.rstr()

Prototype

.rstr( <sourcetext> , <count> )

Return types

.nul, .inf, string

Description

Extracts characters from the end of a string

Parameters

sourcetext
Type nameResult for an expression of this type in this parameter
.nul The result will be .nul
.inf The result will be .inf, unless the second parameter is .nul
string The string to extract the ending characters from
count
Type nameResult for an expression of this type in this parameter
.nul The result will be .nul
.inf The result is the whole first parameter
integer The number of characters to extract. If this is negative no characters are returned. If it is greater than the length of the string then the whole string is returned

.substr()

Prototype

.substr( <sourcetext> , <startpos> , <count> )

Return types

.nul, .inf, string

Description

Extracts characters a specified number of characters from a specified position in a string

Parameters

sourcetext
Type nameResult for an expression of this type in this parameter
.nul The result will be .nul
.inf The result will be .inf, unless another parameter is .nul
string The string to extract characters from
startpos
Type nameResult for an expression of this type in this parameter
.nul The result will be .nul
.inf If the result will be a string, then it will be the empty string, ie. the function behaves as if character extraction starts at the end of the string.
integer The one-based position to start extracting characters from. If this is zero or negative then the start position is the start of the string. If it is greater than the length of the string then an empty string is returned.
count
Type nameResult for an expression of this type in this parameter
.nul The result will be .nul
.inf If the result is a string then all characters to the end of the string are extracted
integer The number of characters to extract. If this is negative no characters are returned. If it is greater than the length from the start of the extraction to the end of the string then characters up to the end of the string are returned.
Prev Up Next
Blob Functions Home Chapter 2. System Functions