Navigation:  ThinBASIC Modules > Core (thinBasic Core Engine) > Array functions >

ARRAY SCAN

Previous pageReturn to chapter overviewNext page

 

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.

 

See also

 

LBound, UBound, ARRAY SORT,

 

Examples