Arrays

De informatie op deze helppagina is zowel van toepassing op CXone Studio als op Desktop Studio.

Een array is een datastructuur die een groep van waarden bevat. Arrays zijn nuttig wanneer u een lijst van items hebt die van hetzelfde type zijn. Bijvoorbeeld, de lijst van netnummers, telefoonnummers of klantnamen.

Er zijn twee soorten arrays die u kunt gebruiken in Studio:

Stringmatrix: door verticale strepen gescheiden tekenreeks in een variabele. Ze bevatten stringwaarden die kunnen bestaan uit alfanumerieke tekens.
Dynamische arrays: arrays die zijn opgeslagen in dynamische gegevensobjecten.

Als u een lijst hebt waar de gegevens alle types informatie bevatten over één entiteit, zijn dynamische gegevensobjecten een meer geschikte gegevensstructuur om te gebruiken. Een vergelijking van arrays en objecten is beschikbaar op de helppagina Gegevensstructuren.

Belangrijke feiten over arrays

Een array moet minstens twee elementen hebben. Een array met slechts één element lijkt een gewone variabele te zijn. Het is nog steeds een array en u kunt die oproepen als een array. Hetzelfde geldt voor dynamische arrays.
In Studio starten de matrixindexen op 1.
Sommige functies zijn beschikbaar voor gebruik met arrays, zoals index() en indexof().
U kunt elk scheidingsteken met stringmatrices gebruiken. Om dit echter origineel te kunnen lezen, moet een stringmatrix een verticale streep gebruiken als scheidingsteken.

Probeer het

Download het Arrayvoorbeeldenscript en importeer dit in Studio. Heel wat voorbeelden van deze helppagina zijn beschikbaar in Snippet actie in het voorbeeldscript. U kunt het Fragmenteditorvenster openen en de debugger uit te voeren om het voorbeeld te zien.

Array syntaxis overzicht

Configureer een stringmatrix met een van de volgende syntaxis.

Wijs een waarde toe aan elke element aan de hand van de index:

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

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

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

Wijs alle elementwaarden toe aan een variabele in een door verticale strepen gescheiden tekenreeks:

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

Maak een dynamische array met de volgende syntaxis:

DYNAMIC <object>

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

Extra formulieren van dynamische arrays worden ondersteund.

Om te verwijzen naar een specifiek element in een stringmatrix, gebruikt u deze syntax:

<var>[index]

Om te verwijzen naar een specifiek element in een dynamische matrix, gebruikt u deze syntax:

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

Elementen en indexen

De waarden die aan matrix bevat, worden elementen genoemd. Het script houdt de volgorde van de elementen bij in de matrix. Elk element in een matrix heeft een numerieke id, een indexnummer genoemd. De index wordt automatisch toegewezen aan elk element op basis van zijn positie in de matrix. Als u elementen opnieuw schikt, toevoegt of verwijdert, kunnen hun indexen wijzigen.

In Studio starten de matrixindexen op 1. Indexen moeten positieve gehele getallen zijn. U moet de index kennen om interactief te werken met een specifiek element in de matrix. U kunt de indexof() functie gebruiken om de index van een element te bepalen als u deze niet kent.

Raadpleeg Individueel element van Stringmatrix

Wanneer wordt verwezen naar een individueel element in een stringmatrix, gebruikt u deze syntax: <arrayElement>[<index>]. U kunt deze syntaxis aan elke zijde van het gelijkheidsteken gebruiken. U kunt dit bijvoorbeeld gebruiken om een waarde toe te wijzen aan een element of om te verwijzen naar de waarde van een element, zoals wanneer de waarde wordt toegewezen aan een andere variabele.

Bijvoorbeeld:

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

In dit voorbeeld is de index van Beowulf 1, deze van Sir Gawain 2 en deze van Byrtnoth 3. Deze elementen hebben dezelfde indexen wanneer u kijkt naar de matrix in een door een verticale streep gescheiden formaat: name = "Beowulf|Sir Gawain|Byrhtnoth". Om de indexen van een matrix te bepalen in dit formaat, telt u de elementen van links naar rechts, te beginnen met 1.

Indexen zijn ingevuld in numerieke volgorde

Indexen zijn één voor één ingevuld in numerieke volgorde. Als u verwijst naar een index die momenteel niet bestaat in de matrix, maakt u het script dit en zal het leeg zijn tenzij u een waarde eraan toewijst. Het script maakt alle indexen die niet bestaan tussen deze waarnaar u verwijst en het vorige laatste element in de matrix. De elementen die het script toevoegt om indexen die leeg zijn, in te vullen. Bijvoorbeeld:

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

De resulterende matrix is heroes = "Beowulf|Sir Gawain|Byrhtnoth|||Lancelot". Het script heeft elementen toegevoegd voor indexen 4 en 5, maar omdat er geen waarde werd toegewezen eraan, zijn ze leeg.

Als u op dezelfde manier probeert een waarde te halen uit een element dat niet bestaat, wordt dat element gemaakt.. Alle elementen tussen deze waarnaar u probeert te verwijderen en het vorige laatste element, worden ook gemaakt en zullen leeg zijn.

Als naar een leeg matrixelement wordt verwezen in een context waarin een getal wordt verwacht, gedraagt het script zich alsof de waarde ervan nul is.

De volgende ongebruikte index bepalen

Om het maken van onnodige lege elementen in een matrix te voorkomen, kunt u de volgende ongebruikte index bepalen. U moet de elementen in de matrix tellen en vervolgens 1 toevoegen aan dat aantal. Dit geeft u het volgende open indexnummer.

Gebruik hiervoor de size() functie. Bijvoorbeeld:

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

In dit voorbeeld, retourneert heroes.size() het aantal elementen in de naammatrix. De waarde van totalNames is 3. Door één eraan toe te voegen en de nextIndex-variabele te gebruiken in plaats van het indexnummer, kunt u een element toevoegen aan de matrix.

U kunt ook de count()-functie gebruiken.

Stringmatrices

Stringmatrices kunnen op twee manieren worden gedefinieerd. De eerste is om elk element expliciet individueel een naam te geven. Het volgende voorbeeld toont een stringmatrix die de tekstwaarden bevat die per individueel element worden gedefinieerd.

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

Het cijfer tussen vierkante haken na de matrixnaam is het indexnummer van het element. Dit is de identificatiecode voor elk element.

De tweede manier is het definiëren van een stringmatrix met een door recht strepen gescheiden tekenreeks met een teken van één rechte streep (|) tussen elk element. Dit voorbeeld toont de matrix van het eerste voorbeeld, gedefinieerd als een door verticale strepen gescheiden tekenreeks. Wanneer u een door verticale strepen gescheiden stringmatrix maakt, moeten de waarden aan de rechterzijde van de verklaring tussen dubbele aanhalingstekens worden ingesloten.

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"

Er is geen verschil tussen de functies en u kunt ze afwisselende gebruiken. Beide methoden voor het definiëren van de stringmatrix leveren hetzelfde resultaat op, een variabele die een matrix van elementen bevat.

Het gebruik van het trefwoord ASSIGN is niet nodig wanneer u een -stringmatrix declareert. Het is echter wel handig om te gebruiken. Door ASSIGN op te nemen in het script kan de plaats waar u de -matrix introduceert, eenvoudig worden gelokaliseerd met Uitgebreid zoeken. Zonder ASSIGN moet u de naam van de -matrix opzoeken. De zoekresultaten bevatten iedere referentie naar de matrix in uw script. Wanneer u ASSIGN opneemt in uw zoekterm, retourneert de zoekactie alleen de resultaten waar de variabele expliciet is toegewezen. Als u een variabele declareert zonder ASSIGN, gebruikt u deze syntax: <name> = "<value>"

Dynamische matrices

Dynamische matrices kunnen verschillende vormen aannemen:

Het dynamische gegevensobject bevat een matrix. Elk matrixelement is ook een objectlid.

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

Het dynamische object bevat een lid die een matrix bevat. De andere leden van het object kunnen strings of numerieke waarden bevatten, of ze kunnen andere matrices bevatten.

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"

Een stringmatrix bevat elementen die elk een dynamische gegevensobject bevatten.
```
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
```
U kunt de inhoud van de dynamische objecten en de stringmatrix weergeven op het tabblad Variabelen als Boomstructuur in het venster Fragment-editor wanneer u de debugger uitvoert.

Dit type dynamische matrix kan niet worden gebruikt wanneer uw script moet werken met andere systemen, zoals wanneer u verbinding maakt met API's. De gegevens die de stringmatrix bevat, kunnen niet worden geserialiseerd of geconverteerd naar JSON- or XML-strings.

Raadpleeg een matrixelement op Locatie

u kunt verwijzen naar een element in een tekenreeks of een dynamische matrix met zijn locatie in de matrix, opgegeven volgens zijn index. Bijvoorbeeld:

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

De waarde van currentName is Sir Gawain.

U kunt een variabele in plaats van het indexnummer gebruiken aan elke zijde van het gelijkheidsteken in een ASSIGN-verklaring. Hiermee kunt u verwijzen naar specifieke indices zonder hardcodering van de index in het script. Bijvoorbeeld:

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

De waarde van currentHero in dit voorbeeld is Sir Gawain. De laatste twee lijnen van het bovenstaande voorbeeld die een variabele gebruikt als de index aan de linkerzijde van de ASSIGN-verklaring. Dit toont ook het gebruik van de count()-functie om het aantal elementen in de matrix te retourneren. Deze informatie wordt gebruikt voor het toevoegen van een nieuw element in de volgende lege index.

Wanneer u een variabele voor het indexnummer gebruikt, moet u geen ronde haakjes rond de naam van de variabele gebruiken. Het script verwacht een numerieke waarde tussen de vierkante haken in de matrixnaam. Dit veronderstelt dat alles dat geen nummer is, een variabele is. Het zoekt dus een variabele op die naam. Er moet een overeenkomende variabele verklaring zijn waar u een numerieke waarde toewijst. Als er geen is, resulteert dit in de volgende fout:

_ERR=In Snippet line 12: Array-index moet >= 1 zijn.

Als de Error vertakking voor de Snippet actie is verbonden, neemt het script deze wanneer deze fout optreedt.

Gebruik FOREACH met een stringmatrix

U kunt een FOREACH verklaring gebruiken met stringmatrices om te herhalen via elk element.

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

In dit voorbeeld worden elem en aName bijgewerkt met elke herhaling. De elem variabele bevat het huidige element dat de FOREACH loop verwerkt. Het script werkt aName bij met de inhoud van elem. Aan het einde van elke herhaling, houden elem en aName dezelfde waarde, maar in het midden van de herhaling, houdt elem de nieuwe waarde en aName de oude waarde (of geen waarde, in het geval van de start van de eerste iteratie).

U kunt dit duidelijk zien in het FOREACH Loop with a String Array fragment in het Script Matrixvoorbeelden. Om de manier te zien waarop de variabelen worden bijgewerkt, doorloopt u het fragment per lijn.

Gebruik FOR met een stringmatrix

U kunt een FOR loop met een stringmatrix gebruiken voor herhalen via de matrix en een ingesteld aantal keer een gedefinieerde actie uitvoeren.

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

Het resultaat van dit voorbeeld is, dat Item wordt bijgewerkt bij elke herhaling van de FOR loop met de inhoud van de heroes-matrix van de indexlocatie, opgegeven door de waarde van i. De FOR loop stopt met herhalen nadat deze het einde van de stringmatrix bereikt, zoals aangegeven door heroes.count.

U kunt deze loop zien in het FOR Loop with a String Array-fragment in het Script Matrixvoorbeelden.

Functies met matrices gebruiken

U kunt functies gebruiken met matrices. Gebruik de naam van de matrix met de index tussen vierkante haken. Voeg dan de functienaam toe met de puntnotatie. Dit wordt getoond in het volgende voorbeeld:


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

De resultaten van dit voorbeeld zijn miniHero = sir gawain en yellyHero = SIR GAWAIN.

Niet alle functies werken met alle matrices. Sommige werken alleen met bepaalde types waarden. Controleer de types waarmee de functie die u wilt gebruiken, werkt.

U kunt functies gebruiken met dynamische matrices. Afhankelijk van de specifieke dynamische matrix en wat deze bevat, moet u echter mogelijk een speciale objecteigenschap.gebruiken.$value. Sommige functies zullen niet werken op een volledig object. U kunt de functie lower() bijvoorbeeld niet gebruiken op een matrix van objecten. Het script zal de functie negeren als u dit hebt geprobeerd. In deze gevallen moet u workarounds toepassen. U kunt bijvoorbeeld specifieke waarden kopiëren van de objecten in de matrix naar een afzonderlijke variabele. U kunt lower() vervolgens gebruiken op de inhoud van de variabele, en indien nodig, de geconverteerde waarde vervolgens terug te converteren in het object.

De functies in de volgende tabel zijn specifiek ontworpen om te werken met matrices. U test deze functies in het Functions and Arrays-fragment in het Script Matrixvoorbeelden.

Functie	Beschrijving
count()	Retourneert het aantal elementen in een array of object.
index(indexValue)	Retourneert het matrixelement van de inhoud van de variabele volgens de opgegeven indexValue.
indexof(text)	Retourneert de tekenpositie van de opgegeven text binnen de inhoud van een variabele.
size()	Retourneert het aantal elementen binnen een array.
split(delimiter)	Converteert de inhoud van de variabele naar een door verticale strepen gescheiden string die kan worden behandeld als een array. Vervangt het bestaande opgegeven delimiter door een verticale streep.