Obsah

# Služba ScriptForge.Dictionary

Slovník je kolekce dvojic klíč a položka.

- Klíč je řetězec, u něhož nezáleží na velikosti znaků.

- Položky mohou být jakéhokoliv typu.

Klíče a položky je možné získávat, počítat, aktualizovat atd.

Služba Dictionary se podobá objektu Collection, který je v jazyce LibreOffice Basic vestavěný, je však funkčně bohatší. Objekty Collection například neumožňují získávat klíče. Slovníky navíc nabízejí další operace jako nahrazování klíčů, ověřování, zda určitý klíč již existuje či převod slovníku na pole (objekt Array) nebo řetězec formátu JSON.

## Volání služby

##### V Basicu

V následujícím příkladu se vytvoří prázdný slovník myDict.

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

Po použití se doporučuje uvolnit zdroje:

         Set myDict = myDict.Dispose()

##### V Pythonu

V níže uvedeném příkladu se vytvoří prázdná instance služby Dictionary a pomocí nativní metody Pythonu update se naplní obsahem objektu Pythonu dict.

        dico = dict('A' = 1, 'B' = 2, 'C' = 3)
        # Inicializuje prázdný objekt dict s názvem myDict
        myDict = CreateScriptService('Dictionary')
        # Načte hodnoty slovníku dico do slovníku myDict
        myDict.update(dico)
        myDict['D'] = 4
        print(myDict)   # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
        propval = myDict.ConvertToPropertyValues()

Při vytváření instance služby Dictionary je možné použít objekt Pythonu dict jako argument, jak ukazuje následující příklad.

        dico = dict('A' = 1, 'B' = 2, 'C' = 3)
        # Inicializuje slovník myDict obsahem slovníku dico
        myDict = CreateScriptService('Dictionary', dico)
        myDict['D'] = 4
        print(myDict) # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
        propval = myDict.ConvertToPropertyValues()

Protože Python již vestavěnou podporu pro slovník obsahuje, je většina metod služby Dictionary k dispozici pouze pro skripty Basicu. Výjimku tvoří metody ConvertToPropertyValues a ImportFromPropertyValues, podporované jak v Basicu, tak v Pythonu.

## Vlastnosti

Název | Pouze pro čtení | Typ | Popis
--- | --- | --- | ---
Count | ano | Long | Počet záznamů ve slovníku.
Items | ano | pole typu Variant | Seznam položek jako jednorozměrné pole.
Keys | ano | pole řetězců (String) | Seznam klíčů jako jednorozměrné pole.

Vlastnosti Keys a Items vrátí svůj obsah ve stejném pořadí, které nesouvisí s vytvářením slovníku.

### Příklad:

V následujícím příkladu se používá vlastnost Keys pro iterování přes všechny klíče slovníku myDict.

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

Seznam metod služby Dictionary
Add ConvertToArray ConvertToJson ConvertToPropertyValues | Exists ImportFromJson ImportFromPropertyValues Item | Remove RemoveAll ReplaceItem ReplaceKey

## Add

Přidá do slovníku novou dvojici klíč-položka. V případě úspěšného přidání vrátí True.

### Syntaxe:

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

### Parametry:

key: Řetězec použitý k identifikaci položky. Nerozlišuje se u něj velikost písmen.

item: Jakákoliv hodnota, včetně pole, objektu Basicu, objektu UNO, slovníku apod.

### Příklad:

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

Klíč musí být v rámci slovníku jedinečný. Pokud klíč již ve slovníku existuje, nastane chyba DUPLICATEKEYERROR. Klíče obsahující pouze znaky mezer vyvolají chybu INVALIDKEYERROR.

## ConvertToArray

Uloží obsah slovníku do pole začínajícího od 0 a obsahujícího dva sloupce. Do prvního sloupce se uloží klíče, do druhého položky.

Je-li slovník prázdný, metoda vrátí prázdné pole (Array).

### Syntaxe:

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

### Příklad:

          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

Převede obsah slovníku na text formátu JSON (JavaScript Object Notation).

### Omezení

Metoda podporuje následující datové typy: String, Boolean, čísla, Null a Empty. Povolena jsou rovněž pole obsahující položky těchto typů, a to bez ohledu na rozměry pole. Data jsou převedena na řetězce, nemohou však být použita v polích. Jiné datové typy jsou pomocí služby SF_String.Represent převedeny na své řetězcové reprezentace.

### Syntaxe:

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

### Parametry:

indent: Je-li indent kladné číslo nebo text, prvky polí a objektů se naformátují se stanovenou úrovní odsazení. Při záporné hodnotě se budou nové řádky přidávat bez odsazení. Výchozí hodnotou je prázdný řetězec "", který znamená nejkompaktnější formát. Kladné číslo pro indent značí, kolik mezer má jedna úroveň odsazení. Pokud je hodnota indent řetězec, například Chr(9) či Tab(1), pro odsazení úrovní se použije znak tabulátoru.

### Příklad:

          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

Uloží obsah slovníku do pole PropertyValues.

Každá položka pole je strukturou com.sun.star.beans.PropertyValue. Klíč je v ní uložen jako Name, položka jako Value.

Jestliže je některá z položek typu Date, převede se na strukturu com.sun.star.util.DateTime. Je-li položkou prázdné pole, převede se na Null. Pokud je slovník prázdný, bude prázdné i výsledné pole.

### Syntaxe:

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

### Příklad:

##### V Basicu

        Dim myDict as Variant
        myDict = CreateScriptService("Dictionary")
        ' Přidá do slovníku nějaké vlastnosti
        myDict.Add("Color", "Blue")
        myDict.Add("Width", 20)
        ' Převede slovník na pole objektů PropertyValue
        Dim prop as Variant
        prop = myDict.ConvertToPropertyValues()

##### V Pythonu

V následujícím příkladu je použit slovník Pythonu jako druhý argument metody CreateScriptService.

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

Struktura PropertyValue, která je součástí API pro LibreOffice, se používá pro reprezentaci parametrů předávaných do mnoha služeb a metod knihovny UNO.

## Exists

Určuje, zda klíč ve slovníku existuje.

### Syntaxe:

dict.Exists(key: str): bool

### Parametry:

key: Klíč, který se má ve slovníku vyhledat.

### Příklad:

        Dim myDict as Variant
        myDict = CreateScriptService("Dictionary")
        ' Přidá do slovníku nějaké vlastnosti
        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

Přidá do aktuálního slovníku obsah řetězce formátu JSON (JavaScript Object Notation). V případě úspěšného přidání vrátí True.

### Omezení

Řetězec formátu JSON může obsahovat čísla, text, booleovské hodnoty, hodnoty null a pole obsahující tyto typy. Nesmí obsahovat objekty, tj. podslovníky.

Při importu se vyzkouší převod textu na datum, a to v případě, že položka odpovídá některému z těchto vzorků: YYYY-MM-DD, HH:MM:SS nebo YYYY-MM-DD HH:MM:SS.

### Syntaxe:

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

### Parametry:

inputstr: Řetězec, který se má naimportovat.

overwrite: Je-li True, je povoleno, aby položky téhož názvu již ve slovníku existovaly, a jejich hodnoty jsou přepsány. Je-li False (výchozí), opakovaný klíč způsobí chybu. Mějte na paměti, že u klíčů slovníku se velikost písmen nerozlišuje, zatímco u řetězců formátu JSON ano.

### Příklad:

        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)
        ' Podslovníky "address" a "phoneNumbers" (0) a (1) jsou naimportovány jako hodnoty Empty.

## ImportFromPropertyValues

Vloží do aktuálního slovníku obsah pole objektů PropertyValue. Prvky Name z PropertyValue se použijí jako klíče slovníku, zatímco prvky Value jako jim odpovídající hodnoty. V případě úspěšného přidání vrátí True.

### Syntaxe:

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

### Parametry:

propertyvalues: Jednorozměrné pole začínající od 0 obsahující objekty com.sun.star.beans.PropertyValue, případně jediný objekt PropertyValue, který není součástí pole.

overwrite: Je-li True, je povoleno, aby položky téhož názvu již ve slovníku existovaly, a jejich hodnoty jsou přepsány. Je-li False (výchozí), opakovaný klíč způsobí chybu. Mějte na paměti, že u klíčů slovníku se velikost písmen nerozlišuje, zatímco u názvů v objektech PropertyValue a ve slovnících Pythonu ano.

### Příklad:

V následujícím příkladu se nejprve vytvoří pole se dvěma objekty PropertyValue a poté se převede na slovník.

##### V Basicu

        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

##### V Pythonu

        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

Získá pro zadaný klíč existující položku slovníku. Pokud klíč existuje, vrátí hodnotu položky, v opačném případě vrátí Empty.

### Syntaxe:

dict.Item(key: str): any

### Parametry:

key: Nerozlišuje se u něj velikost písmen. Pokud neexistuje, vrátí se hodnota Empty.

### Příklad:

V následujícím příkladu se iteruje přes všechny klíče slovníku a pomocí metody Item se přistupuje k jeho hodnotám.

        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

Odstraní pro zadaný klíč existující záznam slovníku. V případě úspěšného odstranění vrátí True.

### Syntaxe:

dict.Remove(key: str): bool

### Parametry:

key: Nerozlišuje se u něj velikost písmen. Pokud ve slovníku neexistuje, nastane chyba UNKNOWNKEYERROR.

### Příklad:

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

## RemoveAll

Odstraní ze slovníku všechny záznamy. V případě úspěšného odstranění vrátí True.

### Syntaxe:

dict.RemoveAll(): bool

### Příklad:

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

## ReplaceItem

Nahradí pro zadaný klíč hodnotu existující položky slovníku. V případě úspěšného nahrazení vrátí True.

### Syntaxe:

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

### Parametry:

key: Řetězec představující klíč, jehož hodnota se má nahradit. Nerozlišuje se u něj velikost písmen. Pokud ve slovníku neexistuje, nastane chyba UNKNOWNKEYERROR.

value: Nová hodnota položky přiřazené k parametru key.

### Příklad:

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

## ReplaceKey

Nahradí existující klíč slovníku jiným. Hodnota položky se nezmění. V případě úspěšného nahrazení vrátí True.

### Syntaxe:

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

### Parametry:

key: Řetězec představující klíč, který se má nahradit. Nerozlišuje se u něj velikost písmen. Pokud ve slovníku neexistuje, nastane chyba UNKNOWNKEYERROR.

value: Řetězec pro nový klíč. Nerozlišuje se u něj velikost písmen. Pokud ve slovníku již existuje, nastane chyba DUPLICATEKEYERROR.

### Příklad:

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

Všechny procedury nebo identifikátory knihovny ScriptForge, které jsou uvozeny podtržítkem "_", jsou určeny pro interní použití. Není zamýšleno je používat v makrech Basicu nebo skriptech Pythonu.

Související témata

Služba ScriptForge.Array

Objekt Collection