ScriptForge.Dictionary dienst

Een woordenboek is een verzameling sleutel-itemparen

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

Tippictogram

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 BASIC

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

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

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


Tippictogram

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
    

Methoden

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

Voorbeeld:


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

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

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

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

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.

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

Syntaxis:

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

Parameters:

inputstr: De te importeren tekenreeks.

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. Let op dat woordenboeksleutels niet hoofdlettergevoelig zijn, terwijl namen in JSON-tekenreeksen hoofdlettergevoelig zijn.

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

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

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: Niet hoofdlettergevoelig. Als het niet bestaat, wordt de waarde Empty geretourneerd.

Voorbeeld:

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.

Syntaxis:

dict.Remove(key: str): bool

Parameters:

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

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

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

Voorbeeld:


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

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


Help ons, alstublieft!