GETI

Member Of Menu: 
List
Array
Argument Types: 
Real
List
Symbol
Array
Result Type(s): 
Any
Real
Complex
List
Symbol
Array
Invertible: 
No
Valid In Expression: 
No
Stack Diagram: 
List1 Real2 → List1 Real3 Item4
List1 List2 → List1 List3 Item4
Array1 Real2 → Array1 Real3 Item4
Array1 List2 → Array1 List3 Item4
Symbol1 List2 → Symbol1 List3 Item4
Symbol1 Real2 → Symbol1 Real3 Item4

This operation is used to retrieve an item at a particular index within a list, vector or matrix. When operating on a list, the list to retrieve from may be found on the stack or it may be a list found in memory, referenced by a symbol name. In either case, the list or symbol is kept on the stack, the real number index is incremented and the item at the real number index is retrieved and pushed onto the stack. The intention is that incrementing the index on the stack allows quick iteration over the items on the stack. The retrieved item merely has to be removed from the top of the stack (stored elsewhere if necessary) and GETI can be executed again to get the next item in the list. If the index points to the end of the list before the operation, the index after the operation will have wrapped and begin again at one. Note that the index can be a real value or a list with a single real value when operating on lists.

If operating on a vector either directly on the stack or referenced by a symbol, the index can be a real value or a list with a single real value. The vector or symbol remains on the stack after the operation. The index is incremented to point to the next item in the vector, wrapping to the first item if at the end. Finally, the real or complex value at that location in the vector is pushed onto the stack.

If operating on a matrix either directly on the stack or referenced by a symbol, the index must be a list with two real values representing the row and column location. After execution, the matrix or symbol remains on the stack. The index is incremented such that the operation visits each column in a row and then incrementing the row count until wrapping back around to the item at the first row, first column. Finally, the real or complex value at the input row and column is pushed onto the stack.

Also, this operation sets the 46th flag as described in the Working With Programs guide if the index wrapped. Otherwise, it clears the flag. Testing this flag can be useful in a program in order to loop over all items in the list, vector or matrix.