Nápověda LibreOffice 24.8
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.
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 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.
| 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.
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 | ||
|---|---|---|
Přidá do slovníku novou dvojici klíč-položka. V případě úspěšného přidání vrátí True.
dict.Add(key: str, item: any): bool
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.
      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.
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).
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))
    Převede obsah slovníku na text formátu JSON (JavaScript Object Notation).
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.
dict.ConvertToJson(indent: str = ""): str
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.
      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]}
    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.
dict.ConvertToPropertyValues(): obj[0..*]
    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 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.
Určuje, zda klíč ve slovníku existuje.
dict.Exists(key: str): bool
key: Klíč, který se má ve slovníku vyhledat.
    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
  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.
Ř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.
dict.ImportFromJson(inputstr: str, overwrite: bool = False): bool
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.
    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.
  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.
dict.ImportFromPropertyValues(propertyvalues: obj[0..*], overwrite: bool = False): bool
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.
V následujícím příkladu se nejprve vytvoří pole se dvěma objekty PropertyValue a poté se převede na slovník.
    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]))
  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.
dict.Item(key: str): any
key: Nerozlišuje se u něj velikost písmen. Pokud neexistuje, vrátí se hodnota Empty.
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
  Odstraní pro zadaný klíč existující záznam slovníku. V případě úspěšného odstranění vrátí True.
dict.Remove(key: str): bool
key: Nerozlišuje se u něj velikost písmen. Pokud ve slovníku neexistuje, nastane chyba UNKNOWNKEYERROR.
    myDict.Add("key1", 100)
    myDict.Add("key2", 200)
    myDict.Add("key3", 300)
    MsgBox(myDict.Count) ' 3
    myDict.Remove("key2")
    MsgBox(myDict.Count) ' 2
  Odstraní ze slovníku všechny záznamy. V případě úspěšného odstranění vrátí True.
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
  Nahradí pro zadaný klíč hodnotu existující položky slovníku. V případě úspěšného nahrazení vrátí True.
dict.ReplaceItem(key: str, value: any): bool
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.
    myDict.Add("a", 1)
    MsgBox(myDict.Item("a")) ' 1
    myDict.ReplaceItem("a", 100)
    MsgBox(myDict.Item("a")) ' 100
  Nahradí existující klíč slovníku jiným. Hodnota položky se nezmění. V případě úspěšného nahrazení vrátí True.
dict.ReplaceKey(key: str, value: str): bool
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.
    myDict.Add("oldKey", 100)
    MsgBox(myDict.Item("oldKey")) ' 100
    myDict.ReplaceKey("oldKey", "newKey")
    MsgBox(myDict.Item("newKey")) ' 100