ThinBASIC Core Language > BuiltIn Functions > Array functions

Description

Scan all or part of an array searching for a given value.

Syntax (Standard)

nRec = ARRAY SCAN ArrayVariable([StartIndex]) [FOR nElements] [, COLLATE UCASE], = Expression

Syntax (for UDT and fixed strings arrays)

nRec = ARRAY SCAN ArrayVariable([StartIndex]) [FOR nElements], BYTE(StartByte, Length), = Expression

Syntax (for array of pointer to heap allocated memory areas: each element of the Array MUST be a DWORD pointer to some memory allocated with HEAP* functions. Array Scan will use such pointer to reach allocated memory and perform a string comparison)

nRec = ARRAY SCAN ArrayVariable([StartIndex]) PTR [, BYTE(StartByte, Length)], = Expression

Returns

Numeric

Item element where the scan operation found the requested value.

ATTENTION: returned value is relative to StartIndex if StartIndex is specified otherwise will be absolute position starting from 1.

Zero means no items found

Parameters

For Standard arrays

Name	Type	Optional	Meaning
ArrayVariable	Array	No	Name of a declared and already dimensioned array.
StartIndex	Number	Yes	The element index inside the array from which to start to SCAN. If omitted, 1 is assumed
nElements	Number	Yes	If present, it indicates the number of consecutive elements to be scanned (starting from StartIndex).
Expression		No	Expression consist of logical relation operator (=, <>, >, >=, <, <=) followed by an expression of the same data type of ArrayVariable. Examples: = "AnyString expression" & MID$("ABC", 2, 1) >= 234 <1000

For UDT and fixed string arrays

Name	Type	Optional	Meaning
ArrayVariable	Array	No	Name of a declared and already dimensioned array.
StartIndex	Number	Yes	The element index inside the array from which to start to SCAN. If omitted, 1 is assumed
nElements	Number	Yes	If present, it indicates the number of consecutive elements to be scanned (starting from StartIndex).
StartByte	Number	No	Starting byte where to start to check for equality. The same byte position will be used in Expression.
Length	Number	No	Len of the memory area to check for equality. The same length will be used in Expression.
Expression		No	Expression consist of logical relation operator (=) followed by an expression of the same data type of ArrayVariable. Examples: = "AnyString expression" & MID$("ABC", 2, 1) = MyUDT

Remarks

If considering StartIndex and nElements, scanning will be outside array bounds, in any case SCAN will go till the end of the array.

ATTENTION: returned value is relative to StartIndex if StartIndex is specified otherwise will be absolute position starting from 1.

Restrictions

In Standard Arrays, only dynamic string and numeric arrays are permitted.

COLLATE UCASE is valid only for dynamic string arrays. COLLATE UCASE is used to consider all elements inside array as uppercase.