The Gambas interpreter offers you two types of native container classes.
A collection is a collection of items that are indexed using a key of the type string? chapter 7.5 Collection. Only elements of the data type' Variant' can be stored in a collection. The values are stored internally in a hash table that grows dynamically when more elements are inserted into it.
An array is a set of elements that are indexed using an integer type key and stored in a memory block. All elements in an array have the same data type and there is an array class for each native data type.
Arrays can be one- and multi-dimensional. If they are multidimensional, the elements are indexed by more than one integer value. If an array has exactly one dimension, it can be dynamically reduced or expanded using the Resize () method.
Chapters 7.4.0 to 7.4.9 are not only dedicated to the general class array with its properties and methods, but also give an overview of the following topics, with no order of precedence implying the order of precedence:
The class array (gb) is the Parent class for each other array class. An array is to be understood as a data container whose elements can be accessed with a numeric key (index).
The class Array (gb) has these properties:
|Bounds||Array.Bounds||A virtual class is returned. The number of dimensions of an array is specified by the property Array. Bounds. Count and the size of the Nth dimension can be queried via Array. Bounds[N].|
|Count||Integer||Number of elements in the array.|
|Length||Integer||Number of elements in the array. The Count and Length properties are used synonymously.|
|Data||Pointer||Pointer to the array data.|
|Dim||Integer||Number of dimensions of an array.|
|Max||Integer||Largest index of an array. The following applies: Array.max = array.count - 1.|
|Type||Integer||Type of data that can be inserted into an array? http://gambaswiki.org/wiki/cat/constant|
Table 188.8.131.52.1: Properties of the class Array (gb)
The class Array (gb) has basic methods and special methods, but these do not apply to all array classes. The next section introduces and describes the basic methods:
|Clear ()||Deletes all elements in an array.|
|Remove (Index As Integer[, Length As Integer]||Deletes one or more elements in an array.|
|Resize (Size As Integer)||Changes the size (number of elements) of an array.|
Table 184.108.40.206.4.1: Methods 1 of class Array (gb)
In the following table,' array type' always stands for the data type of an element in the array.
|Add (Value As Array type[ Index As Integer]||Insert a new element into the array at the position' Index'. All subsequent elements are automatically moved down one position. If' Index' is not specified, a new element is inserted at the end of the array.|
|Copy ([Start As Integer, Length As Integer])||The function returns as a function value the 1:1 copy of the original in a new array object. If the optional Start=s argument is specified, only an array with the elements starting from start position s is generated. If Length=k is specified, only k elements will be copied to the new array (object) from the start position s on.|
|Delete (Start As Integer[, Length As Integer])||Delete is used synonymously for Extract (..).|
|Extract (Start As Integer[, Length As Integer])||Deletes one or more elements in the original array from' Start=s' and returns them (as function value) in an array. If the optional argument' Length=k' is specified, then from position s on exactly k elements are deleted from the array and returned as function value. If k is negative, the (-k) elements are extracted from s to backward and returned.|
|Exist (Value As Array type[, Mode As Integer])||Returns True if the specified element exists in the array. The optional' Mode' argument determines the comparison method.|
|Fill (value as array type[, Start As Integer, Length As Integer]||Fills an array with the given value. If the optional parameter' Start=s' is specified, then the default value is inserted from the start position s on. If the parameter' Length=k' is specified (optional), the predefined value is inserted as a k-fold value.|
|Find (Value As Array type[, Mode As Integer, Start As Integer])||Returns the position at which the search element was first found in the array. If the search string does not exist in the array, -1 is returned as a function value. If the optional argument' Start=s' is specified, the search starts from index s. The' Mode' argument determines the comparison method.|
|Insert (array As Array type[, Pos As Integer]) As Array type||Inserts the elements of a given array into the original array at the end (default). However, if the optional argument' Pos=p' is specified, the given array will be inserted into the original array from position p on.|
|Pop ()||Removes the last element of an array and returns this element as a function value. If the original array is empty, an error is triggered.|
|Push (value as array type)||Inserts an element at the end of an array.|
|Reverse ()||The order of the array elements is inverted - the array elements E0… En are rearranged to En…E0: The inverted array is returned as a function value.|
Tabel 220.127.116.11.4.2: Methods 2 of class Array
Gambas has a predefined array class for each native data type –> chapter 18.104.22.168. the name of these classes is the name of the data type followed by square brackets.
Boolean, Byte, Short, Integer, Long, Single, Float, Date, String, Object, Pointer und Variant
Please note the following notes, as all arrays do not have all and other methods:
Arrays can have these methods in the following table:
|Sort ([ Mode As Integer])||The elements in the array are sorted. Optionally, the sorting sequence can be defined via Mode. –> gb.Ascent (a. Z, standard) and gb.Descent (e. g. A)|
|Join ([ Separator As String, Escape As String]) As String||Chains the strings stored in the arrays. Separator is a string to be inserted between two strings of the array. The standard separator is a comma. Escape is used to enclose each string. If Escape consists of two characters, the first is the start escape character and the second is the end escape character. Individual escape characters in the strings are duplicated. The join function is the opposite of the split function.|
|Read (stream As Stream[, Start As Integer, Length As Integer]||Fills an array by reading the data directly from a stream. Start specifies where the data is stored in the array. By default, the data is stored from the beginning. Length is the number of elements that are read from the file. By default, all data is read until the end of the array is reached.|
|ToString ([ Start As Integer, Length As Integer]) As String||The function returns the array contents as a string. Start is the index of the first byte to be extracted. By default, Start equals 0, Length is the number of bytes to extract. By default, everything is extracted to the end of the array.|
|FindByRef (Value As Object[, Start As Integer]) As Integer||The function returns the position of the first occurrence of the specified object in the array. If Start is specified, the search starts at the start position. By default, the entire array is searched. If the specified object cannot be found, -1 is returned as a function value. Unlike Find (), the function FindByRef (Value As Object[, Start As Integer]) always compares the objects according to their identity (i. e. their address in memory). The special _compare () method is not used.|
|ExistByRef (Value As Object) As Boolean||The function returns True as a function value if the specified object is stored in the array. In contrast to Exist (), the function ExistByRef (Value As Object) always compares the objects according to their identity (i. e. their address in memory). The special _compare () method is not used.|
Table 22.214.171.124.1: Methods 3 of the class array