Služba ScriptForge.Dictionary

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

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

Ikona tipu

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

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.


Ikona tipu

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:

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

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

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

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
  
warning

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.


Podpořte nás!