8.18/6/2018

Arrays

An array is a table of values of the same data type. You reference each element of the array (each cell of the table) independently. Arrays can be of type Boolean, integer, measure, currency, or string. The type of the array defines the type of values each of its elements can contain. Thus in a Boolean array, the value of each element is either True or False, and in a string array each element is a string value.

Arrays in PlanetPress Talk are one-dimensional. If you are not familiar with arrays from other programming or scripting languages, you can think of a one-dimensional array as a single row of a table. You specify the number of elements you want the array to contain, and initialize each of the elements, when you define the array. Note that you cannot subsequently increase or decrease the number of elements in an array. If you are uncertain of the exact number of elements the array may need to contain at runtime, you may want to create an array that can handle the most extreme case you expect the document to encounter at runtime. Note however that increasing the size of the array increases the memory required for the document, and that it is good programming practice not to create arrays that are larger than what the document requires to execute properly. An array in PlanetPress can have a maximum of 65,535 elements.

You define an array using the define() command, and assign values to individual elements using the assignment operator (:=), the set() command or the put() command. You retrieve the value of an individual element using either the get() command, or the name of the array followed by the position of that element in the array. The position is an integer value starting at 0 for the first element of the array, and incrementing by one for each additional element. See Define (procedure), Set (procedure), Put (procedure), and Get (function).

As an example, consider &tax_rates, an integer array containing five elements (10 20 30 40 50). You define the array as follows:

define( &tax_rates,arrayinteger,[10,20,30,40,50] )

You can use any of the following to change the value of the third element from 30 to 32.

&tax_rates[2] := 32
&tax_rates, 2, 32
put( &tax_rates, 2, 32 )

You can use any of the following to reference the third element in the array:

&tax_rates[2]
get(&tax_rates, 2)

For example:

&due := mul( &gross,&tax_rates[2] )
&due := mul( &gross,get(&tax_rates,2) )