Declaring arrays

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 strings

Incorrect 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 -20

Arrays 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 point

This declaration creates three decimal arrays:

decimal{3} lc_first[10],lc_second[15,5],lc_third[ ]

Values for array elements

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

Size of variable-size arrays

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].

More about arrays

This section provides technical details about:

Assigning one array to another

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 = a

To 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 = a

If 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 = a

Multidimensional 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:

1 for a[1,1]
3 for a[1,2]
2 for a[2,1]
4 for a[2,2]

Initializing a with an arraylist produces the same result:

integer a[2,2] = {1,2,3,4}

The following section describes arraylists.

Using arraylists to assign values to an array

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}

1
4
2
5
3
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}

1
3
 
5
0
2
4
 
6
0

Errors that occur when addressing arrays

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.