FINDSTR
Synopsis
FINDSTR substring IN dynarray[,occurrence] SETTING fm[,vm[,sm]] [THEN statements] [ELSE statements]
Arguments
| substring | A string to match against each element in dynarray. |
| dynarray | The target dynamic array in which substring is located. |
| occurrence | Optional — An integer that specifies which occurrence of substring to return dynarray. The default is 1. |
|
fm vm sm |
Variables that receive an integer specifying the Field Mark (fm) Value Mark (vm) and Subvalue Mark (sm) where substring is located in dynarray. For further information on these level delimiters, see the Dynamic Arrays page of this manual. |
Description
The FINDSTR statement searches a dynamic array for the specified substring. If it locates the substring, it sets integer count variables specifying which element of the dynamic array contains the substring. By default, it locates the first occurrence of substring in the dynamic array, reading left to right. You can set the optional occurrence argument for subsequent occurrences of substring in the dynamic array.
If FINDSTR finds substring, it sets fm, vm, and sm to an integer count. If dynamic array delimiters for a lower level do not exist, FINDSTR sets this level's variable (vm and/or sm) to 1. If substring is not located, fm, vm, and sm are not modified, and continue to hold their previous values.
The fm, vm, and sm arguments accept a single dynamic array reference (A<i>), a single substring reference (A[s,l]), or a substring reference nested inside a dynamic array reference (A<i>[s,l]).
You can optionally specify a THEN clause, an ELSE clause, or both a THEN and an ELSE clause. If substring is located in dynarray, the THEN clause is executed. If substring is not located in dynarray, the ELSE clause is executed. The statements argument can be the NULL keyword, a single statement, or a block of statements terminated by the END keyword. A block of statements has specific line break requirements: each statement must be on its own line and cannot follow a THEN, ELSE, or END keyword on that line.
The FINDSTR statement returns the f, v, and s position of a dynamic array element by specifying a substring found in that element. The FIND statement returns the f, v, and s position of a dynamic array element by specifying the element's exact value. The EXTRACT function returns the value of a dynamic array element by specifying its f, v, and s position.
Examples
The following example shows how to use the FINDSTR statement:
statecity="Kansas":@VM:"Kansas City":@VM:"Topeka"
:@FM:"Missouri":@VM:"St Louis":@VM:"Kansas City"
FOR x=1 TO 5
FINDSTR "Kansas" IN statecity,x SETTING f,v,s
PRINT f,v,s
NEXT
This example returns the following values for f, v, and s:
1 1 1 ! 1st occurrence of substring "Kansas" 1 2 1 ! 2nd occurrence of substring "Kansas" 2 3 1 ! 3rd occurrence of substring "Kansas" 2 3 1 ! no further occurrences, variables unchanged 2 3 1
