Obsah
Rejstřík 🔎︎

# 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.

Objekty Collection jazyka LibreOffice Basic neumožňují získávat klíče.
Navíc jejich položky obsahují pouze primitivní datové typu Basicu jako data, text, čísla apod.

## Volání služby

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

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

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

              myDict.Add(Key As String, Item As Variant) As Boolean

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

              myDict.ConvertToArray() As Variant

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

                myDict.ConvertToJson([Indent As Variant]) As String

### Parametry:

Indent : When Indent is a positive number or a text, JSON array elements and object members are pretty-printed with that indentation level. A negative Indent value will add new lines with no indentation. Indent default value "" selects the most compact representation. Using a positive integer for Indent indents that many spaces per level. When Indent is a string, such as Chr(9) or Tab(1), the Tab character is used to indent each level.

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

              myDict.ConvertToPropertyValues() As Variant

### 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)
              ' Převede slovník na pole objektů PropertyValue
              Dim prop as Variant
              prop = myDict.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:

              myDict.Exists(Key As String) As Boolean

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

                myDict.ImportFromJson(InputStr As String, [Overwrite As Boolean]) As Boolean

### 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ři importu 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:

                myDict.ImportFromPropertyValues(PropertyValues As Variant [, Overwrite As Boolean]) As Boolean

### 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 ano.

### Příklad:

                Dim vProp As New com.sun.star.beans.PropertyValue
                vProp.Name = "prop"
                vProp.Value = CDateToUnoDateTime(Now)
                myDict.ImportFromPropertyValues(vProp, Overwrite := True)

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

              myDict.Item(Key As String) As Variant

### Parametry:

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

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

              myDict.Remove(Key As String) As Boolean

### 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) 'Prints "3"
              myDict.Remove("key2")
              MsgBox(myDict.Count) 'Prints "2"

## RemoveAll

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

### Syntaxe:

              myDict.RemoveAll() As Boolean

### Příklad:

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

## ReplaceItem

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

### Syntaxe:

              myDict.ReplaceItem(Key As String, Value As Variant) As Boolean

### 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")) 'Prints "1"
              myDict.ReplaceItem("a", 100)
              MsgBox(myDict.Item("a")) ' Prints "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:

              myDict.ReplaceKey(Key As String, Value As String) As Boolean

### 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")) 'Prints "100"
              myDict.ReplaceKey("oldKey", "newKey")
              MsgBox(myDict.Item("newKey")) ' Prints "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.