Partager via

ASCAN( ) Function

  • Article

Searches an array for an element containing the same data and data type as an expression.

ASCAN(ArrayName, eExpression [, nStartElement [, nElementsSearched [, nSearchColumn [, nFlags ]]]])

Return Values

Numeric

Parameters

  • ArrayName
    Specifies the name of the array to search.

  • eExpression
    Specifies the general expression to search for.

  • nStartElement
    Specifies the element number at which the search begins. The element number you specify is included in the search. If you omit nStartElement, the entire array is searched by default.

  • nElementsSearched
    Specifies the number of elements that are searched. If you omit nStartElement and nElementsSearched, the search begins with the first array element and continues to the last array element if you do not specify nSearchColumn.

    Note   You can refer to an element in a two-dimensional variable array in one of two ways. The first method uses two subscripts to specify the row and column position of the element in the array; the other method uses an element number. This function and others that manipulate two-dimensional arrays require element numbers (nStartElement and nElementsSearched). Use AELEMENT( ) to return the element number from row and column subscripts in a two-dimensional array.

  • nSearchColumn
    Specifies the array column to search. This is often useful in arrays created by functions such as AFIELDS( ).

    You can use 0 or a negative number for nSearchColumn to impose a search of the entire array. If you use a value greater than 0 for nSearchColumn, ASCAN( ) treats the specified column as a one-dimensional array, using each data row as an element in the search. For instance, the following example searches only the 3rd and 4th elements of column 2 (instead of the entire array).

    ? ASCAN(abc,"M",3,2,2)

    Visual FoxPro generates an error if nSearchColumn is a number larger than the number of available columns.

  • nFlags
    Specifies additional search criteria to apply to the scan function. Default scans are case-sensitive.

    The number you specify in nFlags provides a bit-value that determines the case sensitivity or exactness setting of a scan according to the following table:

    NFlag Bit Description
    0 0000 Current behavior existing in the previous version of Visual FoxPro
    1 0001 Case Insensitive
    2 0010 Current behavior existing in the previous version of Visual FoxPro
    3 0011 Case Insensitive
    4 0100 Exact OFF
    5 0101 Case Insensitive; Exact OFF
    6 0110 Exact ON
    7 0111 Case Insensitive; Exact ON
    8 1000 Return row number
    9 1001 Case Insensitive; return row number
    10 1010 Return row number
    11 1011 Case Insensitive; return row number
    12 1100 Return row number; Exact OFF
    13 1101 Case Insensitive; Return row number; Exact OFF
    14 1110 Return row number; Exact ON
    15 1111 Case Insensitive; Return row number; Exact ON

The bit values are as follows:

Bit Description
0 Case Insensitive bit
1 Exactness ON bit (Only effective if bit 2 is set)
2 Override system Exact setting bit
3 Return row number if 2D array

nFlags applies only to the ASCAN( ) function and does not affect settings for SET EXACT.

Remarks

If a match is found, ASCAN( ) returns the number of the element containing the expression. If a match cannot be found, ASCAN( ) returns 0.

The criteria for a successful match of character data are determined by the setting of the system SET EXACT if nFlag with bit 2 is not set. If SET EXACT is ON, an element must match the search expression character for character and have the same length. If SET EXACT is OFF, and an element and search expression match until the end of the expression is reached, the match is successful. For more information on match criteria for character strings, see the string comparison table in the SET EXACT topic.

In the previous version of Visual FoxPro, the nStartElement and nElementsSearched parameters are optional. The nStartElement must be > 0 while nElementsSearched can be any value. In order to accommodate the new nSearchColumn parameter, you will need to bypass these parameters by passing a value of –1.

The nStartElement and nElementsSearched parameters take on special meaning if the value of nSearchColumn is greater than 0. In the previous version of Visual FoxPro, they are always referenced to the entire array. For this version of Visual FoxPro, if a positive nSearchColumn is passed, the values of nStartElement and nElementsSearched are referenced to the single one-dimensional array represented by the nSearchColumn. For example, the following would only search the 3rd and 4th elements of column 2, and not the entire array:

? ASCAN(abc,"M",3,2,2)

Example

The following example creates and fills an array with company names, and then uses ASCAN( ) to search for a particular company name. If the company name is found, it is removed from the array.

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer     && Open customer table
SELECT company FROM customer ;
  WHERE country = 'UK' ;
  INTO ARRAY gaCompanies
gnCount = _TALLY
gcName = 'Seven Seas Imports'
CLEAR
DISPLAY MEMORY LIKE gaCompanies*
gnPos = ASCAN(gaCompanies, gcName) && Search for company
IF gnPos != 0
  *** Company found, remove it from the array ***
  = ADEL(gaCompanies, gnPos)
  gnCount = gnCount - 1
ENDIF
DISPLAY MEMORY LIKE gaCompanies

See Also

ACOPY( ) | ADEL( ) | ADIR( ) | AELEMENT( ) | AFIELDS( ) | AINS( ) | ASORT( ) | ASUBSCRIPT( ) | DIMENSION | SET EXACT