Inhalte

# 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

##### In Basic

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

##### In Python

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

Name | Schreibgeschützt | 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

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

Liste der Methoden im Dienst "Dictionary"
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:

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

### Parameter:

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

### Beispiel:

          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.

### Syntax:

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

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

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

### Parameter:

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.

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

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

### Beispiel:

##### In Basic

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

##### In Python

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.

### Syntax:

dict.Exists(key: str): bool

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

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

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

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

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

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

### Beispiel:

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

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

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

### Syntax:

dict.Item(key: str): any

### Parameter:

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

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

dict.Remove(key: str): bool

### Parameter:

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

### Beispiel:

        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.

### Syntax:

dict.RemoveAll(): bool

### Beispiel:

        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.

### Syntax:

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

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

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

### Beispiel:

        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.

### Syntax:

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

### 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")) ' 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.

Verwandte Themen

Dienst ScriptForge.Array

Objekt Collection