Usługa ScriptForge.Dictionary

Słownik to zbiór par klucz-element

• Klucz jest ciągiem znaków, w którym nie jest rozróżniana wielkość liter

• Elementy mogą być dowolnego typu

Klucze i elementy można odzyskiwać, liczyć, aktualizować i wykonywać wiele innych czynności.

Usługa Dictionary jest podobna do wbudowanego obiektu Collection LibreOffice Basic, ma jednak więcej funkcji. Na przykład obiekty Collection nie obsługują odzyskiwania kluczy. Co więcej, słowniki zapewniają dodatkowe możliwości, takie jak zastępowanie kluczy, sprawdzanie, czy określony klucz już istnieje i konwertowanie słownika na obiekt Array lub ciąg JSON.

Wywoływanie usługi

Poniższy przykład tworzy myDict jako pusty słownik.

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

Zaleca się zwolnienie zasobów po użyciu:

     Set myDict = myDict.Dispose()
  

Poniższy przykład tworzy pustą instancję usługi Dictionary i używa natywnej metody Pythona update do zapełnienia jej zawartością obiektu dict Pythona.

    dico = dict('A' = 1, 'B' = 2, 'C' = 3)
    # Zainicjuj myDict jako pusty obiekt dict
    myDict = CreateScriptService('Dictionary')
    # Załaduj wartości dico do myDict
    myDict.update(dico)
    myDict['D'] = 4
    print(myDict)   # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
    propval = myDict.ConvertToPropertyValues()
  

Możliwe jest utworzenie instancji usługi Dictionary przy użyciu obiektu Pythona dict jako argumentu, jak pokazano w poniższym przykładzie.

    dico = dict('A' = 1, 'B' = 2, 'C' = 3)
    # Zainicjuj myDict zawartością dico
    myDict = CreateScriptService('Dictionary', dico)
    myDict['D'] = 4
    print(myDict) # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
    propval = myDict.ConvertToPropertyValues()
  

Ponieważ Python ma wbudowaną obsługę słowników, większość metod usługi Dictionary jest dostępna tylko dla skryptów Basic. Wyjątkami są ConvertToPropertyValues i ImportFromPropertyValues, które są obsługiwane zarówno w języku Basic, jak i Python.

Właściwości

Właściwości Keys i Items zwracają odpowiednią zawartość, stosując identyczną kolejność. Kolejność nie jest powiązana z kolejnością tworzenia.

W poniższym przykładzie użyto właściwości Keys do iteracji po wszystkich kluczach w słowniku myDict.

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

Add

Dodaje nową parę klucz-element do słownika. Zwraca wartość True, jeśli operacja się powiedzie.

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

key: wartość ciągu używana do identyfikacji elementu. W kluczu nie jest rozróżniana wielkość liter.

item: dowolna wartość, w tym tablica, obiekt Basic, obiekt UNO, słownik itp.

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

Każdy klucz musi być unikalny w tym samym słowniku. Jeśli klucz już istnieje w słowniku, zostanie zgłoszony komunikat DUPLICATEKEYERROR. Klucze składające się ze spacji spowodują błąd INVALIDKEYERROR.

ConvertToArray

Przechowuje zawartość słownika w dwukolumnowej tablicy liczonej od zera. Klucze są przechowywane w pierwszej kolumnie, a elementy są przechowywane w drugiej kolumnie.

Jeśli słownik jest pusty, ta metoda zwróci pustą Array.

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

Konwertuje zawartość słownika na tekst JSON (JavaScript Object Notation).

Ograniczenia

Ta metoda obsługuje następujące typy danych: String, Boolean, liczby, Null i Empty. Tablice zawierające elementy tego typu są również dozwolone, niezależnie od ich wymiarów. Daty są konwertowane na ciągi znaków, jednak nie można ich używać wewnątrz tablic. Inne typy danych są konwertowane na ich reprezentację w postaci ciągu znaków przy użyciu usługi SF_String.Represent.

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

indent: gdy indent jest liczbą dodatnią lub tekstem, elementy tablicy JSON i elementy obiektu są ładnie drukowane z tym poziomem wcięcia. Ujemna wartość indent spowoduje dodanie nowych wierszy bez wcięć. Wartość domyślna to pusty ciąg znaków "", który wybiera najbardziej zwartą reprezentację. Użycie dodatniej liczby całkowitej dla indent powoduje wcięcie o tyle spacji na poziom. Gdy indent jest ciągiem znaków, np. Chr(9) lub Tab(1), znak tabulacji służy do wcięcia każdego poziomu.

      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

Przechowuje zawartość słownika w tablicy PropertyValues.

Każdy wpis w tablicy to com.sun.star.beans.PropertyValue. Klucz jest przechowywany w Name, element jest przechowywany w Value.

Jeśli jeden z elementów ma typ Date, jest konwertowany na strukturę com.sun.star.util.DateTime. Jeśli jeden z elementów jest pustą tablicą, jest konwertowany na wartość Null. Wynikowa tablica jest pusta, gdy słownik jest pusty.

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

    Dim myDict as Variant
    myDict = CreateScriptService("Dictionary")
    ' Dodaje niektóre właściwości do słownika
    myDict.Add("Color", "Blue")
    myDict.Add("Width", 20)
    ' Konwertuje na tablicę obiektów PropertyValue
    Dim prop as Variant
    prop = myDict.ConvertToPropertyValues()
  

W poniższym przykładzie zauważ, że jako drugi argument metody CreateScriptService należy przekazać słownik języka Python.

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

Wiele usług i metod w bibliotece UNO przyjmuje parametry reprezentowane za pomocą struktury PropertyValue, która jest częścią interfejsu API LibreOffice.

Exists

Określa, czy klucz istnieje w słowniku.

dict.Exists(key: str): bool

key: klucz do sprawdzenia w słowniku.

    Dim myDict as Variant
    myDict = CreateScriptService("Dictionary")
    ' Dodaje niektóre właściwości do słownika
    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

Dodaje zawartość ciągu JSON (JavaScript Object Notation) do bieżącego słownika. Zwraca wartość True, jeśli operacja się powiedzie.

Ograniczenia

Ciąg JSON może zawierać liczby, tekst, wartości logiczne, wartości null i tablice zawierające te typy. Nie może zawierać obiektów JSON, czyli słowników podrzędnych.

Podejmowana jest próba konwersji dotychczasowego tekstu, jeśli pozycja pasuje do jednego z poniższych wzorców: RRRR-MM-DD, HH:MM:SS lub RRRR-MM-DD HH:MM:SS.

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

inputstr: ciąg do zaimportowania.

overwrite: gdy True, w słowniku mogą istnieć wpisy o tej samej nazwie, a ich wartości zostaną nadpisane. Gdy False (domyślnie), powtarzane klucze spowodują błąd. Należy pamiętać, że w kluczach słownika nie jest rozróżniana wielkość liter, natomiast w nazwach w ciągach JSON wielkość liter jest uwzględniana.

    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)
    ' (Pod)słowniki „address” i „phoneNumbers” (0) i (1) są importowane jako wartości puste.
  

ImportFromPropertyValues

Wstawia zawartość tablicy obiektów PropertyValue do bieżącego słownika. Nazwy PropertyValue są używane jako klucze w słowniku, natomiast wartości zawierają odpowiadające im wartości. Zwraca wartość True, jeśli operacja się powiedzie.

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

propertyvalues: jednowymiarowa tablica liczona od zera zawierająca obiekty com.sun.star.beans.PropertyValue. Ten parametr może być także pojedynczym obiektem PropertyValue, który nie jest zawarty w tablicy.

overwrite: gdy True, w słowniku mogą znajdować się wpisy o tej samej nazwie, a ich wartości zostaną nadpisane. Gdy False (domyślnie), powtarzane klucze spowodują błąd. Należy pamiętać, że w kluczach słownika w języku Basic nie jest rozróżniana wielkość liter, natomiast w nazwach w zestawach wartości właściwości i słownikach języka Python rozróżniana jest wielkość liter.

Poniższe przykłady najpierw tworzą tablicę z dwoma obiektami PropertyValue, a następnie konwertują ją na słownik.

    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

Pobiera istniejący wpis słownika na podstawie jego klucza. Zwraca wartość elementu, jeśli się powiedzie, w przeciwnym razie zwraca Empty.

dict.Item(key: str): any

key: nie rozróżniana jest wielkość liter. Jeżeli nie istnieje, zwracana jest wartość Empty.

Poniższy przykład iteruje po wszystkich kluczach w słowniku i używa metody Item, aby uzyskać dostęp do ich wartości.

    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

Usuwa istniejący wpis słownika na podstawie jego klucza. Zwraca wartość True, jeśli operacja się powiedzie.

dict.Remove(key: str): bool

key: nie rozróżniana jest wielkość liter. Musi istnieć w słowniku, w przeciwnym razie zostanie zgłoszony błąd UNKNOWNKEYERROR.

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

RemoveAll

Usuwa wszystkie wpisy ze słownika. Zwraca wartość True, jeśli operacja się powiedzie.

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

Zastępuje istniejącą wartość elementu na podstawie jej klucza. Zwraca wartość True, jeśli operacja się powiedzie.

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

key: wartość ciągu reprezentująca klucz, którego wartość zostanie zastąpiona. Nie rozróżniana jest wielkość liter. Jeżeli klucz nie istnieje w słowniku, zgłaszany jest błąd UNKNOWNKEYERROR.

value: nowa wartość elementu, do którego odnosi się parametr key.

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

ReplaceKey

Zastępuje istniejący klucz w słowniku nowym kluczem. Wartość przedmiotu pozostaje niezmieniona. Zwraca wartość True, jeśli operacja się powiedzie.

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

key: wartość ciągu reprezentująca klucz, który ma zostać zastąpiony. Nie rozróżniana jest wielkość liter. Jeśli klucz nie istnieje w słowniku, zostanie zgłoszony błąd UNKNOWNKEYERROR.

value: wartość ciągu dla nowego klucza. Nie rozróżniana jest wielkość liter. Jeśli nowy klucz już istnieje w słowniku, zostanie zgłoszony błąd DUPLICATEKEYERROR.

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

Wszystkie podstawowe procedury lub identyfikatory ScriptForge poprzedzone znakiem podkreślenia „_” są zarezerwowane do użytku wewnętrznego. Nie należy ich używać w makrach Basic ani skryptach Pythona.