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.

Create/Destroy	parse, erase
Initialize/Set Values	reset, ARRAY assign
Properties	arrayattr, lbound, ubound
Add/Delete Elements	ARRAY insert, ARRAY delete
Search/Sort	ARRAY scan, ARRAY sort
Matrix	mat
Implied Bit-Arrays	BIT, BIT CALC
File Operations	FileScan, Line Input#, Print#, GET, PUT

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.

    DIM A(5) AS INTEGER
    REDIM A(5) AS INTEGER
    LOCAL A(5) AS INTEGER
    STATIC A(5) AS INTEGER
    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"
       TryThis                 
    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.

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

• FILESCAN - read text file,
• LINE INPUT# - read lines into string array
• PRINT# - write array to sequential file
• PUT - write array to binary file
• GET - read array from binary file

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 ASSIGN - Assign a number of values to successive elements of an array
• ARRAY DELETE - Delete a single item from a given array
• ARRAY INSERT - Insert a single item into a given array
• ARRAY SCAN - Scan all or part of an array for a given value
• ARRAY SORT - Sort all or part of a given array
• ARRAYATTR - Return descriptive attributes of a given array
• ERASE - Deallocate array memory
• LBOUND - Return the lowest subscript of an array's specific dimension
• MAT - Matrix calculations on arrays
• PARSE - Parse a string and extract all delimited fields into an array
• RESET - Set an array subscript or an entire array to zero or null/empty
• UBOUND - Return the highest subscript of an array's specific dimension

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
    

• ARRAY ASSIGN - sets value of multiple array elements
  

      ARRAY ASSIGN A() = 7,0,2         ' assigns first 3 elements
      ARRAY ASSIGN A() = sin(7),4*2    ' values can be expressions
      

  Assignment starts with 1st array element. Values/expressions to assign must match array data type

• ARRAY DELETE - delete single array element
  

      ARRAY DELETE A(3)           ' delete element 3, 
                                  ' all remaining elements shifted, 
                                  ' last element = 0
  
      ARRAY DELETE A(2) FOR 2, 6  ' delete element 2,
                                  ' shift 2 elements - A(3) & A(4),
                                  ' A(4) = 6 (last element shifted)
                                  ' A(5) value unchanged
      

  Default index is 0. Array length does not change. Specified index value set to zero, followed by optional shift of specified number of elements. Value of last element can be specified.

• ARRAY INSERT - insert single element into array
  

      ARRAY INSERT A(3)           ' A(3) = 0
                                  ' all remaining elements shifted up,
                                  ' A(5) value is lost
  
      ARRAY INSERT A(2) FOR 2, 6  ' A(2) = 6
                                  ' shift 2 elements - A(3) & A(4),
                                  ' A(4) lost (last shifted element)
                                  ' A(5) unchanged
      

  Default index is 0. Array length does not change. Specified index value set to zero, followed by optional shift of specified number of elements. Last element value is lost.

• ARRAY SCAN - search array for elements matching an expression
  

      Numeric Arrays:
      ARRAY SCAN array([index]) [FOR count] , expression, TO iResult&
  
      ARRAY SCAN A(0), Val, TO iResult        ' entire array for Val
      ARRAY SCAN A(0 FOR 2, Val, TO iResult   ' elements 0-1 for Val
  
  
      String Arrays:
      ARRAY SCAN array([index]) [FOR count] , {FROM start TO end]
             [, COLLATE {UCASE | cstring}], expression, TO iResult&
  
      ARRAY SCAN A() FOR 2, 6, TO iResult  ' search for value 6
      

  Starting at index, returns relative position of first matching element. Returns value is NOT an index value!

• ARRAY SORT - sort all or part of an array
  

      Numeric Arrays:
      ARRAY SORT array([index]) [FOR count] [,TAGARRAY tarray()] 
               [,{ASCEND | DESCEND}]
  
      ARRAY SORT A(5) FOR 5, TAGARRAY B(), ASCEND
      

  Start sorting at index FOR count elements. Zero is default index. If no count, array is sorted from index to last element. Sort entire array if no index or count is provided. Sorts ascending (default) or descending.

  Can also swap elements in a 2nd array, called a tagarray, in the same order as the sorted array. Tagarray must have as many elements as sorted array, but can be of different data type.

      String Arrays:
  
      ARRAY SORT array([index]) [FOR count] [,FROM start TO end] 
           [, COLLATE {USECASE | cstring}] [,TAGARRAY tarray()] 
           [,{ASCEND | DESCEND}]
  
      ARRAY SORT A$()
      ARRAY SORT A$(5) FOR 5, FROM 0 TO 5, COLLATE UCASE, , ASCEND 
      

  Start sorting at index FOR count elements. Zero is default index. If no count, array is sorted from index to last element. Sort entire array if no index or count is provided. Sorts ascending (default)or descending.

  Can also swap elements in a 2nd array, called a tagarray, in the same order as the sorted array. Tagarray must have as many elements as sorted array, but can be of different data type.

  Can sort strings on subset of each element. Use FROM .. TO .. to define first/last characters to used for sorting.

  Can define custom string of 256 characters to use for sorting order.

  Can also swap elements in a 2nd array, called a tagarray, in the same order as the sorted array. Tagarray must have as many elements as sorted array, but can be of different data type.

• ARRAYATTR - return attributes of array
  

      iresult = ARRAYATTR( A(), AttrNum)
  
      AttrNum 0  TRUE (-1) if A() is dimensioned, FALSE (0) if not
              1  Array data type (built-in numeric equates)
              2  TRUE (-1) is array of pointers, FALSE (0) if not
              3  Number of dimensions
              4  Total number of elements
              5  Array element size (in bytes)
  
      DIM A(5) AS INTEGER          ' use A() in next 3 lines
      iResult = ARRAYATR (A(),0)   ' -1 (TRUE) - A() is dimensioned
      iResult = ARRAYATR (A(),2)   ' 0 (FALSE) - A() is not pointers
      iResult = ARRAYATR (A(),4)   ' 6 (indexes 0 thru 5)
      

• ERASE - deallocate array memory
  

      Dim a(5)         ' create array
      Erase a()        ' array not longer exists
      

• LBOUND - lower bound of array
  

      DIM A(5) AS INTEGER         # create array
      iLower = LBOUND(A)          # i = 0 (default array lower bound)
  
      DIM A(2 to 5) AS INTEGER    # create array
      iLower = LBOUND(A)          # i = 2 
      

• PARSE - Extract delimited fields from string into an array
  

      PARSE Main$, Array$(), ANY delimiters$
  
      PARSE a$, b$()                    'parse a$ into b$()
      PARSE "a:b:c:d", a()              'assigns 4 elements of string
      PARSE "a..b..c..d", a(), ".."     'assigns 4 elements of string
      PARSE "a:b,c-d", a(), ANY ":,-"   'assigns 4 elements of string
      

  CSV delimiting is default. With ANY, the delimiter string is treated as a list of individual characters.

• MAT - Matrix calculations on arrays
  Some operations act on the array, some create arrays, and others require two arrays.

      MAT a1() = CON           'Set all elements of a1() to one
      MAT a1() = CON(expr)     'Set all elements of a1() to value of expr
      MAT a1() = IDN           'Establish a1() as an identity matrix
      MAT a1() = ZER           'Set all elements of a1() to zero
      MAT a1() = a2() + a3()   'Addition
      MAT a1() = a2()          'Assignment
      MAT a1() = INV(a2())     'Inversion
      MAT a1() = (expr) * a2() 'Scalar Multiplication
      MAT a1() = a2() - a3()   'Subtraction
      MAT a1() = a2() * a3()   'Multiplication
      MAT a1() = TRN(a2())     'Transposition
      

• RESET - Set array/array element to zero or empty string
  

      Reset A$(5)    'sets indexed element to ""
      Reset A$()     'set all elements to ""
      

  Sets numeric array elements to zero.

• UBOUND - upper bound of array
  

      DIM A(5) AS INTEGER         # create array
      iUpper = UBOUND(A)          # i = 5
  
      DIM A(2 to 7) AS INTEGER    # create array
      iUpper = UBOUND(A)          # i = 7
      

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