|
Purpose |
Scan all or part of an array for a given value. |
|
Syntax |
Numeric array: ARRAY SCAN array([index]) [FOR count], expression, TO lvar& String arrays: ARRAY SCAN array ([index]) [FOR count] [, FROM startChar TO endChar] [, COLLATE {UCASE | cstring}], expression, TO lvar& |
|
Remarks |
ARRAY SCAN scans all or part of array, an n-dimension array, for the first element that satisfies expression. expression consists of a relational operator (=, >, <, <>, >=, =>, <=, =<) followed by an expression of the same data type as array. The relative index of the first match is stored in lvar&, which must be a Long-integer variable: ARRAY SCAN A&(), > 5, TO I& This line of code identifies the relative index of the first element of array A&() that is greater than 5, and stores the relative index in I&. The match index ranges from 1 to the last element of the scan + 1. Since it is a relative index: DIM A(1 TO 10) AS SINGLE ARRAY SCAN A(), > 17.42!, TO I& …will store 2 in I& if A(2) > 17.42, but: DIM A(5 TO 20) AS SINGLE ARRAY SCAN A(), > 17.42!, TO lvar& …will store 2, not 6, in lvar& if A(6) > 17.42. If none of the scanned elements satisfy expression, zero will be stored in lvar&. Together, index and count specify the portion of array to be scanned. index specifies the element at which the scan is to begin, while count specifies the number of consecutive elements to be scanned. If index is not specified, the scan begins at the first element of array. If count is not specified, the array is scanned from element index to the last element of array. If neither is specified, the entire array is scanned: DIM A&(1 TO 100) ARRAY SCAN A&(5), =1, TO I& 'scans 5..100 ARRAY SCAN A&() FOR 10, =1, TO I& 'scans 1..10 ARRAY SCAN A&(10) FOR 20, =1, TO I& 'scans 10..29 ARRAY SCAN A&(), =1, TO I& 'scans 1..100 Scanning a string array When scanning a string array, COLLATE UCASE treats all lowercase letters as uppercase during the scan (for example, element "Bob" would satisfy the condition = "BOB"): ARRAY SCAN A$(), COLLATE UCASE, = "BOB", TO I& ' scans A$() for "BOB"; all letters treated as ' uppercase COLLATE string is used to specify a non-standard
scanning order. cstring must contain exactly 256 characters,
in the order in which they should be compared, from lowest to highest.
For example, the normal ascending ASCII
scan order (where "A" is considered less than "B",
etc.) would be described by a
C$ = CHR$(0 TO 255) ARRAY SCAN A$(), COLLATE C$, > "BOB", TO I& The normal descending ASCII scan order would be described by a string containing the reverse of the above: C$ = STRREVERSE$(CHR$(0 TO 255)) ARRAY SCAN A$(), COLLATE C$, > "BOB", TO I& The COLLATE string option is provided as a flexible means with which to specify a descending scan, or to specify the scanning order for strings containing international characters or other special symbols. See ARRAY SORT for more information on building collating strings. When scanning a string array, all characters of each element of the array are normally considered when performing comparisons. To limit the comparison to a specific subset of characters, use FROM to specify the startChar position, and TO to specify the endChar position that ARRAY SCAN will consider within each array element. For example, you could scan based on the zip code contained in the last 5 characters of a 40-character address string: ARRAY SCAN A$(), = "90210", TO I& ' considers all characters when scanning for "90210"
ARRAY SCAN A$(), FROM 36 TO 40, = "90210", TO I& ' considers positions 36..40 only when scanning Scanning a multi-dimensional array When scanning a multi-dimensional array, the array is treated as a single-dimension array containing all of the elements of the multi-dimensional array, in linear column-major order. That is, all elements where all dimensions (except the first), are held at their minimum bounds, will come first in memory. These are immediately followed by the elements where the second dimension is set to its next consecutive index value, etc. For example, the elements of a two-dimensional array (DIM A(0 TO n, 0 TO x)) would be stored in consecutive memory locations as follows: A(0,0), A(1,0), …, A(n,0) ' The first n+1 elements, A(0,1), A(1,1), …, A(n,1) ' The next n+1 elements, [statements] ' Subsequent elements, A(0,x), A(1,x), …, A(n,x) ' The last n+1 statements. …or more clearly: In this case, ARRAY SCAN A(0,0) FOR n+1, >5, TO I& would scan only elements (0,0)...(n,0), while ARRAY SCAN A(0,0), >5, TO I& would scan the entire array: elements (0,0)...(n,x). As mentioned earlier, since ARRAY SCAN records the relative index of the matched element, ARRAY SCAN A(0,0), >5, TO I& would store 2 in I& if A(1,0) > 5. |
|
Options |
The options for ARRAY SCAN can be specified in any order, as long as the FOR option, if present, directly follows the closing parenthesis of the name of array. |
|
Restrictions |
ARRAY SCAN cannot be used on arrays within UDT structures or on an array of Interfaces. However, ARRAY SCAN can be used with arrays of UDT structures - simply treat them as if they were an array of fixed-length strings. To use ARRAY SCAN on an embedded UDT array, use DIM..AT to dimension a regular array (of the same type) directly "over the top" of the UDT array, and use ARRAY SCAN on that array. For example: TYPE SalesType OrderNum AS LONG PartNumber(1 TO 20) AS STRING * 20 END TYPE [statements] DIM Sales AS SalesType [statements] DIM Temp(1 TO 20) AS STRING * 20 AT VARPTR(Sales.Partnumber(1)) ARRAY SCAN Temp(), FROM 1 TO LEN(Search$), = Search$, TO lResult& ERASE Temp() |
|
See also |
ARRAY ASSIGN, ARRAY DELETE, ARRAY INSERT, ARRAY SORT, DIM, LBOUND, PowerArray, REDIM, UBOUND |
|
Example |
ARRAY SCAN A&(5) FOR 10, > 64000&, TO B& Scans elements 5 through 14 of array A&, looking for the first element whose value is > 64000, and stores the relative index of that element in B&. ARRAY SCAN A$(5) FOR 10,FROM 16 TO 25,COLLATE C$, = D$, TO B& Scans elements 5 through 14 of array A$, looking only at characters 16 to 25 of each element, using the order specified by collating string C$, looking for the first element whose value is equal to D$, and stores the relative index of that element in B&. |