Arrays

Ein Array ist eine Datenstruktur, die eine Gruppe mit Werten enthält. Arrays sind praktisch, wenn Sie eine Liste mit Elementen haben, die einen ähnlichen Typ aufweisen. Beispiele sind Listen mit Vorwahlen, Telefonnummern oder Kundennamen.

Es gibt zwei Arten von Arrays, die Sie in Studio verwenden können:

String-Arrays: Dies sind Strings in einer Variablen, die durch einen Senkrechtstrich voneinander getrennt sind. Sie enthalten Stringwerte, die aus alphanumerischen Zeichen bestehen können.
Dynamische Arrays: Diese Arrays werden in dynamischen Datenobjekten gespeichert.

Ein dynamisches Datenobjekt eignet sich als Datenstruktur, wenn Ihre Liste Daten mit verschiedenen Arten von Informationen über ein einzelnes Element enthält. Auf der Hilfeseite Datenstrukturen werden Arrays und Objekte verglichen.

Wichtige Fakten über Arrays

Ein Array muss mindestens zwei Elemente enthalten. Ein Array, das nur ein Element enthält, scheint eine reguläre Variable zu sein. Es handelt sich dennoch um ein Array und kann auch wie ein Array aufgerufen werden. Dasselbe gilt für dynamische Arrays.
In Studio beginnen Array-Indizes mit 1.
In Arrays können einige Funktionen verwendet werden, wie index() und indexof().
Mit String-Arrays können Sie ein beliebiges Trennzeichen verwenden. Damit ein String-Array nativ gelesen werden kann, muss jedoch ein Senkrechtstrich als Trennzeichen verwendet werden.

Testen

Laden Sie das Skript mit Array-Beispielen herunter und importieren Sie es in Studio. Viele der auf dieser Hilfeseite genannten Beispiele sind in Snippet-Aktionen im Beispielskript enthalten. Sie können das Snippet-Editor-Fenster öffnen und den Debugger ausführen, um das Beispiel zu sehen.

Zusammenfassung der Array-Syntax

Erstellen Sie ein String-Array mit einer der beiden folgenden Syntaxen.

Weisen Sie jedem Element über seinen Index einen Wert zu:

ASSIGN <var>[<index1>] = "<value1>"

ASSIGN <var>[<index2>] = "<value2>"

ASSIGN <var>[<index3>] = "<value3>"

Weisen Sie alle Elementwerte einer Variablen zu und verwenden Sie dabei einen String mit einem Senkrechtstrich als Trennzeichen:

ASSIGN <var> = "<value1> | <value2> | <value3>"

Erstellen Sie ein dynamisches Array mit der folgenden Syntax:

DYNAMIC <object>

ASSIGN <object>.<member>[<index>].<sub-member>= "value"

Weitere Formen dynamischer Arrays werden unterstützt.

Verwenden Sie diese Syntax, um auf ein bestimmtes Element in einem String-Array zu verweisen:

<var>[index]

Verwenden Sie diese Syntax, um auf ein bestimmtes Element in einem dynamischen Array zu verweisen:

ASSIGN <var> = <object>.<member>[<index>].<arrayElement>

Elemente und Indizes

Die in einem Array enthaltenen Werte werden als Elemente bezeichnet. Das Skript behält den Überblick über die Reihenfolge der Elemente im Array. Jedes Element im Array hat eine numerische Kennung, die als Indexnummer bezeichnet wird. Der Index wird jedem Element automatisch auf Grundlage seiner Position im Array zugewiesen. Wenn Sie Elemente neu anordnen, hinzufügen oder entfernen, können sich die jeweiligen Indizes ändern.

In Studio beginnen Array-Indizes mit 1. Indizes müssen positive Ganzzahlen sein. Sie müssen den Index kennen, damit Sie mit einem bestimmten Element im Array interagieren können. Wenn Sie den Index eines Elements nicht kennen, können Sie ihn mithilfe der indexof()-Funktion ermitteln.

Verweisen auf einzelne Elemente in einem String-Array

Verwenden Sie diese Syntax, um auf ein einzelnes Element in einem String-Array zu verweisen: <ArrayElement>[<Index>]. Sie können diese Syntax auf einer der beiden Seiten des Gleichheitszeichens verwenden. Sie können damit beispielsweise einem Element einen Wert zuweisen oder auf den Wert eines Elements verweisen. Dies wäre beispielsweise der Fall, wenn Sie den Wert einer anderen Variablen zuweisen.

Beispiel:

ASSIGN heroes[1] = "Beowulf"
ASSIGN heroes[2] = "Sir Gawain" 
ASSIGN heroes[3] = "Byrhtnoth"

In diesem Beispiel hat Beowulf den Index 1, Sir Gawain 2 und Byrtnoth 3. Im Array-Format mit Senkrechtstrichen als Trennzeichen haben diese Elemente dieselben Indizes: name = "Beowulf|Sir Gawain|Byrhtnoth". Um die Indizes für ein Array in diesem Format zu ermitteln, zählen Sie die Elemente von links nach rechts, beginnend mit 1.

Indizes werden in numerischer Reihenfolge ausgefüllt

Indizes werden nacheinander in numerischer Reihenfolge ausgefüllt. Wenn Sie auf einen Index verweisen, der zurzeit nicht im Array vorhanden ist, erstellt das Skript den Index. Er ist so lange leer, bis Sie ihm einen Wert zuweisen. Das Skript erstellt alle nicht vorhandenen Indizes zwischen dem Index, auf den Sie verweisen, und dem bisher letzten Element im Array. Die Elemente, die das Skript zum Ausfüllen der Indizes hinzufügt, sind leer. Beispiel:

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth" 
ASSIGN heroes[6] = "Lancelot"

Das resultierende Array ist heroes = "Beowulf|Sir Gawain|Byrhtnoth|||Lancelot". Das Skript hat Elemente für die Indizes 4 und 5 hinzugefügt, aber da ihnen kein Wert zugewiesen wurde, sind sie leer.

Wenn Sie versuchen, einen Wert aus einem nicht vorhandenen Element abzurufen, wird das Element ebenfalls erstellt. Außerdem werden alle weiteren Elemente zwischen dem Element, auf das Sie verwiesen haben, und dem bisher letzten Element erstellt. Auch diese Elemente sind leer.

Wenn auf ein leeres Array-Element in einem Kontext verwiesen wird, in dem eine Zahl erwartet wird, verhält sich das Skript so, als wäre der Wert null.

Bestimmen des nächsten nicht verwendeten Index

Sie können die Erstellung von überflüssigen leeren Elementen in einem Array vermeiden, indem Sie den nächsten nicht verwendeten Index ermitteln. Sie müssen die Elemente im Array zählen und dann dem entsprechenden Wert 1 hinzufügen. So erhalten Sie die nächste offene Indexnummer.

Verwenden Sie dazu die size()-Funktion. Beispiel:

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"  
ASSIGN nextIndex = heroes.size() + 1
ASSIGN heroes[nextIndex] = Roland

In diesem Beispiel gibt heroes.size() die Anzahl der Elemente im Array der Namen zurück. Der Wert von totalNames ist 3. Indem Sie 1 hinzufügen und die nextIndex-Variable anstelle der Indexnummer verwenden, können Sie dem Array ein Element hinzufügen.

Sie können auch die count()-Funktion verwenden.

String-Arrays

String-Arrays können auf zwei Arten definiert werden. Bei der ersten Methode wird jedes einzelne Element explizit genannt. Das folgende Beispiel zeigt ein String-Array mit Textwerten, die Element für Element definiert werden.

ASSIGN heroes[1] = "Beowulf"
ASSIGN heroes[2] = "Sir Gawain" 
ASSIGN heroes[3] = "Byrhtnoth"

Die Zahl in eckigen Klammern nach dem Array-Namen ist die Indexnummer des Elements. Dies ist die Kennung für jedes Element.

Bei der zweiten Methode zum Definieren eines String-Arrays wird ein einzelner Senkrechtstrich (|) zwischen jedem Element im String verwendet. Dieses Beispiel zeigt das Array aus dem ersten Beispiel als String mit Senkrechtstrich als Trennzeichen. Wenn Sie ein String-Array mit Senkrechtstrich als Trennzeichen erstellen, müssen die Werte auf der rechten Seite der Anweisung in doppelte Anführungszeichen eingeschlossen werden.

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"

Die Funktionen sind austauschbar, da kein Unterschied zwischen ihnen besteht. Beide Methoden zum Definieren des String-Arrays führen zum selben Ergebnis: eine Variable, die ein Array mit Elementen enthält.

Das Schlüsselwort ASSIGN muss beim Deklarieren eines String-Arrays nicht zwingend verwendet werden. Die Verwendung ist jedoch hilfreich. Wenn Sie ASSIGN angeben, kann die Stelle in Ihrem Skript, an der Sie das Array eingefügt haben, mithilfe der erweiterten Suche einfach gefunden werden. Wenn ASSIGN nicht vorhanden ist, müssen Sie nach dem Namen des Arrays suchen. Die Suchergebnisse enthalten jeden Verweis auf die Array in Ihrem Skript. Wenn Sie ASSIGN in Ihren Suchbegriff einschließen, gibt die Suche nur die Ergebnisse zurück, bei denen die Variable explizit zugewiesen ist. Um eine Variable ohne ASSIGN zu deklarieren, verwenden Sie diese Syntax: <name> = "<value>"

Dynamische Arrays

Dynamische Arrays können verschiedene Formen haben:

Das dynamische Datenobjekt enthält ein Array. Jedes Array-Element ist auch ein Objektmitglied.

DYNAMIC beowulfLocations 
ASSIGN beowulfLocations[1] = "Land of the Geats"
ASSIGN beowulfLocations[2] = "Heorot" 
ASSIGN beowulfLocations[3] = "Earnanæs"

Das dynamische Objekt beinhaltet ein Mitglied, das ein Array enthält. Die anderen Mitglieder des Objekts können String- oder numerische Werte enthalten oder es kann sich um andere Arrays handeln.

DYNAMIC beowulfCharacteristics 
ASSIGN beowulfCharacteristics.foe[1].characteristics[1] = "Grendel"
ASSIGN beowulfCharacteristics.foe[1].characteristics[2] = "son of Cain"
ASSIGN beowulfCharacteristics.foe[2] = $"Grendel\'s mother" 
ASSIGN beowulfCharacteristics.foe[3] = "Dragon"

Ein String-Array beinhaltet Elemente, die jeweils ein dynamisches Datenobjekt enthalten.
```
DYNAMIC epicPoems
ASSIGN epicPoems.poemName = "Beowulf"
DYNAMIC heroes 
ASSIGN heroes.heroName = "Beowulf"
DYNAMIC monsters
ASSIGN monsters.monsterName = "Grendel"
ASSIGN oldEnglish[1] = epicPoems
ASSIGN oldEnglish[2] = heroes
ASSIGN oldEnglish[3] = monsters
```
Wenn Sie den Debugger ausführen, können Sie den Inhalt der dynamischen Objekte und des String-Arrays auf der Registerkarte "Variablen als Struktur" im Snippet-Editor-Fenster anzeigen.

Diese Art von dynamischem Array kann nicht verwendet werden, wenn Ihr Skript mit anderen Systemen interagieren muss, beispielsweise wenn Sie eine Verbindung mit APIs herstellen. Die im String-Array enthaltenen Daten können nicht serialisiert oder in JSON- oder XML-Strings konvertiert werden.

Verweisen auf ein Array-Element nach Position

Sie können ein Element in einem String oder einem dynamischen Array anhand seiner Position im Array referenzieren, die durch seinen Index angegeben wird. Beispiel:

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"
ASSIGN currentName = heroes[2]

Der Wert von currentName ist Sir Gawain.

Sie können auf einer der beiden Seiten des Gleichheitszeichens in einer ASSIGN-Anweisung eine Variable anstelle der Indexnummer verwenden. So können Sie bestimmte Indizes referenzieren, ohne den Index im Skript fest zu kodieren. Beispiel:

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"
ASSIGN location = 2
ASSIGN currentHero = heroes[location]
ASSIGN nextIndex = heroes.count() + 1
ASSIGN heroes[nextIndex] = "Roland"

De Wert von currentHero in diesem Beispiel lautet Sir Gawain. Die letzten beiden Zeilen im obigen Beispiel zeigen, wie auf der linken Seite der ASSIGN-Anweisung eine Variable als Index verwendet wird. Außerdem wird gezeigt, wie mithilfe der count()-Funktion die Anzahl der Elemente im Array zurückgegeben wird. Anhand dieser Informationen wird am nächsten leeren Index ein neues Element hinzugefügt.

Wenn Sie eine Variable für die Indexnummer verwenden, müssen Sie den Variablennamen nicht in geschweifte Klammern einschließen. Das Skript erwartet einen numerischen Wert zwischen den eckigen Klammern im Array-Namen. Es geht davon aus, dass jeder nicht numerische Wert eine Variable ist, und sucht daher nach einer Variablen mit diesem Namen. An der Stelle, an der Sie einen numerischen Wert zuweisen, muss eine entsprechende Variablendeklaration vorhanden sein. Andernfalls tritt der folgende Fehler auf:

_ERR=In Snippet-Zeile 12: Array-Index muss >= 1 sein.

Wenn die Error-Verzweigung für die Snippet -Aktion verbunden ist, folgt das Skript dieser Verzweigung, sofern dieser Fehler auftritt.

Verwenden von FOREACH mit einem String-Array

Sie können eine FOREACH-Anweisung mit String-Arrays verwenden, um jedes Element zu durchlaufen.

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth|Lancelot"
 FOREACH elem IN heroes 
{
   ASSIGN aName = elem 
}

In diesem Beispiel werden elem und aName mit jeder Iteration aktualisiert. Die elem-Variable enthält das aktuelle Element, das von der FOREACH-Schleife verarbeitet wird. Das Skript aktualisiert aName mit dem Inhalt von elem. Am Ende einer jeden Iteration enthalten elem und aName denselben Wert, aber in der Mitte der Iteration enthält elem den neuen Wert und aName den alten Wert (oder beim Start der ersten Iteration keinen Wert).

Dies ist im Snippet FOREACH Loop with a String Array im Array-Beispielskript gut ersichtlich. Sie können sehen, wie die Variablen aktualisiert werden, indem Sie das Snippet Zeile für Zeile durchlaufen.

Verwenden von FOR mit einem String-Array

Sie können eine FOR-Schleife mit einem String-Array verwenden, um das Array zu durchlaufen und eine definierte Aktion so oft wie festgelegt auszuführen.

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth|Lancelot"
FOR i = 1 TO heroes.count 
   {    
      item = "{heroes[i]}" 
   }

Dieses Beispiel hat folgendes Ergebnis: Item wird bei jeder Iteration der FOR-Schleife mit dem Inhalt des heroes-Arrays an der Indexposition aktualisiert, die vom Wert für i angegeben ist. Die Iteration der FOR-Schleife wird beendet, nachdem das Ende des String-Arrays erreicht wurde, wie von heroes.count angegeben.

Sie können diese Schleife im Snippet FOR Loop with a String Array im Array-Beispielskript sehen.

Verwenden von Funktionen mit Arrays

Sie können Funktionen mit Arrays verwenden. Verwenden Sie den Namen des Arrays mit dem Index in eckigen Klammern und fügen Sie dann den Namen der Funktion in der Punkt-Schreibweise hinzu. Dies wird im folgenden Beispiel gezeigt:


ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"
ASSIGN miniHero = "{heroes[2].lower}"
ASSIGN yellyHero = "{heroes[2].upper}"

Die Ergebnisse dieses Beispiels sind miniHero = sir gawain und yellyHero = SIR GAWAIN.

Nicht alle Funktionen können mit allen Arrays verwendet werden. Einige funktionieren nur mit bestimmten Arten von Werten. Stellen Sie sicher, dass die Funktion, die Sie verwenden möchten, für die jeweiligen Arten geeignet ist.

Sie können Funktionen mit dynamischen Arrays verwenden. Je nach dem dynamischen Array und seinem Inhalt müssen Sie jedoch möglicherweise eine besondere Objekteigenschaft verwenden:$value. Einige Funktionen können nicht für ein ganzes Objekt verwendet werden. Beispielsweise kann die lower()-Funktion nicht für ein Array mit Objekten genutzt werden. Wenn Sie dies versuchen, ignoriert das Skript die Funktion. In solchen Fällen müssen Sie eine Alternativlösung verwenden. Zum Beispiel können Sie bestimmte Werte aus den Objekten im Array in eine separate Variable kopieren. Anschließend können Sie lower() für den Inhalt der Variablen verwenden und den konvertierten Wert bei Bedarf zurück in das Objekt kopieren.

Die Funktionen in der folgenden Tabelle sind speziell für Arrays vorgesehen. Sie können diese Funktionen im Snippet Functions and Arrays im Array-Beispielskript testen.

Funktion	Beschreibung
count()	Gibt die Anzahl der Elemente in einem Array oder einem Objekt zurück.
index(indexValue)	Gibt das Array-Element vom Inhalt der Variablen gemäß der Angabe für indexValue zurück.
indexof(text)	Gibt die Zeichenposition für den angegebenen text im Inhalt einer Variablen zurück.
size()	Gibt die Anzahl der Elemente in einem Array zurück.
split(delimiter)	Konvertiert den Inhalt einer Variablen in einen String, der durch den Senkrechtstrich getrennt ist und als Array verarbeitet werden kann. Ersetzt das vorhandene delimiter-Trennzeichen durch einen Senkrechtstrich.