Dienst ScriptForge.Dictionary

Ein Wörterbuch ist eine Sammlung von Schlüsselelementpaaren

• Der Schlüssel ist eine Zeichenfolge, bei der die Groß-/Kleinschreibung nicht beachtet wird

• Einträge können von beliebiger Art sein

Schlüssel und Einträge können abgerufen, gezählt, aktualisiert und vieles mehr werden.

Der Dienst Dictionary ähnelt dem integrierten LibreOffice Basic-Objekt Collection, jedoch mit mehr Funktionen. Beispielsweise unterstützen Objekte Collection das Abrufen von Schlüsseln nicht. Darüber hinaus bieten Wörterbücher zusätzliche Funktionen wie das Ersetzen von Schlüsseln, das Testen, ob ein bestimmter Schlüssel bereits vorhanden ist, und das Konvertieren des Wörterbuchs in ein Matrixobjekt oder eine JSON-Zeichenfolge.

Dienstaufruf

Das folgende Beispiel erstellt myDict als leeres Wörterbuch.

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

Es wird empfohlen, Ressourcen nach der Verwendung freizugeben:

     Set myDict = myDict.Dispose()
  

Das folgende Beispiel erstellt eine leere Instanz des Dienstes Dictionary und verwendet die native Python-Methode update, um sie mit dem Inhalt eines Python-Objekts dict zu füllen.

    dico = dict('A' = 1, 'B' = 2, 'C' = 3)
    # myDict als leeres Objekt dict initialisieren
    myDict = CreateScriptService('Dictionary')
    # Lädt die Werte von dico in myDict
    myDict.update(dico)
    myDict['D'] = 4
    print(myDict)   # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
    propval = myDict.ConvertToPropertyValues()
  

Es ist möglich, eine Instanz des Dienstes Dictionary mit einem Python-Objekt dict als Argument zu erstellen, wie im folgenden Beispiel gezeigt.

    dico = dict('A' = 1, 'B' = 2, 'C' = 3)
    # Initialisiert myDict mit dem Inhalt von dico
    myDict = CreateScriptService('Dictionary', dico)
    myDict['D'] = 4
    print(myDict) # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
    propval = myDict.ConvertToPropertyValues()
  

Da Python über eine integrierte Wörterbuchunterstützung verfügt, sind die meisten Methoden im Dienst Dictionary nur für Basic-Skripte verfügbar. Ausnahmen sind ConvertToPropertyValues und ImportFromPropertyValues, die sowohl in Basic als auch in Python unterstützt werden.

Eigenschaften

Die Eigenschaften Keys und Items geben ihre jeweiligen Inhalte in identischer Reihenfolge zurück. Die Reihenfolge ist unabhängig von der Erstellungsreihenfolge.

Das folgende Beispiel verwendet die Eigenschaft Keys, um alle Schlüssel im Wörterbuch myDict zu durchlaufen.

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

Add

Fügt dem Wörterbuch ein neues Schlüssel-Element-Paar hinzu. Gibt bei Erfolg True zurück.

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

Key: Zeichenfolge zur Identifizierung des Artikels. Beim Schlüssel wird die Groß-/Kleinschreibung nicht beachtet.

item: Jeder Wert, einschließlich einer Matrix, eines Basic-Objekts, eines UNO-Objekts, eines Wörterbuchs und so weiter

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

Jeder Schlüssel muss im selben Wörterbuch eindeutig sein. Wenn der Schlüssel bereits im Wörterbuch vorhanden ist, wird ein Fehler DUPLICATEKEYERROR ausgelöst. Schlüssel, die aus Leerzeichen bestehen, lösen einen Fehler INVALIDKEYERROR aus.

ConvertToArray

Speichert den Inhalt des Wörterbuchs in einer zweispaltigen nullbasierten Matrix. Die Schlüssel werden in der ersten Spalte gespeichert und die Elemente werden in der zweiten Spalte gespeichert.

Wenn das Wörterbuch leer ist, gibt diese Methode eine leere Matrix zurück.

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

Konvertiert den Inhalt eines Wörterbuchs in einen JSON-Text (JavaScript Object Notation).

Einschränkungen

Diese Methode unterstützt die folgenden Datentypen: Zeichenfolgen, Boolean, Zahlen, Null und Empty. Matrizen, die Elemente dieser Typen enthalten, sind ebenfalls zulässig, unabhängig von ihren Dimensionen. Datumsangaben werden in Zeichenfolgen konvertiert, können jedoch nicht in Matrizen verwendet werden. Andere Datentypen werden mithilfe des Dienstes SF_String.Represent in entsprechende Zeichenfolgen konvertiert.

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

indent: Wenn indent eine positive Zahl oder ein Text ist, werden JSON-Matrixelemente und Objektmitglieder mit dieser Einzugsebene schön gedruckt. Ein negativer Wert für indent fügt neue Zeilen ohne Einzug hinzu. Der Standardwert ist eine leere Zeichenfolge "", die die kompakteste Darstellung auswählt. Die Verwendung einer positiven ganzen Zahl für indent rückt entsprechend viele Leerzeichen pro Ebene ein. Wenn indent eine Zeichenfolge ist, beispielsweise Chr(9) oder Tab(1), wird das Tabulatorzeichen verwendet, um jede Ebene einzurücken.

      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

Speichert den Inhalt des Wörterbuchs in einer Matrix von PropertyValues.

Jeder Eintrag in der Matrix ist ein com.sun.star.beans.PropertyValue. Der Schlüssel wird in Name gespeichert, das Element wird in Value gespeichert.

Wenn eines der Elemente vom Typ Date ist, wird es in eine Struktur com.sun.star.util.DateTime konvertiert. Wenn eines der Elemente eine leere Matrix ist, wird es in Null konvertiert. Die resultierende Matrix ist leer, wenn das Wörterbuch leer ist.

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

    Dim myDict as Variant
    myDict = CreateScriptService("Dictionary")
    ' Fügt dem Wörterbuch einige Eigenschaften hinzu
    myDict.Add("Color", "Blue")
    myDict.Add("Width", 20)
    ' Konvertiert in eine Matrix mit PropertyValue-Objekten
    Dim prop as Variant
    prop = myDict.ConvertToPropertyValues()
  

Beachten Sie im folgenden Beispiel, dass ein Python-Wörterbuch als zweites Argument der Methode CreateScriptService übergeben werden muss.

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

Viele Dienste und Methoden in der UNO-Bibliothek nehmen Parameter auf, die mit der Struktur PropertyValue dargestellt werden, die Teil der LibreOffice-API ist.

Exists

Bestimmt, ob ein Schlüssel im Wörterbuch vorhanden ist.

dict.Exists(key: str): bool

key: Der Schlüssel, der im Wörterbuch nachgeschlagen werden soll.

    Dim myDict as Variant
    myDict = CreateScriptService("Dictionary")
    ' Fügt dem Wörterbuch einige Eigenschaften hinzu
    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

Fügt den Inhalt einer JSON-Zeichenfolge (JavaScript Object Notation) in das aktuelle Wörterbuch ein. Gibt bei Erfolg True zurück.

Einschränkungen

Die JSON-Zeichenfolge kann Zahlen, Text, boolesche Werte, Nullwerte und Matrizen enthalten, die diese Typen enthalten. Es darf keine JSON-Objekte enthalten, nämlich Unterwörterbücher.

Es wird versucht, Text in Datum umzuwandeln, wenn das Element einem dieser Muster entspricht: JJJJ-MM-TT, HH:MM:SS oder JJJJ-MM-TT HH:MM:SS.

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

inputstr: Die zu importierende Zeichenfolge.

overwrite: Wenn True, können Einträge mit demselben Namen im Wörterbuch existieren und ihre Werte werden überschrieben. Bei False (Standard) lösen wiederholte Tastenkombinationen einen Fehler aus. Beachten Sie, dass bei Wörterbuchschlüsseln nicht zwischen Groß- und Kleinschreibung unterschieden wird, während bei Namen in JSON-Zeichenfolgen zwischen Groß- und Kleinschreibung unterschieden wird.

    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)
    ' Die (Unter-)Wörterbücher "Adresse" und "Telefonnummern" (0) und (1) werden als Leerwerte importiert.
  

ImportFromPropertyValues

Fügt den Inhalt einer Matrix von Objekten PropertyValue in das aktuelle Wörterbuch ein. Namen PropertyValue werden als Schlüssel im Wörterbuch verwendet, während Werte die entsprechenden Werte enthalten. Gibt bei Erfolg True zurück.

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

propertyvalues: Eine nullbasierte eindimensionale Matrix, die Objekte vom Typ com.sun.star.beans.PropertyValue enthält. Dieser Parameter kann auch ein einzelnes Objekt PropertyValue sein, das nicht in einer Matrix enthalten ist.

overwrite: Wenn True, können Einträge mit demselben Namen im Wörterbuch existieren und ihre Werte werden überschrieben. Bei False (Standard) lösen wiederholte Schlüssel einen Fehler aus. Beachten Sie, dass bei Wörterbuchschlüsseln in Basic nicht zwischen Groß- und Kleinschreibung unterschieden wird, während bei Namen in Sätzen von Eigenschaftswerten und in Python-Wörterbüchern zwischen Groß- und Kleinschreibung unterschieden wird.

Die folgenden Beispiele erstellen zuerst eine Matrix mit zwei Objekten vom Typ PropertyValue und konvertieren es dann in ein Wörterbuch.

    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

Ruft einen vorhandenen Wörterbucheintrag basierend auf seinem Schlüssel ab. Gibt bei Erfolg den Wert des Elements zurück, ansonsten Empty.

dict.Item(key: str): any

key: Groß- und Kleinschreibung wird nicht beachtet. Wenn es nicht existiert, wird der Wert Empty zurückgegeben.

Das folgende Beispiel iteriert über alle Schlüssel im Wörterbuch und verwendet die Methode Item, um auf ihre Werte zuzugreifen.

    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

Entfernt einen vorhandenen Wörterbucheintrag basierend auf seinem Schlüssel. Gibt bei Erfolg True zurück.

dict.Remove(key: str): bool

key: Groß- und Kleinschreibung wird nicht beachtet. Muss im Wörterbuch vorhanden sein, sonst wird ein UNKNOWNKEYERROR-Fehler ausgelöst.

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

RemoveAll

Entfernt alle Einträge aus dem Wörterbuch. Gibt bei Erfolg True zurück.

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

Ersetzt einen vorhandenen Elementwert basierend auf seinem Schlüssel. Gibt bei Erfolg True zurück.

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

key: Zeichenfolge, die den Schlüssel darstellt, dessen Wert ersetzt wird. Groß-/Kleinschreibung nicht beachten. Wenn der Schlüssel nicht im Wörterbuch vorhanden ist, wird ein Fehler UNKNOWNKEYERROR ausgegeben.

value: Der neue Wert des Elements, auf das mit dem Parameter key verwiesen wird.

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

ReplaceKey

Ersetzt einen vorhandenen Schlüssel im Wörterbuch durch einen neuen Schlüssel. Der Artikelwert bleibt unverändert. Gibt bei Erfolg True zurück.

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

key: Zeichenfolge, die den zu ersetzenden Schlüssel darstellt. Groß-/Kleinschreibung nicht beachten. Wenn der Schlüssel nicht im Wörterbuch vorhanden ist, wird ein Fehler UNKNOWNKEYERROR ausgelöst.

value: Zeichenfolge für den neuen Schlüssel. Groß-/Kleinschreibung nicht beachten. Wenn der neue Schlüssel bereits im Wörterbuch vorhanden ist, wird ein Fehler DUPLICATEKEYERROR ausgelöst.

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

Alle ScriptForge Basic-Routinen oder Bezeichner, denen ein Unterstrich "_" vorangestellt ist, sind für den internen Gebrauch reserviert. Sie sind nicht für die Verwendung in Basic-Makros oder Python-Skripten vorgesehen.