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

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.


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:


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


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


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