xHarbour Reference Documentation > Function Reference

AScan()

Searches a value in an array beginning with the first element.

Syntax

Ascan( <aArray>  , ;
       <xbSearch>, ;
       [<nStart>], ;
       [<nCount>], ;
       [<lExact>], ;
       [<lASCII>]  ) --> nElement

Arguments

<aArray>

This is the array to iterate.

<xbSearch>

<xbSearch> is either the value to search in <aArray> or a code block containing the search condition. The code block receives a single parameter which is the value stored in the current array element. The code block must return a logical value. When the return value is .T. (true), the function stops searching and returns the position of the corresponding array element.

<nStart>

This is a numeric expression indicating the first element in the array to begin the search with. It defaults to 1, the first element of <aArray>.

<nCount>

A numeric expression specifying the number of elements to search. It defaults to 1+Len(<aArray>)-<nStart>.

<lExact>

This parameter influences the comparison for searching character strings in <aArray>. If .T. (true) is passed, an exact string comparison is performed. When omitted or if .F. (false) is passed, string comparison follows the SET EXACT rules.

<lASCII>

This parameter is only relevant for arrays that contain single characters in their elements. A single character is treated like a numeric ASCII value when <lASCII> is .T. (true). The default is.F. (false).

Return

AScan() returns the numeric ordinal position of the array element that contains the searched value. When no match is found, the return value is 0.

Description

The array function AScan() traverses the array <aArray> for the value specified with <xbSearch>. If <xbSearch> is not a code block, AScan() compares the values of each array element for being equal with the searched value. If this comparison yields .T. (true), the function stops searching and returns the numeric position of the array element containing the searched value.

If a code block is passed for <xbSearch>, it is evaluated and receives as parameter the value of the current array element. The code block must contain a comparison rule that yields a logical value. AScan() considers the value as being found when the codeblock returns .T. (true). Otherwise the function proceeds with the next array element.

Note:  use function RAscan() to search an array beginning with the last element.

Info

See also:	AEval(), Asc(), ASort(), ATail(), Eval(), IN, RAscan(), SET EXACT
Category:	Array functions
Source:	vm\arrayshb.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example demonstrates simple and complex searching in arrays.

   PROCEDURE Main()
      LOCAL aArray := { "A", 1, Date(), NIL, .F. }

      // one dimensional array
      ? AScan( aArray, 1 )             // result: 2
      ? AScan( aArray, .F. )           // result: 5

      ? AScan( aArray, {|x| Valtype(x)=="D" } )
                                       // result: 3

      // two dimensional array
      aArray := Directory( "*.prg" )

      ? AScan( aArray, {|a| Upper(a[1]) == "TEST.PRG" } )
                                       // result: 28
   RETURN