StrToken function (LotusScript® Language)

Returns a specified word from a text string.

Note: This function is new with Domino® Release 6.

Syntax

StrToken ( expression , delimiter , wordNumber [, compMethod])

Elements

expression

String containing the string to be scanned.

delimiter

The string which delimits "words" in the input. For example, ", " (comma space) means words are separated by the string ", " - not the character comma or the character space.

wordNumber

Long indicating which word from expression should be returned.

compMethod

Optional Integer specifying the type of comparison to use when searching for the delimiter.

Number

Comparison Mode

0

case sensitive, pitch sensitive

1

case insensitive, pitch sensitive

4

case sensitive, pitch insensitive

5

case insensitive, pitch insensitive

If you omit compMethod, the default comparison mode is the mode set by the Option Compare statement for this module. If there is no statement for the module, the default is case sensitive and pitch sensitive.

Return value

Returns a String. The String returned is the specified word from expression.

Usage

StrToken returns the specified word from a text string. A "word" is defined as the part of a string that is delimited by the defined separator character or characters. For example, if you specify a space (" ") as the separator, a word is any series of characters preceded by and followed by a space (or by the quotation marks that indicate the beginning or end of the string, for example, " hello there " has four words - "", "hello" , "there", "").

Note: The first word, "", is considered a word because it is delimited by the beginning of the string on the left and by the delimiter character the follows.

Expression is broken up into words and the word in the position specified by wordNumber is returned.

If the delimiter is more than one character, a subset of those characters does not work as a delimiter. For example, if the delimiter is " " (two spaces), a single space is not recognized as a delimiter.

If the absolute value of wordNumber is greater than the number of words, the specified word is assumed to be the empty string "".

If wordNumber = 0, the word specified is taken to be the 1st word of the String (i.e. wordNumber=0 is equivalent to wordNumber=1)

If wordNumber < 0, the word specfied is found by counting backwards from the last word of the String.

Error Handling

StrToken will throw a Runtime Type Mismatch if the expression or delimiter is not scalar, or if wordNumber is not a long (cannot be coerced to a long by the compiler)

StrToken will throw a Runtime Argument Out of Range Error if the optionCompare value is invalid.

Example