Description
An array is an indexed collection of elements of a single datatype. In PowerBuilder, an array can have one or more dimensions. One-dimensional arrays can have a fixed or variable size; multidimensional arrays always have a fixed size. Each dimension of an array can have 2,147,483,647 bytes of elements.
Any simple variable declaration becomes an array when you specify brackets after the variable name. For fixed-size arrays, you specify the sizes of the dimensions inside those brackets.
Syntax
{ access } datatype variablename { d1, ..., dn } { = { valuelist } }The following table describes the parameters used to declare array variables.
|
Parameter |
Description |
|---|---|
|
access (optional) |
(For instance variables only) Keywords specifying the access for the variable. For information, see Access for instance variables. |
|
datatype |
The datatype of the variable. You can specify a standard datatype, a system object, or a previously defined structure. For decimals, you can specify the precision of the data by including an optional value in brackets after datatype (see Syntax of a variable declaration): decimal {2} variablename [ ]For blobs, fixed-length blobs within an array are not supported. If you specify a size after datatype, it is ignored. |
|
variablename |
The name of the variable (name must be a valid PowerScript identifier, as described in Identifier names). You can define additional arrays with the same datatype by naming additional variable names with brackets and optional value lists, separated by commas. |
|
[ { d1, ..., dn } ] |
Brackets and (for fixed-size arrays) one or more integer values (d1 through dn, one for each dimension) specifying the sizes of the dimensions. For a variable-size array, which is always one-dimensional, specify brackets only. For more information on how variable-size arrays change size, see Size of variable-size arrays. For a fixed-size array, the number of dimensions is determined by the number of integers you specify and is limited only by the amount of available memory. For fixed-size arrays, you can use TO to specify a range of element numbers (instead of a dimension size) for one or more of the dimensions. Specifying TO allows you to change the lower bound of the dimension (upperbound must be greater than lowbound): [
d1lowbound TO d1upperbound {, ... ,
dnlowbound TO dnupperbound }
] |
|
{ valuelist } (optional) |
A list of initial values for each position of the array. The values are separated by commas and the whole list is enclosed in braces. The number of values cannot be greater than the number of positions in the array. The datatype of the values must match datatype. |
Examples
These declarations create variable-size arrays:
integer li_stats[ ] // Array of integers.
decimal {2} ld_prices[ ] // Array of decimals with
// 2 places of precision.
blob lb_data[ ] // Array of variable-size
// blobs.
date ld_birthdays[ ] // Array of dates.
string ls_city[ ] // Array of strings.
// Each string can be
// any length.This statement declares a variable-size array of decimal number (the declaration does not specify a precision, so each element in the array takes the precision of the value assigned to it):
dec lc_limit[ ]
Fixed arrays
These declarations create fixed-size, one-dimensional arrays:
integer li_TaxCode[3] // Array of 3 integers.
string ls_day[7] // Array of 7 strings.
blob ib_image[10] // Array of 10
// variable-size blobs.
dec{2} lc_Cost[10] // Array of 10 decimal
// numbers.
// Each value has 2 digits
// following the decimal
// point.
decimal lc_price[20] // Array of 20 decimal
// numbers.
// Each takes the precision
// of the value assigned.Using TO to change array index values
These fixed-size arrays use TO to change the range of index values for the array:
real lr_Rate[2 to 5] // Array of 4 real numbers:
// Rate[2] through Rate[5]
integer li_Qty[0 to 2] // Array of 3 integers
string ls_Test[-2 to 2] // Array of 5 strings
integer li_year[76 to 96] // Array of 21 integers
string ls_name[-10 to 15] // Array of 26 stringsIncorrect declarations using TO
In an array dimension, the second number must be greater than the first. These declarations are invalid:
integer li_count[10 to 5] // INVALID: 10 is
// greater than 5
integer li_price[-10 to -20] // INVALID: -10
// is greater than -20Arrays with two or more dimensions
This declaration creates a six-element, two-dimensional integer array. The individual elements are li_score[1,1], li_score[1,2], li_score[1,3], li_score[2,1], li_score[2,2], and li_score[2,3]:
integer li_score[2,3]
This declaration specifies that the indexes for the dimensions are 1 to 5 and 10 to 25:
integer li_RunRate[1 to 5, 10 to 25]
This declaration creates a 3-dimensional 45,000-element array:
long ll_days[3, 300, 50]
This declaration changes the subscript range for the second and third dimension:
integer li_staff[100, 0 to 20, -5 to 5]
More declarations of multidimensional arrays:
string ls_plant[3,10] // two-dimensional array
// of 30 strings
dec{2} lc_rate[3,4] // two-dimensional array of 12
// decimals with 2 digits
// after the decimal pointThis declaration creates three decimal arrays:
decimal{3} lc_first[10],lc_second[15,5],lc_third[ ]General information
PowerBuilder initializes each element of an array to the same default value as its underlying datatype. For example, in a newly declared integer array:
integer li_TaxCode[3]
the elements li_TaxCode[1], li_TaxCode[2], and li_TaxCode[3] are all initialized to zero.
For information about default values for basic datatypes, see Initial values for variables.
Simple array
In a simple array, you can override the default values by initializing the elements of the array when you declare the array. You specify the values in a comma-separated list of values enclosed in braces. You do not have to initialize all the elements of the array, but you cannot initialize values in the middle or end without initializing the first elements.
Multidimensional array
In a multidimensional array, you still provide the values in a simple, comma-separated list. When the values are assigned to array positions, the first dimension is the fastest-varying dimension, and the last dimension is the slowest-varying. In other words, the values are assigned to array positions by looping over all the values of the first dimension for each value of the second dimension, then looping over all the values of the second dimension for each value of the third, and so on.
Assigning values
You can assign values to an array after declaring it using the same syntax of a list of values within braces:
integer li_Arr[]
Li_Arr = {1, 2, 3, 4}
Examples
Example 1
This statement declares an initialized one-dimensional array of three variables:
real lr_Rate[3]={1.20, 2.40, 4.80}Example 2
This statement initializes a two-dimensional array:
integer li_units[3,4] = {1,2,3, 1,2,3, 1,2,3, 1,2,3}As a result:
Li_units[1,1], [1,2], [1,3], and [1,4] are all 1
Li_units[2,1], [2,2], [2,3], and [2,4] are all 2
Li_units[3,1], [3,2], [3,3], and [3,4] are all 3
Example 3
This statement initializes the first half of a 3-dimensional array:
integer li_units[3,4,2] = &
{1,2,3, 1,2,3, 1,2,3, 1,2,3}As a result:
Li_units[1,1,1], [1,2,1], [1,3,1], and [1,4,1] are all 1
Li_units[2,1,1], [2,2,1], [2,3,1], and [2,4,1] are all 2
Li_units[3,1,1], [3,2,1], [3,3,1], and [3,4,1] are all 3
Li_units[1,1,2], [1,2,2], [1,3,2], and [1,4,2] are all 0
Li_units[2,1,2], [2,2,2], [2,3,2], and [2,4,2] are all 0
Li_units[3,1,2], [3,2,2], [3,3,2], and [3,4,2] are all 0
General information
A variable-size array consists of a variable name followed by square brackets but no number. PowerBuilder defines the array elements by use at execution time (subject only to memory constraints). Only one-dimensional arrays can be variable-size arrays.
Because you do not declare the size, you cannot use the TO notation to change the lower bound of the array, so the lower bound of a variable-size array is always 1.
How memory is allocated
Initializing elements of a variable-size array allocates memory for those elements. You specify initial values just as you do for fixed-size arrays, by listing the values in braces. The following statement sets code[1] equal to 11, code[2] equal to 242, and code[3] equal to 27. The array has a size of 3 initially, but the size will change if you assign values to higher positions:
integer li_code[ ]={11,242,27}For example, these statements declare a variable-size array and assigns values to three array elements:
long ll_price[ ] ll_price[100] = 2000 ll_price[50] = 3000 ll_price[110] = 5000
When these statements first execute, they allocate memory as follows:
-
The statement ll_price[100]=2000 will allocate memory for 100 long numbers ll_price[1] to ll_price[100], then assign 0 (the default for numbers) to ll_price[1] through ll_price[99] and assign 2000 to ll_price[100].
-
The statement ll_price[50]=3000 will not allocate more memory but will assign the value 3000 to the 50th element of the ll_price array.
-
The statement ll_price[110]=5000 will allocate memory for 10 more long numbers named ll_price[101] to ll_price[110] and then assign 0 (the default for numbers) to ll_price[101] through ll_price[109] and assign 5000 to ll_price[110].
This section provides technical details about:
General information
When you assign one array to another, PowerBuilder uses the following rules to map the values of one onto the other.
One-dimensional arrays
To an unbounded array
The target array is the same as the source:
integer a[ ], b[ ]
a = {1,2,3,4}
b = aTo a bounded array
If the source array is smaller, values from the source array are copied to the target array and extra values are set to zero. In this example, b[5] and b[6] are set to 0:
integer a[ ], b[6]
a = {1,2,3,4}
b = aIf the source array is larger, values from the source array are copied to the target array until it is full (and extra values from the source array are ignored). In this example, the array b has only the first three elements of a:
integer a[ ], b[3]
a = {1,2,3,4}
b = aMultidimensional arrays
PowerBuilder stores multidimensional arrays in column major order, meaning the first subscript is the fastest varying -- [1,1], [2,1], [3,1]).
When you assign one array to another, PowerBuilder linearizes the source array in column major order, making it a one-dimensional array. PowerBuilder then uses the rules for one-dimensional arrays (described above) to assign the array to the target.
Not all array assignments are allowed, as described in the following rules.
One multidimensional array to another
If the dimensions of the two arrays match, the target array becomes an exact copy of the source:
integer a[2,10], b[2,10] a = b
If both source and target are multidimensional but do not have matching dimensions, the assignment is not allowed and the compiler reports an error:
integer a[2,10], b[4,10] a = b // Compiler error
One-dimensional array to a multidimensional array
A one-dimensional array can be assigned to a multidimensional array. The values are mapped onto the multidimensional array in column major order:
integer a[ ], b[2,2] b = a
Multidimensional array to a one-dimensional array
A multidimensional array can also be assigned to a one-dimensional array. The source is linearized in column major order and assigned to the target:
integer a[ ], b[2,2] a = b
Examples
Suppose you declare three arrays (a, b, and c). One (c) is unbounded and one-dimensional; the other two (a and b) are multidimensional with different dimensions:
integer c[ ], a[2,2], b[3,3] = {1,2,3,4,5,6,7,8,9}Array b is laid out like this:
1 for b[1,1] |
4 for b[1,2] |
7 for b[1,3] |
2 for b[2,1] |
5 for b[2,2] |
8 for b[2,3] |
3 for b[3,1] |
6 for b[3,2] |
9 for b[3,3] |
This statement causes a compiler error, because a and b have different dimensions:
a = b // Compiler error
This statement explicitly linearizes b into c:
c = b
You can then assign the linearized version of the array to a:
a = c
The values in array a are laid out like this:
Initializing a with an arraylist produces the same result:
integer a[2,2] = {1,2,3,4}The following section describes arraylists.
General information
In PowerBuilder, an arraylist is a list of values enclosed in braces used to initialize arrays. An arraylist represents a one-dimensional array, and its values are assigned to the target array using the rules for assigning arrays described in Assigning one array to another.
Examples
In this declaration, a variable-size array is initialized with four values:
integer a[ ] = {1,2,3,4}In this declaration, a fixed-size array is initialized with four values (the rest of its values are zeros):
integer a[10] = {1,2,3,4}In this declaration, a fixed-size array is initialized with four values. Because the array's size is set at 4, the rest of the values in the arraylist are ignored:
integer a[4] = {1,2,3,4,5,6,7,8}In this declaration, values 1, 2, and 3 are assigned to the first column and the rest to the second column:
integer a[3,2] = {1,2,3,4,5,6}If you think of a three-dimensional array as having pages of rows and columns, then the first column of the first page has the values 1 and 2, the second column on the first page has 3 and 4, and the first column on the second page has 5 and 6.
The second column on the second page has zeros:
integer a[2,2,2] = {1,2,3,4,5,6}Fixed-size arrays
In PowerBuilder, referring to array elements outside the declared size causes an error at runtime; for example:
int test[10] test[11]=50 // This causes an execution error. test[0]=50 // This causes an execution error. int trial[5,10] trial [6,2]=75 // This causes an execution error. trial [4,11]=75 // This causes an execution error.
Variable-size arrays
Assigning a value to an element of a variable-size array that is outside its current values increases the array's size. However, accessing a variable-size array above its largest assigned value or below its lower bound causes an error at runtime:
integer li_stock[ ]
li_stock[50]=200
// Establish array size 50 elements.
IF li_stock[51]=0 then Beep(1)
// This causes an execution error.
IF li_stock[0]=0 then Beep(1)
// This causes an execution error.