SetArrayIndex

Arrays
Aptilis 1

SetArrayIndex(ArrayName[], Index)

SetArrayIndex is used to set the internal index of an array. In aptilis, all the variables are arrays and they have an internal counter which allows retrieval of array values one by one, which is especially useful in stringed key arrays, where the keys are not known in advance.
If you don't set the array index before retrieving values with either GetNext or GetPrevious, there is no way you can foresee which value you are going to get.
You can feed string values to SetArrayIndex, ie. "begin", or "end", or an actual number.
The index given to SetArrayIndex might not correspond exactly to the actual index or reference of the value. Indeed, if you have an array with three values, the indexes you can give to setarrayindex might not correspond to the actual indexes:

a["one"] = "un" $                   (index -> 0)
a["ten"] = "dix" $                  (index -> 1)
a["one hundred"] = "cent" $         (index -> 2)

Example 1:

a["pomme"] = "Apple" $
a["banane"] = "Banana" $
a["cerise"] = "Cherry" $

setArrayIndex(a[], "begin")
t = getNext(a[])$
print(t$)
Result:
Apple

Example 2:

a["pomme"] = "Apple" $
a["banane"] = "Banana" $
a["cerise"] = "Cherry" $

setArrayIndex(a[], "end")
t = getPrevious(a[])$
print(t$)
Result:
Cherry

Example 3:

a["pomme"] = "Apple" $
a["banane"] = "Banana" $
a["cerise"] = "Cherry" $

setArrayindex(a[], "begin")
for i = 1 to getArraySize(a[])
t = getNext(a[])$
print(t$, "\n")
end for
Result:
Apple
Banana
Cherry

Example 4:

a["pomme"] = "Apple" $
a["banane"] = "Banana" $
a["cerise"] = "Cherry" $

setArrayindex(a[], "end")
for i = 1 to getArraySize(a[])
t = getPrevious(a[])$
print(t$, "\n")
end for
Result:
Cherry
Banana
Apple

See also GetNext, GetPrevious, GetArraySize, ClearArray.