Operator [ ] Foundation

Index operator (binary): accesses a specific element of an array, string, numeric or object.

<aArray>[<nElement1>][<nElement2>] [...]
<aArray> is an expression which returns a reference to an array. Generally this is the name of the memory variable referencing the array, but it can also be a member variable of an object or a function.
<nValue> is a numerical expression. The index operator allows accessing the bit element of the value. Valid ranges for <nElement> are 1 - 32 which corresponds with the bit position of a 32 bit integer.
<cString> is a character expression. The index operator allows accessing a single character. Valid ranges for <nElement> are 1 - Len(cString).
<oObject> is an expression which returns an object. The index operator allows access to exported member variables., Valid ranges are 1 - <amount-of-exported-member-var>. The order of the exported member variables corresponds with the order they appear in the class declaration.
<nElement> is a numeric expression which specifies a the index based on which the access to the element occurs. For each dimension of the array a numeric expression is included, either as comma separated list entirely enclosed in square brackets or with each expression separately enclosed in square brackets.

Individual elements of an array are accessed with the array operator. The expression returning the array must always precede the operator.

The numeric expression <nElement> must return an integer number not equal to zero in the range between the positive and negative number of array elements in the applicable dimension. A runtime error is generated if the value of <nElement> lies outside this range. If <nElement> has a positive value array elements are accessed from the beginning of the array. Negative values for <nElement> access an array from the end (the expression aArray[-1] == ATail(aArray) yields .T.). When <aArray> is an empty array the index operator cannot be used.

Extended functionality of the index operator

The index operator is not restricted to values of data type Array, but can also be used for character strings or numeric values.

The current Xbase++ version supports this way of operator usage only for LOCAL and STATIC variables holding the character string/the numeric value if used on the left hand side.


In case of character strings, the operator retrieves a single character of a string at the position <nElement> (see example below). This is much faster than retrieving a single character with the SubStr() function.


When the operand has a numeric value, the operator tests if the bit at the position <nElement> is set. The result of this operation is .T. (true) when the bit is set, otherwise it is .F. (false). Individual bits of a numeric value can be manipulated by assigning .T. or .F. for the bit at the position <nElement>. The range for <nElement>extends from 1 to 32 when the operand is of numeric data type.

The index operator ([ ])
// This example demonstrates various possibilities for 
// the index operator 

   LOCAL aArray := { "A", "B", "C" } 
   LOCAL i, j, nMax 

                                    // one dimensional array 
   ? aArray[1]                      // result: A 
   ? aArray[2]                      // result: B 
   ? aArray[3]                      // result: C 

   aArray := Directory()            // two dimensional array 
   nMax   := Len( aArray ) 

   FOR i := 1 TO nMax               // output all elements 
      ? aArray[i,1] 
      FOR j := 2 TO Len( aArray[i] ) 
         ?? aArray[i][j] 

   USE Customer NEW                 // combine function call 
                                    // with array element operator 
   ? DbStruct()[1,1]                // result: CUSTOMERNR 
Using the index operator with character strings
// This example shows how the index operator can be 
// used with values of data type Character. 

   LOCAL cString := "Xbase++ is cool" 
   LOCAL i, nLen, cTemp 

                                    // Traditional way 
   ? SubStr( cString, 3, 1 )        // result: a 
                                    // Fast way 
   ? cString[3]                     // result: a 

   cTemp := "" 
   i     := 0 
   nLen  := Len(cString) 

   DO WHILE ++i <= nLen             // Strip all vowels 
      IF cString[i] $ "aeiou" 
      cTemp += cString[i] 

   ? cTemp                          // result: Xbs++ s cl 

   cTemp[3] := "a" 
   cTemp[4] := "s" 
   cTemp[5] := "e" 

   ? cTemp                          // result: Xbase s cl 
Using the index operator with numbers
// This example shows how the index operator can be 
// used with values of data type Numeric. 

   LOCAL n 

   ? n := 6                  // result: 6 

   ? n[1]                    // result: .F. (bit for 2^0 not set) 
   ? n[2]                    // result: .T. (bit for 2^1 is set) 
   ? n[3]                    // result: .T. (bit for 2^2 is set) 

   n[1] := .T.               // setting bit for 2^0 

   ? n                       // result: 7 

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.