ScriptForge.Dictionary-service

Inhoud

# ScriptForge.Dictionary dienst

Een woordenboek is een verzameling sleutel-itemparen

- De sleutel is een tekenreeks. In Basic-scripts wordt de hoofdlettergevoeligheid van de sleutel bepaald bij het aanmaken van het woordenboek. In Python-scripts is de sleutel altijd hoofdlettergevoelig.

- Items kunnen van elk type zijn

Sleutels en items kunnen worden opgehaald, geteld, bijgewerkt en nog veel meer.

De Dictionary-service is vergelijkbaar met het ingebouwde LibreOffice Basic Collection-object, maar met meer functionaliteit. Collection-objecten ondersteunen bijvoorbeeld niet het ophalen van sleutels. Bovendien bieden Dictionaries extra mogelijkheden, zoals het vervangen van sleutels, het controleren of een specifieke sleutel al bestaat en het converteren van de Dictionary naar een matrix van PropertyValues of een JSON-string.

## Service aanroep

##### In BASIC

In het volgende voorbeeld wordt myDict gemaakt als een leeg woordenboek.

        GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
        Dim myDict As Variant
        myDict = CreateScriptService("Dictionary", True)
                    De sleutels zijn hoofdlettergevoelig, daarom is het tweede argument True.

Het wordt aanbevolen om na gebruik middelen vrij te maken:

         Set myDict = myDict.Dispose()

##### In Python

Het onderstaande voorbeeld maakt een lege instantie van de service Dictionary en gebruikt de Python-native update-methode om deze te vullen met de inhoud van een Python dict-object .

        dico = dict('A' = 1, 'B' = 2, 'C' = 3)
        # Initialiseer myDict als een leeg Dictionary-object
        myDict = CreateScriptService('Dictionary')
        # Laad de waardes van dico in myDict
        myDict.update(dico)
        myDict['D'] = 4
        print(myDict)   # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
        propval = myDict.ConvertToPropertyValues()

Het is mogelijk om een instantie van de service Dictionary te maken met een Python dict-object als argument, zoals in het volgende voorbeeld wordt getoond.

        dico = dict('A' = 1, 'B' = 2, 'C' = 3)
        # Initialiseer myDict met de inhoud van dico
        myDict = CreateScriptService('Dictionary', dico)
        myDict['D'] = 4
        print(myDict) # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
        propval = myDict.ConvertToPropertyValues()

Omdat Python ingebouwde ondersteuning voor dictionaries heeft, zijn de meeste methoden in de Dictionary-service alleen beschikbaar voor Basic-scripts. Uitzonderingen hierop zijn de methoden ConvertToPropertyValues en ImportFromPropertyValues, die zowel in Basic als in Python worden ondersteund.

## Eigenschappen

Naam | Alleen-lezen | Type | Beschrijving
--- | --- | --- | ---
Count | Ja | Long | Het aantal vermeldingen in het woordenboek
Items | Ja | Matrix van varianten | De lijst met items als een eendimensionale matrix
Keys | Ja | Matrix van tekenreeksen | De lijst met sleutels als een eendimensionale matrix

De eigenschappen Keys en Items geven hun respectievelijke inhoud terug, met een identieke volgorde. De volgorde is niet gerelateerd aan de volgorde van het maken.

### Voorbeeld:

In het volgende voorbeeld wordt de eigenschap Keys gebruikt om alle sleutels in het woordenboek myDict te herhalen.

        Dim a As Variant, b As String
        a = myDict.Keys
        For Each b In a
            MsgBox(myDict.Item(b))
        Next b

Lijst met methodes in de woordenboekservice
Add ConvertToArray ConvertToJson ConvertToPropertyValues | Exists ImportFromJson ImportFromPropertyValues Item | Remove RemoveAll ReplaceItem ReplaceKey

## Add

Voegt een nieuw sleutel-itempaar toe aan het woordenboek. Retourneert True indien succesvol.

### Syntaxis:

dict.Add(key: str, item: any): bool

### Parameters:

key: Tekstwaarde die wordt gebruikt om het item te identificeren. De hoofdlettergevoeligheid van de sleutel is bepaald tijdens het aanmaken van het woordenboek.

item: Elke waarde, inclusief een matrix, een basisobject, een UNO-object, een woordenboek, enz..

### Voorbeeld:

          Dim NewValue As Variant
          myDict.Add("NewKey", NewValue)

Elke sleutel moet uniek zijn in hetzelfde woordenboek. Als de sleutel al in het woordenboek bestaat, wordt een DUPLICATEKEYERROR weergegeven. Sleutels die zijn gemaakt van spatietekens zullen een INVALIDKEYERROR-fout veroorzaken.

## ConvertToArray

Slaat de inhoud van het woordenboek op in een op nul gebaseerde matrix met twee kolommen. De sleutels worden opgeslagen in de eerste kolom en de items worden opgeslagen in de tweede kolom.

Als het woordenboek leeg is, retourneert deze methode een lege Matrix.

### Syntaxis:

dict.ConvertToArray(): any[0..*, 0..1]

### Voorbeeld:

          Dim myDict as Variant
          myDict = CreateScriptService("Dictionary")
          myDict.Add("a", 1)
          myDict.Add("b", 2)
          myDict.Add("c", 3)
          Dim arr as Variant
          arr = myDict.ConvertToArray()
          '(("a", 1), ("b", 2), ("c", 3))

## ConvertToJson

Converteert de inhoud van een woordenboek naar JSON (JavaScript Object Notation)-tekst.

### Beperkingen

Deze methode ondersteunt de volgende gegevenstypes: Tekenreeks, Booleaans, getallen, Null en Leeg. Matrixen met items van dit type zijn ook toegestaan, ongeacht hun afmetingen. Datums worden omgezet in tekenreeksen, maar ze kunnen niet binnen matrixen worden gebruikt. Andere gegevenstypes worden geconverteerd naar hun tekenreeksweergave met behulp van de service SF_String.Represent.

### Syntaxis:

dict.ConvertToJson(indent: str = ""): str

### Parameters:

indent: indien indent een positief getal of een tekst is, worden JSON-matrix-elementen en objectleden mooi afgedrukt met dat inspringingsniveau. Een negatieve indent-waarde voegt nieuwe regels toe zonder inspringing. De standaardwaarde is een lege tekenreeks "" die de meest compacte weergave selecteert. Het gebruik van een positief geheel getal voor indent laat zoveel spaties per niveau inspringen. Als indent een tekenreeks is, zoals Chr(9) of Tab(1), wordt het Tab-teken gebruikt om elk niveau te laten inspringen.

### Voorbeeld:

          myDict.Add("p0", 12.5)
          myDict.Add("p1", "a string àé""ê")
          myDict.Add("p2", DateSerial(2020,9,28))
          myDict.Add("p3", True)
          myDict.Add("p4", Array(1,2,3))
          MsgBox myDict.ConvertToJson()
          '{"p0": 12.5, "p1": "a string \u00e0\u00e9\"\u00ea", "p2": "2020-09-28", "p3": true, "p4": [1, 2, 3]}

## ConvertToPropertyValues

Slaat de inhoud van het woordenboek op in een matrix van PropertyValues.

Elk item in de matrix is een com.sun.star.beans.PropertyValue. De sleutel wordt opgeslagen in Name, het item wordt opgeslagen in Value.

Als één van de items het type Date heeft, wordt het geconverteerd naar een com.sun.star.util.DateTime-structuur. Als één van de items een lege matrix is, wordt deze geconverteerd naar Null. De resulterende matrix is leeg als het woordenboek leeg is.

### Syntaxis:

dict.ConvertToPropertyValues(): obj[0..*]

### Voorbeeld:

##### In BASIC

        Dim myDict as Variant
        myDict = CreateScriptService("Dictionary")
        'Voegt enkele eigenschappen toe aan het woordenboek
        myDict.Add("Color", "Blue")
        myDict.Add("Width", 20)
        'Converteert naar een matrix van PropertyValue-objecten'
        Dim prop as Variant
        prop = myDict.ConvertToPropertyValues()

##### In Python

Merk op dat in het onderstaande voorbeeld een Python-woordenboek moet worden doorgegeven als het tweede argument van de CreateScriptService-methode.

        myDict = dict()
        myDict["Color"] = "Blue"
        myDict["Width"] = 30
        sfDic = CreateScriptService("Dictionary", myDict)
        prop = sfDic.ConvertToPropertyValues()

Veel services en methodes in de UNO-bibliotheek gebruiken parameters die worden weergegeven met behulp van de PropertyValue-struct, die deel uitmaakt van de LibreOffice API.

## Exists

Bepaalt of een sleutel in het woordenboek voorkomt.

### Syntaxis:

dict.Exists(key: str): bool

### Parameters:

key: De sleutel die moet worden opgezocht in het woordenboek.

### Voorbeeld:

        Dim myDict as Variant
        myDict = CreateScriptService("Dictionary")
        'Voegt enkele eigenschappen toe aan het woordenboek
        myDict.Add("Color", "Blue")
        myDict.Add("Width", 20)
        '(...)
        If Not myDict.Exists("Size") Then
           MsgBox "You have to provide a Size value"
        End If

## ImportFromJson

Voegt de inhoud van een JSON (JavaScript Object Notation)-tekenreeks toe aan het huidige woordenboek. Retourneert True indien succesvol.

### Beperkingen

De JSON-tekenreeks kan getallen, tekst, booleaans, null-waardes en matrixen bevatten die die types bevatten. Het mag geen JSON-objecten bevatten, namelijk subwoordenboeken.

Er wordt geprobeerd de tekst tot op heden om te zetten als het item overeenkomt met één van deze patronen: JJJJ-MM-DD, UU:MM:SS of JJJJ-MM-DD UU:MM:SS.

### Syntaxis:

dict.ImportFromJson(inputstr: str, overwrite: bool = False): bool

### Parameters:

inputstr: De te importeren tekenreeks.

overschrijven: Wanneer True, kunnen items met dezelfde naam in het woordenboek voorkomen en worden hun waardes overschreven. Wanneer False (standaard), zullen herhaalde toetsen een fout opleveren. Houd er rekening mee dat woordenboeksleutels niet hoofdlettergevoelig zijn, terwijl namen hoofdlettergevoelig zijn in JSON-tekenreeksen.

### Voorbeeld:

        Dim s As String
        s = "{'firstName': 'John','lastName': 'Smith','isAlive': true,'age': 66, 'birth':  '1954-09-28 20:15:00'" _
            & ",'address': {'streetAddress': '21 2nd Street','city': 'New York','state': 'NY','postalCode': '10021-3100'}" _
            & ",'phoneNumbers': [{'type': 'home','number': '212 555-1234'},{'type': 'office','number': '646 555-4567'}]" _
            & ",'children': ['Q','M','G','T'],'spouse': null}"
        s = Replace(s, "'", """")
        myDict.ImportFromJson(s, OverWrite := True)
        'De (sub)woordenboeken "adres" en "telefoonnummers" (0) en (1) worden geïmporteerd als lege waardes.

## ImportFromPropertyValues

Voegt de inhoud van een matrix van PropertyValue-objecten in het huidige woordenboek in. PropertyValue Namen worden gebruikt als Sleutels in het woordenboek, terwijl Waardes de bijbehorende waardes bevatten. Retourneert True indien succesvol.

### Syntaxis:

dict.ImportFromPropertyValues(propertyvalues: obj[0..*], overwrite: bool = False): bool

### Parameters:

propertyvalues: Een op nul gebaseerde 1-dimensionale matrix met com.sun.star.beans.PropertyValue-objecten. Deze parameter kan ook een enkel PropertyValue-object zijn dat niet in een matrix staat.

overwrite: Indien True, kunnen items met dezelfde naam in het woordenboek voorkomen en worden hun waardes overschreven. Indien False (standaard), zullen herhaalde sleutels een fout opleveren. Merk op dat woordenboeksleutels in Basic niet hoofdlettergevoelig zijn, terwijl namen hoofdlettergevoelig zijn in sets met eigenschapswaardes en in Python-woordenboeken.

### Voorbeeld:

De onderstaande voorbeelden maken eerst een matrix met twee PropertyValue-objecten en converteren deze vervolgens naar een woordenboek.

##### In BASIC

        Dim vProp As New com.sun.star.beans.PropertyValue
        Dim arrProp : arrProp = Array()
        vProp.Name = "Color"
        vProp.Value = "Blue"
        arrProp = SF_Array.Append(arrProp, vProp)
        vProp.Name = "Date"
        vProp.Value = CDateToUnoDateTime(Now)
        arrProp = SF_Array.Append(arrProp, vProp)
        myDict = CreateScriptService("Dictionary")
        myDict.ImportFromPropertyValues(arrProp, Overwrite := True)
        Dim keys : keys = myDict.Keys
        For Each k In keys
            MsgBox k & " - " & myDict.Item(k)
        Next k

##### In Python

        from scriptforge import CreateScriptService
        from datetime import datetime
        import uno
        bas = CreateScriptService("Basic")
        arrProp = list()
        vProp = uno.createUnoStruct("com.sun.star.beans.PropertyValue")
        vProp.Name = "Color"
        vProp.Value = "Blue"
        arrProp.append(vProp)
        vProp = uno.createUnoStruct("com.sun.star.beans.PropertyValue")
        vProp.Name = "Date"
        vProp.Value = bas.CDateToUnoDateTime(datetime.now())
        arrProp.append(vProp)
        myDict = CreateScriptService("Dictionary")
        myDict.ImportFromPropertyValues(arrProp, overwrite=True)
        for k in myDict.keys():
            bas.MsgBox("{} - {}".format(k, myDict[k]))

## Item

Haalt een bestaand woordenboekitem op op basis van de sleutel. Retourneert de waarde van het item indien succesvol, anders wordt Leeg geretourneerd.

### Syntaxis:

dict.Item(key: str): any

### Parameters:

key: Als deze niet bestaat, wordt de waarde Leeg geretourneerd.

### Voorbeeld:

Het volgende voorbeeld herhaalt alle sleutels in het woordenboek en gebruikt de methode Item om toegang te krijgen tot hun waardes.

        Dim myDict as Variant, k as Variant, allKeys as Variant
        myDict = CreateScriptService("Dictionary")
        myDict.Add("key1", 100)
        myDict.Add("key2", 200)
        myDict.Add("key3", 300)
        allKeys = myDict.Keys
        For Each k in allKeys
           MsgBox(myDict.Item(k))
        Next k

## Remove

Verwijdert een bestaand woordenboekitem op basis van de sleutel. Retourneert True indien succesvol.

### Syntaxis:

dict.Remove(key: str): bool

### Parameters:

key: Moet in het woordenboek voorkomen, anders wordt een UNKNOWNKEYERROR-fout gegenereerd.

### Voorbeeld:

        myDict.Add("key1", 100)
        myDict.Add("key2", 200)
        myDict.Add("key3", 300)
        MsgBox(myDict.Count) ' 3
        myDict.Remove("key2")
        MsgBox(myDict.Count) ' 2

## RemoveAll

Verwijdert alle vermeldingen uit het woordenboek. Retourneert True indien succesvol.

### Syntaxis:

dict.RemoveAll(): bool

### Voorbeeld:

        myDict.Add("key1", 100)
        myDict.Add("key2", 200)
        myDict.Add("key3", 300)
        MsgBox(myDict.Count) ' 3
        myDict.RemoveAll()
        MsgBox(myDict.Count) ' 0

## ReplaceItem

Vervangt een bestaande itemwaarde op basis van de sleutel. Retourneert True indien succesvol.

### Syntaxis:

dict.ReplaceItem(key: str, value: any): bool

### Parameters:

key: Stringwaarde die de sleutel vertegenwoordigt waarvan de waarde moet worden vervangen. Als de sleutel niet in het woordenboek voorkomt, wordt een UNKNOWNKEYERROR-fout gegenereerd.

value: De nieuwe waarde van het item waarnaar wordt verwezen met de parameter key.

### Voorbeeld:

        myDict.Add("a", 1)
        MsgBox(myDict.Item("a")) ' 1
        myDict.ReplaceItem("a", 100)
        MsgBox(myDict.Item("a")) ' 100

## ReplaceKey

Vervangt een bestaande sleutel in het woordenboek door een nieuwe sleutel. De artikelwaarde blijft ongewijzigd. Retourneert True indien succesvol.

### Syntaxis:

dict.ReplaceKey(key: str, value: str): bool

### Parameters:

key: Tekenreeks die de te vervangen sleutel vertegenwoordigt. Als de sleutel niet in het woordenboek voorkomt, wordt een UNKNOWNKEYERROR-fout gegenereerd.

value: Tekenreeks voor de nieuwe sleutel. Als de nieuwe sleutel al in het woordenboek bestaat, wordt een DUPLICATEKEYERROR-fout gegenereerd.

### Voorbeeld:

        myDict.Add("oldKey", 100)
        MsgBox(myDict.Item("oldKey")) ' 100
        myDict.ReplaceKey("oldKey", "newKey")
        MsgBox(myDict.Item("newKey")) ' 100

Alle ScriptForge Basic-routines of variabelen die beginnen met een underscore "_" zijn voor intern gebruik. Gebruik deze niet in een Basic of Python-macro.

Verwante onderwerpen

ScriptForge.Array service

Verzamelobject

Help ons, alstublieft!