Chapter 4: Array Routines

Overview

This chapter introduces the subroutines and functions supported by OpenOffice.org Basic that are used to manipulate arrays. It covers methods for manipulating arrays, creating arrays with data, creating arrays with no data, and changing the dimension of arrays. This chapter also introduces techniques that compensate for current bugs and other unexpected behaviors; and finally, it develops a method to inspect array variables .

An array is a data structure in which similar elements of data are arranged in an indexed structure-for example, a column of names or a table of numbers . OOo Basic has subroutines and functions that change array dimensions, inspect existing arrays, and convert between arrays and scalar (non-array) data types.

The majority of the routines listed in Table 1 require an array variable as the first argument. Array variables used as arguments to routines can be written with trailing parentheses. Parentheses after the variable are mandatory for arrays whose declaration includes dimensions, and optional for those declared without (see Listing 1 ). Failure to use required parentheses results in an error when the macro is compiled. For example, the variable a() in Listing 1 must always be referenced with parentheses when used as an argument. The variables b and c can be written as either b and c, or b() and c(). Many languages use square brackets rather than parentheses to denote an array variable. For example, some languages use a[] rather than a(); BASIC does not support this. There is no way to determine if a() refers to an array or a function while reading code; you must find where the item in question is declared.

Table 1: Summary of subroutines and functions related to arrays.

Function	Description
Array(args)	Return a Variant array that contains the arguments.
DimArray(args)	Return an empty Variant array. The arguments specify the dimension(s).
IsArray(var)	Return True if this variable is an array, False otherwise .
Join(array) Join(array, delimiter )	Concatenate the array elements separated by the optional string delimiter and return as a String. The default delimiter is a single space.
LBound(array) LBound(array, dimension)	Return the lower bound of the array argument. The optional dimension specifies which dimension to check. The first dimension is 1.
ReDim [Preserve] var(args) As Type	Change the dimension of an array using the same syntax as the DIM statement. The keyword Preserve keeps existing data intact. In OOo 2.0, the "As Type" will become optional.
Split(str) Split(str, delimiter) Split(str, delimiter, n)	Split the string argument into an array of strings. The default delimiter is a space. The optional argument n limits the number of strings returned.
UBound(array) UBound(array, dimension)	Return the upper bound of the array argument. The optional dimension specifies which dimension to check. The first dimension is 1.

Listing 1: Parentheses are not always required but are always allowed.

 Dim a(1 To 2)      'a() is declared with specified dimensions Dim b()            'b() is declared as an array without specified dimensions Dim c              'c is a variant and may reference an array. c = Array(1, 2)    'c references a Variant array Print IsArray(a()) 'True Print IsArray(b()) 'True Print IsArray(c()) 'True Print IsArray(a)   '***** Compile time error on this line ***** Print IsArray(b)   'True Print IsArray(c)   'True 

 

The word "dimension" is used to refer to arrays similarly to the way that "dimensions" is used to refer to spatial dimensions. For example, an array with one dimension is like a line; you can set boxes along the line that represent variables. An array with two dimensions is like a grid with rows and columns of data.

 Dim a(3) As Integer          'One-dimensional array Dim b(3 To 5) As String      'One-dimensional array Dim c(5, 4) As Integer       'Two-dimensional array Dim d(1 To 5, 4) As Integer  'Two-dimensional array