Dear David,
thank you for your message and apologies for not coming back to you earlier. We are currently working on an update of the documentation pages to also included language construct definitions. In the meantime, an in relation to your post, please find below a detailed description of all array functionality in ADOxx. I will keep you posted as soon as the update is released.
The documentation below provides also generic examples in AdoScript to support you in applying the concepts.
Overview Arrays
Arrays are part of the LEO language. So they actually may not just be used in AdoScript, but also in any other LEO based language. However, there are also some AdoScript specific elements concerning the handling of arrays, e.g. the SET command for arrays.
LEO arrays are implemented as array lists, i.e. the size of an array can be changed dynamically, elements can be appended.
Each element of an array may be any LEO value, i.e. the elements of one array need not all be of one same type.
Defining array variablesNew arrays variables are defined like other variables using the SET/SETG/SETL commands. Within expressions, array values are written with curly braces {}, like in the followiing:
1SET a: ({0, 2, 3, 6}) # array of four integer values
2CC "AdoScript" INFOBOX (STR a)
3
4SET ei: ("nen")
5SET b: {"ei", ei}) # string constant "ei" and value of variable ei
6CC "AdoScript" INFOBOX (STR b)
7
8# different data types in array
9SET ei: (1)
10SET b: ({"ei", ei}) # string constant "ei" and value of variable ei
11CC "AdoScript" INFOBOX (STR b)
Note that it is not correct to ommit the parenthesises (round braces) here. Without them, the content inside the curly braces would be interpreted as a new LEO program (block), known for instance from the notation of IF branches.
Another way to create a new array is using the array() function. It is used when the values of the array elements shall be assigned later. The function creates an array of a given size (number of elements) and with undefined element values.
1SET c: (array(10)) # new array with 10 elements
2CC "AdoScript" INFOBOX (STR c) # all elements are undefined
Getting the array sizeThe size, or length, of an array is the array's number of elements. For a given array, its size can be evaluated with the LEN operator or the array function .length:
1SET c: (array(10)) # new array with 10 elements
2SET n: (LEN c) # the value of n becomes 10
3CC "AdoScript" INFOBOX (STR n)
4
5SET c: (array(10)) # new array with 10 elements
6SET m: (c.length) # the value of n becomes 10
7CC "AdoScript" INFOBOX (STR m)
c has to be of type array. The result is number of elements of a.
Accessing arrays/Subscription to an array Array access is written with square brackets []. Inside the brackets the index of the accessed array element is specified. The index of the first element of any array is 0. The index of the last element of an array with n elements is n-1. It is always an error to try to access an element with an index less than 0 or greater or equal than the number of elements:
1SET a: ({0, 2, 3, 6}) # array of four integer values
2SET n1: (a[1]) # the value of n1 becomes 2
3SET n2: (a[1] + a[2]) # the value of n2 becomes 5
4SET n3: (a[4]) # error since a.length is 4
5CC "AdoScript" INFOBOX (STR n1 + " " + STR n2) # before the message, the error message of n3 is shown
Subscription to an array using SUBa SUB i #same as a
a has to be of type array, i of type integer. The result is the i-th element of a. The indexing of array elements begins with 0, as stated above.
HINT: Array elements, and so the result, may be of any type. The type of two different elements of one array needs not to be the same. Use type() if you are not sure about the element type.
For multi-dimensional arrays indices of different dimensions can be written comma-separated inside one bracket pair. a [i, j] means the same as a .
Assigning values to array elements
Single elements of array variables can be modified using the AdoScript SET command. The index is specified in enclosing brackets:
1# set all elements of array c to 0:
2SET c: (array(10)) # new array with 10 elements
3FOR i from:0 to:9 {
4SET c:0
5}
6CC "AdoScript" INFOBOX (STR c)
7
8# increase value of a[1]
9SET a: ({0, 2, 3, 6}) # array of four integer values
10CC "AdoScript" INFOBOX ("Before: " + STR a)
11SET a[1]: (a[1] + 1) # increase a[1] by 1, new value is 3
12CC "AdoScript" INFOBOX ("After: " + STR a)
Replacing values in an arrayThe areplace() function (areplace ( a, i1 , ..., in , val ) n >= 1) can also be used to change the value of an array element. As this is a LEO function, it can be used in any expression.
1SET a: ({0, 2, 3, 6}) # array of four integer values
2CC "AdoScript" INFOBOX ("Before: " + STR a)
3SET dummy: (areplace(a, 1, 263)) # same effect as SET a[1]:263, or as an Exporession set( a [ i1 , ..., in ], val ).
4CC "AdoScript" INFOBOX ("After: " + STR a)
The return value of areplace() is the new value of the replaced element.
Appending values to an arrayThe aappend() function (aappend ( a, i1 , ..., in , val ) n >= 0) also belongs to the LEO syntax and may not just be used in AdoScript. aappend() adds a new value at the end of an array:
1SET a:{7, 14, 21}
2CC "AdoScript" INFOBOX ("Before: " + STR a)
3SET dummy: (aappend(a, 28)) # a becomes {7, 14, 21, 28}
4CC "AdoScript" INFOBOX ("After: " + STR a)
The return value of aappend() is the appended value.
Deleting values in an arrayaerase ( a, i1 , ..., in ) n >= 1
Erases a single array element. a must be the name of an array variable. The array must have at least n dimensions. i1 to in must be of type integer.
Return value is the value of element which has been erased.
1SET a:{7, 14, 21}
2CC "AdoScript" INFOBOX ("Before: " + STR a)
3SET dummy: (aerase(a, 2)) # a becomes {7, 21, 28}
4CC "AdoScript" INFOBOX ("After: " + STR a)
Sorting arraysa.sort ( [ lambdaExpr ] )
Sorts the elements of an array. With the optional lambda expression a comparison operator can be specified. The labmda expression must have two parameters and returns true if the first value shall be inserted before the second.
The default lamda expression is
1lambda(x, y, x < y)
which leads to an ascending sorting of the array elements.
1SET a:{7, 14, 21}
2CC "AdoScript" INFOBOX ("Before: " + STR a)
3SET dummy: (a.sort(lambda(x, y, x > y)))
4CC "AdoScript" INFOBOX ("After: " + STR a)
Check if an array is emptya.empty
Returns 1 (true) if the array a is empty, and 0 (false) otherwise.
1SET a:{7, 14, 21}
2SET b: (array(0)) # initializes an empty array
3CC "AdoScript" INFOBOX ("A empty?: " + STR a.empty)
4CC "AdoScript" INFOBOX ("B empty?: " + STR b.empty)
Check if value in an arrayval IN a
Returns 1 (true) if val (value of any type) is contained in array a, and 0 (false) otherwise.
1SET a:{7, 14, 21}
2CC "AdoScript" INFOBOX ("7 included?: " + STR (7 IN a))
3CC "AdoScript" INFOBOX ("18 included?: " + STR (18 IN a))
www.adoxx.org
