You can define two-dimensional arrays of numbers in DPL. An array corresponds to a two-dimensional range in a spreadsheet, and it can be used in DPL with certain spreadsheet functions. The following statement defines a two-dimensional array in DPL:
array A =
{1, 2, 3;
4, 5, 6;
7, 8, 9;
10, 11, 12};
The first element of this array is referred to as A[0][0], and it equals 1. The second element is A[0][1], and it equals 2. The third element is A[0][2], and it equals 3. The fourth element is A[1][0], and it equals 4. The last element is A[3][2], and it equals 12. Commas separate elements in a row, and semicolons separate rows. (Note: the last row does not end with a semicolon.)
The elements of an array, unlike those of a series, cannot be initialized in groups. You must initialize each element of an array separately, although you can leave some elements uninitialized. If you do not initialize an array element, it is called a null element.
An array, like a series, cannot depend on the states of events. However, you can initialize the elements of arrays with expressions that depend on the states of events.
You can reference the elements of an array, like those of a series, with subscripts. The first subscript refers to the row, the second refers to the column. The subscripts of an array are always in a range from 0 to a positive integer. A subscript of 0 references the first row or column of an array. A subscript of 1 references the next row or column, and so on. If necessary, DPL will truncate the number represented by an array subscript to produce an integer.
If an array has only one row, DPL treats it as a two-dimensional array whose first subscript can have only one value.
array Payments = {100, 150, 200, 240};
The first element of this array is Payments[0][0], and it equals 100. DPL allows you to omit the first subscript when an array only has one row, so the first element is also Payments[0].
You can initialize each element of an array with an expression. The expression can contain values that depend on events and any of DPL's functions.
You can leave some elements of an array uninitialized, in which case they are called null elements. The following definition includes a null element in an array that only has one row.
array Payments = {100, 150, , 240};
The null element in this example occurs where two commas occur without an intervening expression. It is the third element in Payments. In a program, you refer to it as Payments[2] or Payments[0][2].
Null elements correspond to empty cells in spreadsheets. DPL treats null elements the same way a spreadsheet treats empty (null) cells. In expressions and most functions, DPL usually treats null elements as the number 0, although some spreadsheet functions distinguish between null elements and those equal to 0. DPL will display null elements as (null) in response to a command to list the elements of the array.
DPL allows you to reference an array before defining it. This makes it possible to define several arrays recursively. Because you can define both series and arrays recursively, you must first specify whether the variable being referenced before its definition is a series or an array (if you don't, DPL will assume it is a series). Then, use the variable name, and finally, provide the complete definition. For example:
array a;
series s=
from 1: a[0][0],
from 2 to 4: a[1][$-2];
array a= {@sum(s{2..4}), 0,0;
1,2,3};
There are three ways to use an array in a DPL expression:
- With one or two subscripts (depending on the dimensions of the array)
- Without a subscript, as the argument of a function that converts the array to a single number
- With a specified subrange, as the argument of a function that converts the subrange into a single number
If an array does not have subscripts, it must appear by itself as the argument of a function and not as part of an expression.
If an array has subscripts, it can appear in an expression anywhere a value is permitted. Each subscript can be basic or relative. (A basic subscript is an expression that does not depend on the subscript of a series. A relative subscript is an expression added to, or subtracted from, a special identifier ($) that represents the subscript of a series.) Arrays with relative subscripts can only appear in expressions that initialize a series or define values that will be used to initialize a series.
The following is an example.
series Deductions = from 2010 to 2013: 100*A[$-2010][1];
With this definition and the previous one for the array called A, Deductions[2010] equals 200, Deductions[2011] equals 500, Deductions[2012] equals 800, and Deductions[2013] equals 1100.
Certain spreadsheet functions convert an array into a single number. When used as an argument in these functions, the array name is used without subscripts or with a subrange specification and without any additional operands or operators. In other words, the array name in the function argument cannot be part of an expression. This is the only way you can use an array without subscripts or with a subrange specification in DPL. For example, the following expression uses a function that can take an array name as its argument.
5 * @sum(A) - 25
For example, you may refer to the following array in three ways.
array Costs =
{10000, 20000, 30000, 40000;
12500, 22500, 32500, 42500;
15000, 25000, 35000, 45000};
- With subscripts, referring to a single element (Year1Cost is 10000).
value Year1Cost = Costs[0][0];
- Without subscripts, referring to all the elements in the array (CostTotal is 330000).
value CostTotal = @sum(Costs);
- With a subrange specification, referring to a selected subset of the elements in the array (CostSubTotal
is 187500).
value CostSubTotal = @sum(Costs{0..1}{1..3});
An array subrange is an array created from a portion of another array. An array subrange specification looks similar to a reference to a single array element, except that curly braces { } are used (rather than square brackets [ ]), and the parameters are two numbers or expressions separated by two periods (..) rather than single numbers or expressions.
The first parameter refers to the rows, and the second parameter to the columns. Remember that the first element of the array is Costs[0][0]. If the subrange refers to the first row only, you may omit the row reference:
Costs{2..3} or Costs{0..0}{2..3}
The boundaries on the subrange may be variable expressions, allowing you to vary the starting and ending position dynamically depending on the states of events:
chance CostLevel.{3} = {0.5,0.2,0.3,}
= 0,1,2; chance Years.{2} = {0.5}
= 2,3; value CostSum = @sum(Costs{CostLevel..CostLevel}
{0..Years});
An array subrange consisting of a single element is not equivalent to a subscripted reference to that element.
Costs{0..0}{1..1} does not equal Cost [0][1]
The two expressions refer to the same value. However, the first results in an array with one element, whereas the second results in a single value. The expression Costs{0..0}{1..1} can be used where an array is expected (@npv(Costs{0..0}{1..1})). The expression Costs[0][1] can be used where a single value is expected (Costs[0][1] + 200).
When referring to a single element in a subrange, treat the subrange as a separate array. For example, the expression @index(Costs{0..1}{1..3}, 2, 1) refers to the same element, 32500, as the expression
Costs[1][2]
Notice that although the element is in the third column of the array (the first column is 0), it is in the second column of the subrange. (The @index function takes the array, column, and row, respectively, as arguments).
Some spreadsheet functions differentiate between null elements and the number 0. DPL treats null elements the same way a spreadsheet treats empty (null) cells. For instance, the function @count () counts the number of elements in an array, but omits null elements from the count.
Some spreadsheet functions that take an array name as an argument require that the array have only one row or one column. For instance, the function @irr() computes the internal rate of return for a set of payments. The payments can be elements of an array, but the calculation only makes sense if the array has one row or one column. Consider a program with the following array definition.
array C = {-5; 1; 2; 3; 4; ; 6};
This array has one column of seven elements, one of which is null. You must use two subscripts to refer to the elements of this array because it has more than one row. After this definition, the program in this example contains the following expression.
100 * @irr(1 / C[2][0], C)
The first argument of this function is an expression that provides an initial guess at the answer. If this expression contains the name of an array, it must have subscripts. The second argument is the name of an array. This name cannot have any subscripts. If the array referenced by the second subscript does not have one row or one column, DPL will generate an error message. The expression in this example equals 37.0432.
Versions: DPL Professional, DPL Enterprise, DPL Portfolio
See Also