Dienst ScriptForge.Dictionary

Ein Wörterbuch ist eine Sammlung von Schlüsselelementpaaren

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

Tippsymbol

Das LibreOffice Basic-Objekt Collection unterstützt das Abrufen der Schlüssel nicht.
Außerdem enthalten seine Elemente nur primitive Grunddatentypen wie Datum, Text, Zahlen und dergleichen.


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

Eigenschaften

Name

ReadOnly

Typ

Beschreibung

Count

Ja

Long

Die Anzahl der Einträge im Wörterbuch

Items

Ja

Matrix mit Variants

Die Liste der Elemente als eindimensionale Matrix

Keys

Ja

Matrix mit Zeichenfolgen

Die Liste der Schlüssel als eindimensionale Matrix


Tippsymbol

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


Beispiel:

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
    

Methoden

Add
ConvertToArray
ConvertToJson
ConvertToPropertyValues

Exists
ImportFromJson
ImportFromPropertyValues
Item

Remove
RemoveAll
ReplaceItem
ReplaceKey


Add

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

Syntax:


          myDict.Add(Key As String, Item As Variant) As Boolean
        

Parameter:

Key: Zeichenfolge, der zur Identifizierung des Artikels verwendet wird. 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 …

Beispiel:


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

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.

Syntax:


          myDict.ConvertToArray() As Variant
        

Beispiel:


        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.

Syntax:


            myDict.ConvertToJson([Indent As Variant]) As String
        

Parameter:

Indent: Wenn Endent 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. Standardwert "" für Indent wählt die kompakteste Darstellung. 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.

Beispiel:


            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.

Syntax:


          myDict.ConvertToPropertyValues() As Variant
        

Beispiel:


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

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


Exists

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

Syntax:


          myDict.Exists(Key As String) As Boolean
        

Parameter:

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

Beispiel:


          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.

Syntax:


            myDict.ImportFromJson(InputStr As String, [Overwrite As Boolean]) As Boolean
        

Parameter:

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 Schlüssel einen Fehler aus. Beachten Sie, dass bei Wörterbuchschlüsseln nicht zwischen Groß- und Kleinschreibung unterschieden wird, während bei Namen in JSON-Strings zwischen Groß- und Kleinschreibung unterschieden wird.

Beispiel:


            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.

Syntax:


            myDict.ImportFromPropertyValues(PropertyValues As Variant [, Overwrite As Boolean]) As Boolean
        

Parameter:

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 die Groß-/Kleinschreibung nicht beachtet wird, während bei Namen in Sätzen von Eigenschaftswerten die Groß-/Kleinschreibung beachtet wird.

Beispiel:


            Dim vProp As New com.sun.star.beans.PropertyValue
            vProp.Name = "prop"
            vProp.Value = CDateToUnoDateTime(Now)
            myDict.ImportFromPropertyValues(vProp, Overwrite := True)
        

Item

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

Syntax:


          myDict.Item(Key As String) As Variant
        

Parameter:

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

Beispiel:

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.

Syntax:


          myDict.Remove(Key As String) As Boolean
        

Parameter:

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

Beispiel:


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

RemoveAll

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

Syntax:


          myDict.RemoveAll() As Boolean
        

Beispiel:


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

ReplaceItem

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

Syntax:


          myDict.ReplaceItem(Key As String, Value As Variant) As Boolean
        

Parameter:

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 ausgelöst.

Value: Der neue Wert des Elements, auf das mit dem Schlüsselparameter verwiesen wird.

Beispiel:


          myDict.Add("a", 1)
          MsgBox(myDict.Item("a")) 'Prints "1"
          myDict.ReplaceItem("a", 100)
          MsgBox(myDict.Item("a")) ' Prints "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.

Syntax:


          myDict.ReplaceKey(Key As String, Value As String) As Boolean
        

Parameter:

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.

Beispiel:


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

Alle Basic-Routinen oder -Identifikatoren von ScriptForge mit einem Unterstrich "_" sind für internen Gebrauch reserviert. Sie sind nicht für den Einsatz in Basic-Macros gedacht.