Spis treści

# 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

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

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

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)

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

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

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.

Tematy pokrewne

Usługa ScriptForge.Array

Obiekt Collection