class Array

An array of elements, in one or more dimensions.

Syntax

[<oRef> =] new Array([<dim1 expN> [,<dim2 expN>...]])

<oRef>

A variable or property in which to store a reference to the newly created Array object.

<dim1 expN> [,<dim2 expN> ...]

The size of the array in each specified dimension. If no dimensions are specified, the array is a one-dimensional array with zero elements.

Properties

The following tables list the properties and methods of the Array class. (No events are associated with this class.)

Property	Default	Description
baseClassName	ARRAY	Identifies the object as an instance of the Array class
className	(ARRAY)	Identifies the object as an instance of a custom class. When no custom class exists, defaults to baseClassName
dimensions		The number of dimensions in the array
size	0	The number of elements in the array
Method	Parameters	Description
add( )	<exp>	Increases the size of a one-dimensional array by one and assigns the passed value to the new element.
delete( )	<position expN> [,1 \| 2]	Deletes an element from a one-dimensional array, or deletes a row (1) or column (2) of elements from a two-dimensional array, without changing the size of the array.
dir( )	[<filespec expC>]	Stores in the array five characteristics of specified files: name, size, modified date, modified time, and file attribute(s). Returns the number of files whose characteristics are stored.
dirExt( )	[<filespec expC>]	Same as dir( ) method, but adds short (8.3) file name, create date, create time, and access date.
element( )	<row expN> [,<col expN>]	Returns the element number for the element at the specified row and column.
fields( )		Stores table structure information for the current table in the array
fill( )	<exp> , <start expN> [, <count expN>]	Stores a specified value into one or more elements of the array.
getFile( )	[<filename skeleton expC> [, <title expC> [, <suppress database expL>],[<file types list expC>]]]	Displays a dialog box from which a user can select multiple files.
grow( )	1 \| 2	When passed 1, adds a single element to a one-dimensional array or a row to a two-dimensional array; when passed 2, adds a column to the array.
insert( )	<element expN> [,1 \| 2]	Inserts an element, row (1), or column (2) into an array without changing the size of the array (the last element, row, or column is lost).
resize( )	<rows expN> [, <cols expN> [, <retain values>]]	Increases or decreases the size of an array. First passed parameter indicates the new number of rows, the second parameter indicates the new number of columns. If the third parameter is zero, current values are relocated; if nonzero, they are retained in their old positions.
scan( )	<exp> , <start expN> [, <count expN>]	Searches an array for the specified expression; returns the element number of the first element that matches the expression, or zero if the search is unsuccessful.
sort( )	<start expN> [, <count expN> [, 0 \| 1 ]]	Sorts the elements in a one-dimensional array or the rows in a two-dimensional array in ascending (0) or descending (1) order.
subscript( )	<element expN> 1 \| 2	Returns the row (1) or column (2) subscript for the specified element number.

Description

An Array object is a standard array of elements, addressed by a contiguous range of numbers in one or more dimensions. The array can hold as many elements as memory allows. You can create arrays that contain more than two dimensions, but most dBL Array methods work only on one- or two-dimensional arrays. For a two-dimensional array, the first dimension is considered the row and the second dimension is the column. For example, the following statement creates an array with 3 rows and 4 columns:

a = new Array( 3, 4 )

There are two ways to refer to individual elements in an array; you can use either element subscripts or the element number. Element subscripts, one for each dimension, are values that represent the element’s position in that dimension. For a two-dimensional array, they indicate the row and column in which an element is located. Element numbers indicate the sequential position of the element in the array, starting with the first element in the array and increasing in each dimension, with the last dimension first. For a two-dimensional array, the first element is in the first column of the first row, the second element is in the second column of the first row, and so on.

To determine the number of dimensions in an array, check its dimensions property (it’s read-only). The array’s size property reflects the number of elements in the array. To determine the number of rows or columns in a two-dimensional array, use the ALEN( ) function. There is no built-in way to determine the size of dimensions above two.

In an Array object, element numbering starts with one. You cannot create elements outside the defined range of elements or subscripts (although you could change the dimensions of the array if desired). For example, a 3-row, 4-column array has 12 elements, numbered 1 to 12. The first element’s subscripts are [1,1] and the last element is [3,4].

Certain dBL methods require the element number, and others require the subscripts. If you are using one- or two-dimensional arrays, you can use element( ) to determine the element number if you know the subscripts, and subscript( ) to determine the subscripts if you know the element number.

Array elements may contain any data type, including object references to other arrays. Therefore you can create nested arrays (multi-dimensional arrays of arrays with fixed length in each dimension), ragged arrays (nested arrays with variable lengths), arrays of associative arrays, and so on.

With both nested and multi-dimensional arrays, you end up with multiple dimensions or levels of elements, but when you nest arrays, you create separate array objects, and the methods that are designed to work on the multiple dimensions of a single Array object will not work on the separate dimensions of the nested arrays.

In addition to creating an array with the NEW operator, you can create a populated one-dimensional array using the literal array syntax. For example, this statement

a1 = {"A", "B", "C"}

creates an Array object with three elements: "A", "B", and "C". You can nest literal arrays. For example, if this statement:

a2 = { {1, 2, 3}, a1 }

followed the first, you would then have a nested array.

To access a value in a nested array, use the index operators in series. Continuing the example, the third element in the first array would be accessed with:

x = a2[1][3] // 3

One-dimensional arrays are the only Array objects that are allowed to have zero elements. This is particularly useful for building arrays dynamically. To create a zero-element array, create a NEW Array with no parameters:

a0 = new Array( )

Then use the add( ) method to add elements to the array.