Usługa ScriptForge.Dictionary

Słownik to zbiór par klucz-element

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

Ikona wskazówki

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

W języku Basic

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()
  
W języku Python

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

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

Nazwa

Tylko do odczytu

Typ

Opis

Count

Tak

Long

Liczba wpisów w słowniku

Items

Tak

Tablica wariantów

Lista elementów w postaci tablicy jednowymiarowej

Keys

Tak

Tablica ciągów

Lista kluczy jako tablica jednowymiarowa


Ikona wskazówki

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


Przykład:

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
    

Lista metod w usłudze Dictionary

Add
ConvertToArray
ConvertToJson
ConvertToPropertyValues

Exists
ImportFromJson
ImportFromPropertyValues
Item

Remove
RemoveAll
ReplaceItem
ReplaceKey


Add

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

Składnia:

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

Parametry:

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.

Przykład:


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

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.

Składnia:

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

Przykład:


      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.

Składnia:

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

Parametry:

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.

Przykład:


      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.

Składnia:

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

Przykład:

W języku Basic

    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 języku Python

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

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.

Składnia:

dict.Exists(key: str): bool

Parametry:

key: klucz do sprawdzenia w słowniku.

Przykład:


    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.

Składnia:

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

Parametry:

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.

Przykład:


    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.

Składnia:

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

Parametry:

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.

Przykład:

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

W języku 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
  
W języku 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

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

Składnia:

dict.Item(key: str): any

Parametry:

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

Przykład:

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.

Składnia:

dict.Remove(key: str): bool

Parametry:

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

Przykład:


    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.

Składnia:

dict.RemoveAll(): bool

Przykład:


    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.

Składnia:

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

Parametry:

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.

Przykład:


    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.

Składnia:

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

Parametry:

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.

Przykład:


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

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.


Prosimy o wsparcie!