User Tools

Site Tools


k7:k7.4:start

7.4.0 Arrays

7.4.0.1 Native container classes

The Gambas interpreter offers you two types of native container classes.

7.4.0.1.1 Collection

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.

7.4.0.1.2 Array

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:

  • Native arrays
  • Derived arrays
  • One-dimensional arraysMultidimensional arrays (? dimensions)
  • Dynamic arrayInline arrays
  • Embeded arraysDeclaration of arrays
  • Inserting elements into an array
  • Access to elements of an array; including their display
  • Array copy
  • Export and import of arrays
  • Conversion: Array ←→ vector
  • Sorting the elements of an array

7.4.0.2 Class Array

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

7.4.0.3 Properties of the class array

The class Array (gb) has these properties:

PropertyData typeDescription
BoundsArray.BoundsA 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 IntegerNumber of elements in the array.
LengthIntegerNumber of elements in the array. The Count and Length properties are used synonymously.
DataPointerPointer to the array data.
DimIntegerNumber of dimensions of an array.
MaxIntegerLargest index of an array. The following applies: Array.max = array.count - 1.
TypeIntegerType of data that can be inserted into an array? http://gambaswiki.org/wiki/cat/constant

Table 7.4.0.3.1: Properties of the class Array (gb)

7.4.0.4 Methods of the class array

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:

MethodDescription
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 7.4.0.4.4.1: Methods 1 of class Array (gb)

Hints:

  • Clear(): Deletes all elements in a one-dimensional array and returns 0. If the array is multidimensional (–> chapter 7.4.4), then the values of all array elements - depending on the data type - are set to the default value.
  • Remove (i, k): Deletes the element with the specified index=i from the array. If the optional parameter Length=k is also set to k>0, k elements are deleted from the array starting with array[i]. If k is negative, then all elements array[i.. Max] are removed in the array.
  • Resize(s): With Array. resize (s) you set the number of elements in an array to the number=s. The number of elements in the array is thus reduced or increased. Either excess elements are removed from the end or additional elements are added - depending on the type of array with their default value for native arrays (–> chapter 7.4.3.1).

In the following table,' array type' always stands for the data type of an element in the array.

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

7.4.0.5 Array classes for native data types

Gambas has a predefined array class for each native data type –> chapter 7.4.3.1. 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:

  • For all (native) arrays - except Variant[] - there is the method Sort ([Mode As Integer]).
  • Only string[] has the method Join ([ Separator As String, Escape As String]).
  • For the native arrays Boolean[], Byte[], Short[], Integer[], Long[], Long[], Single[], Float[], Date[], Pointer[], there are two methods Read (stream as stream[, start as integer, length as integer] and Write (stream as stream[, start as integer, length as integer]).
  • The ToString method ([ Start As Integer, Length As Integer]) knows only byte[].
  • Only for the arrays Object[] you can use the two methods FindByRef (value as object[, start as integer] and ExistByRef (value as object).

Arrays can have these methods in the following table:

MethodDescription
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 StringChains 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 StringThe 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 IntegerThe 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 BooleanThe 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 7.4.0.5.1: Methods 3 of the class array

Download

7.4.0 Arrays

7.4.0.1 Native Container-Klassen

Der Gambas-Interpreter bietet Ihnen zwei Arten von nativen Container-Klassen.

7.4.0.1.1 Collection

Eine Collection ist eine Sammlung von Elementen, die über einen Schlüssel vom Typ String indiziert werden → Kapitel 7.5 Collection. Nur Elemente vom Datentyp 'Variant' können in einer Collection gespeichert werden. Die Werte werden intern in einer Hash-Tabelle gespeichert, die dynamisch wächst, wenn mehr Elemente in sie eingefügt werden.

7.4.0.1.2 Array

Ein Array ist eine Menge von Elementen, die über einen Schlüssel vom Typ Integer indiziert werden und in einem Speicher-Block gespeichert sind. Alle Elemente in einem Array haben den gleichen Datentyp und es gibt eine Array-Klasse für jeden nativen Datentyp.

Arrays können ein- und mehrdimensional sein. Sind sie mehrdimensional, werden die Elemente von mehr als einem Integer-Wert indiziert. Wenn ein Array genau eine Dimension besitzt, dann kann es mit der Resize()-Methode dynamisch verkleinert oder erweitert werden.

Die Kapitel 7.4.0 bis 7.4.9 widmen sich nicht nur der allgemeinen Klasse Array mit seinen Eigenschaften und Methoden, sondern geben auch einen Ein- und Überblick zu den folgenden Themen, wobei die Reihenfolge keine Rangfolge impliziert:

  • Native Arrays
  • Abgeleitete Arrays
  • Eindimensionale Arrays
  • Mehrdimensionale Arrays (→ Dimensionen)
  • Dynamisches Array
  • Inline-Arrays
  • Embeded-Arrays
  • Deklaration von Arrays
  • Einfügen von Elementen in ein Array
  • Zugriff auf Elemente eines Arrays; eingeschlossen deren Anzeige
  • Array-Kopie
  • Export und Import von Arrays
  • Konvertierung: Array ↔ Vektor
  • Sortierung der Elemente eines Arrays

7.4.0.2 Klasse Array

Die Klasse Array (gb) ist die Eltern-Klasse für jede andere Array-Klasse. Ein Array ist als Daten-Container aufzufassen, auf dessen Elemente mit einem numerischen Schlüssel (Index) zugegriffen werden kann.

7.4.0.3 Eigenschaften der Klasse Array

Die Klasse Array (gb) verfügt über diese Eigenschaften:

EigenschaftDatentypBeschreibung
BoundsArray.BoundsEs wird eine virtuelle Klasse zurückgegeben. Die Anzahl der Dimensionen eines Arrays wird durch die Eigenschaft Array.Bounds.Count angegeben und die Größe der N-ten Dimension kann man über Array.Bounds[N] abfragen.
Count IntegerAnzahl der Elemente im Array.
LengthIntegerAnzahl der Elemente im Array. Die Eigenschaften Count und Length werden synonym verwendet.
DataPointerZeiger auf die Array-Daten.
DimIntegerAnzahl der Dimension eines Arrays.
MaxIntegerGrößter Index eines Arrays. Dabei gilt: Array.Max = Array.Count - 1.
TypeIntegerTyp der Daten, die in ein Array eingefügt werden können → http://gambaswiki.org/wiki/cat/constant

Tabelle 7.4.0.3.1: Eigenschaften der Klasse Array (gb)

7.4.0.4 Methoden der Klasse Array

Die Klasse Array (gb) verfügt über grundlegende Methoden und spezielle Methoden, die jedoch nicht für alle Array-Klassen zutreffen. Im nächsten Abschnitt werden die grundlegenden Methoden vorgestellt und beschrieben:

MethodeBeschreibung
Clear()Löscht alle Elemente in einem Array.
Remove ( Index As Integer [ , Length As Integer ] )Löscht ein oder mehrere Elemente in einem Array.
Resize ( Size As Integer )Ändert die Größe (Anzahl der Elemente) eines Arrays.

Tabelle 7.4.0.4.1 : Methoden 1 der Klasse Array (gb)

Hinweise:

  • Clear(): Löscht alle Elemente in einem eindimensionalen Array und Array.Count gibt danach 0 zurück. Wenn das Array mehrdimensional (→ Kapitel 7.4.4) ist, dann werden die Werte aller Array-Elemente – je nach Datentyp – auf den Default-Wert gesetzt.
  • Remove(i,k): Löscht das Element mit dem angegebenen Index=i aus dem Array. Wenn auch der optionale Parameter Length=k mit k>0 gesetzt ist, werden k Elemente aus dem Array ab Array[i] gelöscht. Ist k negativ, dann werden alle Elemente Array[i..Max] im Array entfernt.
  • Resize(s): Mit Array.Resize(s) bringt man die Anzahl der Elemente in einem Array auf die Anzahl=s. Die Anzahl der Elemente im Array wird so verkleinert oder vergrößert. Entweder werden überschüssige Elemente vom Ende entfernt oder zusätzliche Elemente angehängt – entsprechend dem Typ des Arrays mit ihrem Default-Wert bei nativen Arrays (→ Kapitel 7.4.3.1).

In der folgenden Tabelle steht 'Array-Typ' immer für den Daten-Typ eines Elements im Array.

1x1MethodeBeschreibung
Add (Value As Array-Typ [ Index As Integer ])Es wird ein neues Element in das Array an der Stelle 'Index' eingefügt. Alle nachfolgenden Elemente werden automatisch um eine Position (nach unten) verschoben. Wird 'Index' nicht angegeben, wird ein neues Element am Ende des Arrays eingefügt.
Copy ([Start As Integer, Length As Integer])Die Funktion gibt als Funktionswert die 1:1-Kopie des Originals in einem neuen Array-Objekt zurück. Falls das optionale Argument Start=s angegeben ist, wird nur ein Array mit den Elementen ab Startposition s generiert. Ist Length=k angegeben, werden ab der Startposition s nur k Elemente in das neue Array(-Objekt) kopiert.
Delete (Start As Integer [,Length As Integer])Delete wird synonym für Extract(..) verwendet.
Extract (Start As Integer [,Length As Integer])Es werden ein oder mehrere Elemente im Original-Array ab der Position 'Start=s' gelöscht und (als Funktionswert) in einem Array zurückgegeben. Wird das optionale Argument 'Length=k' angegeben, dann werden ab Position s genau k Elemente aus dem Array gelöscht und als Funktionswert zurückgegeben. Ist k negativ, werden die (-k) Elemente von s an rückwärts extrahiert und zurückgegeben.
Exist (Value As Array-Typ [,Mode As Integer])Gibt True zurück, wenn das angegebene Element im Array vorhanden ist. Das optionale Argument 'Mode' bestimmt die Vergleichsmethode.
Fill ( Value As Array-Typ [ , Start As Integer, Length As Integer ] )Füllt ein Array mit dem vorgegebenen Wert. Ist der optionale Parameter 'Start=s' angegeben, dann wird der vorgegebene Wert ab Start-Position s eingefügt. Ist der Parameter 'Length=k' angegeben (optional), wird der vorgegebene Wert k-fach eingefügt.
Find ( Value As Array-Typ [ , Mode As Integer, Start As Integer ] )Gibt die Position zurück, an welcher das Such-Element zum ersten Mal im Array gefunden wird. Existiert der Such-String nicht im Array, wird als Funktionswert -1 zurück gegeben. Wird das optionale Argument 'Start=s' angegeben, so wird erst ab Index s gesucht. Das Argument 'Mode' bestimmt die Vergleichsmethode.
Insert ( Array As Array-Typ[] [ , Pos As Integer ] ) As Array-Typ[]Fügt die Elemente eines vorgegebenen Arrays in das Original-Array am Ende ein (Standard). Wird jedoch das optionale Argument 'Pos=p' angegeben, so wird das vorgegebene Array in das Original-Array erst ab Position p eingefügt.
Pop( )Entfernt das letzte Element eines Arrays und gibt dieses Element als Funktionswert zurück. Wenn das originale Array leer ist, wird ein Fehler ausgelöst.
Push ( Value As Array-Typ )Fügt ein Element am Ende eines Arrays ein.
Reverse( )Die Reihenfolge der Array-Elemente wird invertiert – die Array-Elemente E0..En werden umsortiert auf En..E0. Das invertierte Array wird als Funktionswert zurückgegeben.

7.4.0.5 Array-Klassen für native Datentypen

Gambas hat eine vordefinierte Array-Klasse für jeden nativen Datentyp → Kapitel 7.4.3.1. Der Name dieser Klassen ist der Name des Datentyps, dem eckige Klammern [] folgen.

Boolean[], Byte[], Short[], Integer[], Long[], Single[], Float[], Date[], String[], Object[], Pointer[] und Variant[]

Bitte beachten Sie die folgenden Hinweise, da nicht alle Arrays über alle u.a. Methoden verfügen:

  • Für alle (nativen) Arrays – außer Variant[ ] – gibt es die Methode Sort([Mode As Integer]).
  • Nur String[ ] hat die Methode Join( [ Separator As String, Escape As String ] ) .
  • Für die nativen Arrays Boolean[ ], Byte[ ], Short[ ], Integer[ ], Long[ ], Single[ ], Float[ ], Date[ ], Pointer[ ] existieren die beiden Methoden Read( Stream As Stream [ , Start As Integer, Length As Integer ] ) und Write( Stream As Stream [ , Start As Integer, Length As Integer ] ).
  • Die Methode ToString( [ Start As Integer, Length As Integer ] ) kennt nur Byte[ ].
  • Nur bei den Arrays Object[ ] können Sie die beiden Methoden FindByRef( Value As Object [ , Start As Integer ] ) und ExistByRef( Value As Object ) einsetzen.

Arrays können über diese Methoden in der folgenden Tabelle verfügen:

1x1MethodeBeschreibung
Sort ( [ Mode As Integer ] )Die Elemente im Array werden sortiert. Über Mode kann optional die Sortierreihenfolge festgelegt werden. → gb.Ascent (a..Z , Standard) und gb.Descent (z..A)
Join ( [ Separator As String, Escape As String ] ) As StringVerkettet die in den Arrays gespeicherten Zeichenketten. Separator ist eine Zeichenfolge, die zwischen je zwei Strings des Arrays eingefügt werden soll. Das Standard-Trennzeichen ist ein Komma. Escape wird zum Einschließen jeder Zeichenfolge verwendet. Besteht Escape aus zwei Zeichen, dann ist das erste das Start-Escape-Zeichen und das zweite das Ende-Escape-Zeichen. Einzelne Escape-Zeichen in den Strings werden dupliziert. Die Join-Funktion ist das Gegenteil der Split-Funktion.
Read ( Stream As Stream [ , Start As Integer, Length As Integer ] )Füllt ein Array, indem die Daten direkt aus einem Stream gelesen werden. Start gibt an, wo die Daten im Array gespeichert werden. Standardmäßig werden die Daten von Anfang an gespeichert. Length ist die Anzahl der Elemente, die aus der Datei gelesen werden. Standardmäßig werden alle Daten gelesen bis das Ende des Arrays erreicht ist.
Write ( Stream As Stream [ , Start As Integer, Length As Integer ] )Schreibt den Array-Inhalt in einen Stream. Start gibt die Position des ersten Elements im Array an, von dem geschrieben wird. Standardmäßig werden die Daten ab erstem Array-Element geschrieben. Length ist die Anzahl der Elemente, die in die Datei geschrieben werden. Standardmäßig werden die Daten geschrieben bis das Ende des Arrays erreicht ist.
ToString ( [ Start As Integer, Length As Integer ] ) As StringDer Funktionswert gibt den Array-Inhalt als String zurück. Start ist der Index des ersten zu extrahierenden Bytes. Standardmäßig ist Start gleich 0. Length ist die Anzahl der zu extrahieren Bytes. Standardmäßig wird alles bis zum Ende des Arrays extrahiert.
FindByRef ( Value As Object [ , Start As Integer ] ) As IntegerAls Funktionswert wird die Position des ersten Auftretens des spezifizierten Objekts im Array zurück gegeben. Ist Start angegeben, dann beginnt die Suche an der Start-Position. Standardmäßig wird das gesamte Array durchsucht. Wenn das spezifizierte Objekt nicht gefunden werden kann, dann wird -1 als Funktionswert zurückgegeben. Im Gegensatz zu Find() vergleicht die Funktion FindByRef(Value As Object [,Start As Integer]) die Objekte stets anhand ihrer Identität (d.h. ihrer Adresse im Speicher). Die spezielle _compare()-Methode wird nicht benutzt.
ExistByRef ( Value As Object ) As BooleanDie Funktion gibt True als Funktionswert zurück, wenn das spezifizierte Objekt im Array gespeichert ist. Im Gegensatz zu Exist() vergleicht die Funktion ExistByRef(Value As Object) die Objekte stets anhand ihrer Identität (d.h. ihrer Adresse im Speicher). Die spezielle _compare()-Methode wird nicht benutzt.

Tabelle 7.4.0.5.1 : Methoden 3 der Klasse Array

Download

The website uses a temporary session cookie. This technically necessary cookie is deleted when the browser is closed. You can find information on cookies in our privacy policy.
k7/k7.4/start.txt · Last modified: 02.07.2018 (external edit)

Page Tools