ScriptForge.Dictionary dienst

Een woordenboek is een verzameling sleutel-itemparen

• De sleutel is een niet hoofdlettergevoelige tekenreeks

• 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 functies. Bijvoorbeeld, Collection-objecten ondersteunen het ophalen van sleutels niet. Bovendien bieden woordenboeken extra mogelijkheden zoals het vervangen van sleutels, testen of een specifieke sleutel al bestaat en het omzetten van het woordenboek in een matrix-object of JSON-string.

Service aanroep

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

    GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
    Dim myDict As Variant
    myDict = CreateScriptService("Dictionary")
  

Het wordt aanbevolen om na gebruik middelen vrij te maken:

     Set myDict = myDict.Dispose()
  

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 dict-object
    myDict = CreateScriptService('Dictionary')
    # Laad de waarden 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 woordenboekondersteuning heeft, zijn de meeste methoden in de service Dictionary alleen beschikbaar voor basisscripts. Uitzonderingen zijn ConvertToPropertyValues en ImportFromPropertyValues die worden ondersteund in zowel Basic als Python.

Eigenschappen

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.

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
    

Add

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

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

key: Tekenreeks die wordt gebruikt om het item te identificeren. De sleutel is niet hoofdlettergevoelig.

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

      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.

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

      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 gegevenstypen: 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 gegevenstypen worden geconverteerd naar hun tekenreeksweergave met behulp van de service SF_String.Represent.

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

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.

      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 een van de items het type Date heeft, wordt het geconverteerd naar een com.sun.star.util.DateTime-structuur. Als een van de items een lege matrix is, wordt deze geconverteerd naar Null. De resulterende matrix is leeg als het woordenboek leeg is.

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

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

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

dict.Exists(key: str): bool

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

    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-waarden en matrixen bevatten die die typen 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 een van deze patronen: JJJJ-MM-DD, UU:MM:SS of JJJJ-MM-DD UU:MM:SS.

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

inputstr: De te importeren tekenreeks.

overschrijven: Wanneer True, kunnen items met dezelfde naam in het woordenboek voorkomen en worden hun waarden 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.

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

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 Waarden de bijbehorende waarden bevatten. Retourneert True indien succesvol.

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

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 waarden 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 eigenschapswaarden en in Python-woordenboeken.

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

    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
  

    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.

dict.Item(key: str): any

key: Niet hoofdlettergevoelig. Als het niet bestaat, wordt de waarde Empty geretourneerd.

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

    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.

dict.Remove(key: str): bool

key: Niet hoofdlettergevoelig. Moet in het woordenboek voorkomen, anders wordt een UNKNOWNKEYERROR-fout weergegeven.

    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.

dict.RemoveAll(): bool

    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.

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

key: Tekenreekswaarde die de sleutel vertegenwoordigt waarvan de waarde wordt vervangen. Niet hoofdlettergevoelig. Als de sleutel niet in het woordenboek voorkomt, wordt de fout UNKNOWNKEYERROR weergegeven.

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

    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.

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

key: Tekenreeks die de sleutel vertegenwoordigt die moet worden vervangen. Niet hoofdlettergevoelig. Als de sleutel niet in het woordenboek voorkomt, wordt de fout UNKNOWNKEYERROR weergegeven.

value: Tekenreeks voor de nieuwe sleutel. Niet hoofdlettergevoelig. Als de nieuwe sleutel al in het woordenboek bestaat, wordt de fout DUPLICATEKEYERROR weergegeven.

    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.