Share via

AELEMENT( ) Function

  • Article

Returns the number of an array element from the element's subscripts.

AELEMENT(ArrayName, nRowSubscript [, nColumnSubscript])

Return Values

Numeric

Parameters

  • ArrayName
    Specifies the name of the array whose element number you want to return.

  • nRowSubscript
    Specifies the row subscript. If the array is one-dimensional, AELEMENT( ) identically returns nRowSubscript.

    If you include just nRowSubscript and it is greater than the number of rows in the array, Visual FoxPro generates an error message.

  • nColumnSubscript
    Specifies the column subscript. If the array is two-dimensional, include both nRowSubscript and nColumnSubscript.

Remarks

You can refer to an element in a two-dimensional 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, and the second method uses a single-element number. AELEMENT( ) returns the element number when supplied with an element's row and column subscripts.

The Visual FoxPro functions ADEL( ), ADIR( ), AFIELDS( ), AINS( ), ALEN( ), ASCAN( ), ASORT( ), and ASUBSCRIPT( ) can manipulate two-dimensional arrays and require that elements be referred to by their element number. AELEMENT( ) facilitates conversion from subscripts to an element number for use by these functions. The corresponding row and column subscripts can be returned from an element number with ASUBSCRIPT( ).

The following example illustrates the creation of an array with two rows and three columns. DISPLAY MEMORY shows the contents of the elements of the array listed in element number order.

DIMENSION gaMyArray(2,3)
DISPLAY MEMORY LIKE gaMyArray
gaMyArray   Pub  A
  ( 1, 1)   L  .F. (element number 1)
  ( 1, 2)   L  .F. (element number 2)
  ( 1, 3)   L  .F. (element number 3)
  ( 2, 1)   L  .F. (element number 4)
  ( 2, 2)   L  .F. (element number 5)
  ( 2, 3)   L  .F. (element number 6)

An element can be referred to by its subscripts or its element number. The commands STORE 'INVOICE' TO gaMyArray(2, 1) and STORE 'INVOICE' TO gaMyArray(4) both store the character string INVOICE to the same array element.

In one-dimensional arrays, an element number is identical to its single-row subscript. It isn't necessary to use AELEMENT( ) with one-dimensional arrays.

See Also

ADEL( ) | ADIR( ) | AFIELDS( ) | AINS( ) | ALEN( ) | ASCAN( ) | ASORT( ) | ASUBSCRIPT( ) | DIMENSION | DISPLAY MEMORY