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

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

Da Python ├╝ber eine integrierte W├Ârterbuchunterst├╝tzung verf├╝gt, sind die meisten Methoden im Dienst Dictionary nur f├╝r Basic-Skripts 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


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:

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

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

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

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.


Bitte unterst├╝tzen Sie uns!