Array Functions
PowerBASIC provides very good support of arrays, which are variables that can contain multiple values. Each value is called an element and is referenced by a long-integer index. PowerBASIC supports up to 4,294,967,295 elements in an array.

Arrays can be of any data type, string or numeric, but data types may not be mixed within an array - i.e., all elements must be of the same data type. For example, one element cannot be a string, while another is numeric.

Here's a quick reference of the available array functions, categorized by the function provided.

Declaring an Array - Local Scope
In addition to using the DIM statement, array variable with local scope (for use inside a procedure) can be declared with any of the following PowerBASIC declaration statements.

    INSTANCE A(5) AS INTEGER   'allowed only inside a Class

See the tutorials on declarations and scope for more information on using these declaration statements.

Array Bounds
The default lower bound on a PowerBASIC array is zero. The lower bound can be set to a different value as shown in the following examples.

    Dim A(5) AS STRING          ' range 0 to 5, 6 elements
    Dim A(10 to 20) AS STRING   ' range 10 to 20, 11 elements

Multi-Dimensional Arrays
Arrays can have more than one dimension, as shown in the following examples.

    Dim A(2,5) AS INTEGER         ' 2x5 array, default 0 lower bound
    Dim A(5 to 10, 5) AS STRING   ' 6x6 array, explicit index range

Declaring an Array - Global Scope
To declare an array variable with global scope (for use in any procedure anywhere in the program), use the GLOBAL or THREADED statements outside procedures. Empty parentheses (no subscripts) must be used in the declaration statements. This next example shows two array variable declarations made outside the PBMain() function.

    GLOBAL x() As Long                'GLOBAL
    THREADEd y() As String            'THREADED
    Function PBMain() As Long
        ... statements
    End Function

Then, before using the arrays, the bounds of the arrays must be set using a DIM or REDIM statement within a procedure. With global arrays, both the array size and data type can be changed.

If DIM is used, the type cannot be changed. If REDIM is used, the global variable type can be changed.

Here's an example of an array variable declared with global scope. It shows using DIM to set the array bounds in one procedure and then accessing the array in another procedure.

    GLOBAL A() As String       'GLOBAL or THREADED can be used

    Function PBMain()
       DIM A(5)                'set bounds inside a procedure
       A(2) = "yes"
    End Function
    Sub TryThis
        MSGBox A(2)             'displays "yes"
    End Sub

Resizing an Array
To resize an array use the REDIM statement as in the following simple example.

    DIM x(5) As Long
    REDIM x(7) As Long

REDIM works on array variables declared with any of the DIM/LOCAL/STATIC/INSTANCE/GLOBAL/THREADED statements.

When resizing variables with local scope, the REDIM statement cannot change the type of the variable.

When resizing variables with global scope, the REDIM statement is allowed to change the type of the variable.

The REDIM need be done only once, at which point the bounds of the array and its values are set regardless of which procedure accesses the array. The REDIM can, however, be repeated as often as necessary to resize the array variable.

Using Variants
Using the PowerBASIC LET statement, an entire array can be placed inside a variant data type. This is especially useful in certain COM operations.

Using variants which contain arrays is discussed in the tutorial section on COM.

When used by itself, REDIM all resets the values in an array. To maintain the values in the array, use "REDIM PRESERVE" instead.

File Operations
It's very common to read a text file into an array, with one line of text per array element. It's also very common to write a string array to a text file, each array element written as a separate line of text.

PowerBASIC's capabilities to perform these tasks are discussed in the tutorial section on files. But here is a one-line description of the file functions which support reading/writing/creating arrays.

Bit-Level Arrays
All variables are stored as bits of memory. An Integer, for example, is 2 bytes or 32 bits of memory. If you wanted to create an array with 25 values, all zero or one, you could use a simple statemment like DIM A%(24), which would require 25x32=800 bits of memory.

If the goal is to store only zero's or one's, it would be much more efficient to store data 1 bit at a time - reducing the storage requirements by about 97%!

PowerBASIC provides such a capability by offering functions which can set/reset individual bits in an integer-type variable. PowerBASIC uses the terminology "implied bit-array" to refer to a variable used in such a way.

See the PowerBASIC Help file for more information on using the supplied BIT and BIT CALC statement to work with implied bit-arrays.

Array Function
PowerBASIC provides the ARRAY function to modify, search and sort arrays. ARRAY contains five different options:

    ARRAY ASSIGN - set value of multiple array elements
    ARRAY DELETE - delete a single array element
    ARRAY INSERT - insert a single element into an array
    ARRAY SCAN   - search an array for elements matching an expression
    ARRAY SORT   - sort all or part of an array

Array Function Listing
Here's a simple listing of the array functions from the top of the page, with a one-line description of what the function does. Examples are given in the next section.

Array Functions Reference
Here are examples for each of the array functions. The functions are list in alphabetical order.

All of the examples assume the following statements have been executed to create an array A() and to set the value of its six elements:

    DIM A(5) AS INTEGER                ' 6 elements (index range 0 to 5)
    A(0)=7: A(1)=0: A(2)=2: A(3)=6     ' set 1st four elements
    A(4)=3: A(5)=4                     ' values now set to 7,0,2,6,3,4

If you have any suggestions or corrections, please let me know.