String Functions

String Functions
	Chapter 1. Intrinsic Functions

.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 name	Result 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 name	Result 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 name	Result 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`

Parameter	Default value	Type name	Description
	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 name	Result 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 name	Result 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 name	Result 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 name	Result 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 name	Result 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 name	Result 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 name	Result 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.