Getting Started
Introduction
Sample Programs
IDEs
History
Advice
Mini-Tutorial
Tutorials
Code Snippets

Resources
Web Sites
More Tutorials
Forums
Vendors/Tools
Books
Magazines
Newsletters
NewsGroups
User Groups
Talk Shows
Blogs

Controls
Overview
Button
Check3State
Checkbox
ComboBox
Frame
Graphic
Image
ImageX
ImgButton
ImgButtonX
Label
Line
ListBox
ListView
Option
Progress Bar
Scrollbar
StatusBar
TAB
TextBox
Toolbar
TreeView

GBIC >> PowerBASIC >> Tutorials >> Arrays

PowerBASIC Information Center Tutorials
These tutorials were written to help you get a quick, but thorough, understanding of PowerBASIC - the scope of the language as well as it's specific capabilities.

Introduction       Projects       Language           Messages       Functions           Advanced
  • Overview
  • Examples
  • IDE
  • Compilation
  • Distribution
  • Project Files
  • DDT Windows
  • Controls
  • Menus
  • Dialogs  
  • Help Files
  • Resources  
  • Templates  
  • Project Shell  
  • Syntax
  • Operators
  • Data Types
  • Variables
  • Scope
  • Declarations  
  • Procedures
  • Flow Control
  • Windows
  • Messages
  • Callbacks
  • Mouse
  • Keyboard
  • Dialogs
  • Controls
  • Subclassing
  • Arithmetic
  • Trig  
  • Strings
  • Arrays
  • Date/Time
  • Printing
  • Files
  • Folders
  • Keyboard
  • Mouse
  • Sound
  • System
  • Error Traps
  • Debugging
  • Objects
  • Graphics
  • Databases
  • API
  • DLLs
  • ASM
  • Threads
  • 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.

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