Wobsah

# Słužba ScriptForge.Dictionary

Słownik je zběrka porow klučowych zapiskow.

- Kluč je znamješkowy rjećazk. W skriptach Basic so wulko- resp. małopisanje při wutworjenju słownika postaja. W skriptach Python kluč přeco na wulko-/małopisanje dźiwa.

- Zapiski móža kóždy typ měć

Kluče a zapiski dadźa so wotwołać, ličić, aktualizować a wjele wjace.

Słužba Dictionary je podobna na zatwarjeny objekt Collection LibreOfficeDev Basic, ale z wjace funkcijemi. Objekty Collection na přikład wotwołanje klučowa njepodpěruja. Nimo toho słowniki přidatne móžnosće skića, na přikład wuměnjenje klučow, testowanje, hač wěsty kluč hižo eksistuje a přetworjenje słownika do matriksy PropertyValues abo znamješkoweho rjećazka JSON.

## Słužbowe wuwołanje

##### W Basic

Slědowacy přikład myDict jako prózdny słownik wutworja.

        GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
        Dim myDict As Variant
        myDict = CreateScriptService("Dictionary", True)
                    ' Kluče na wulko- a małopisanje dźiwaja, tohodla je True druhi argument

Poruča so, resursy po wužiwanju wuswobodźić:

         Set myDict = myDict.Dispose()

##### W Python

Slědowacy přikład prózdnu instancu słužby dictionary wutworja a wužiwa natiwnu metodu Python update, zo by ju z wobsahom objekta Python dict pjelnił.

        dico = dict('A' = 1, 'B' = 2, 'C' = 3)
        # myDict jako prózdny objekt Dictionary inicializěrować
        myDict = CreateScriptService('Dictionary')
        # Hódnoty dico do myDict začitać
        myDict.update(dico)
        myDict['D'] = 4
        print(myDict)   # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
        propval = myDict.ConvertToPropertyValues()

Je móžno, instancu słužby Dictionary z pomocu objekta Python dict jako argument wutworić, kaž to so w slědowacym přikładźe pokazuje.

        dico = dict('A' = 1, 'B' = 2, 'C' = 3)
        # myDict z wobsahom dico inicializěrować
        myDict = CreateScriptService('Dictionary', dico)
        myDict['D'] = 4
        print(myDict) # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
        propval = myDict.ConvertToPropertyValues()

Dokelž Python ma zatwarjeny słownikowu podpěru, je najwjace metodow w słužbje Dictionary jenož za skripty Basic k dispoziciji. Wuwzaća su metodźe ConvertToPropertyValues a ImportFromPropertyValues, kotrejž so w Basic kaž tež Python podpěrujetej.

## Kajkosće

Mjeno | Přećiwo pisanju škitany | Typ | Wopisanje
--- | --- | --- | ---
Count | Haj | Long | Ličba zapiskow w słowniku
Items | Haj | Matriks z Variants | Lisćina zapiskow jako jednodimensionalna matriks
Keys | Haj | Matriks ze znamješkowymi rjećazkami | Lisćina klučow jako jednodimensionalna matriks.

Kajkosći Keys a Items swój daty wobsah z identiskim porjadom wróćatej. Porjad so na wutworjenski porjad njepoćahuje.

### Přikład:

Slědowacy přikład kajkosć Keys wužiwa, zo by wšě kluče w słowniku myDict přeběžała.

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

Lisćina metodow w słužbje Dictionary
Add ConvertToArray ConvertToJson ConvertToPropertyValues | Exists ImportFromJson ImportFromPropertyValues Item | Remove RemoveAll ReplaceItem ReplaceKey

## Add

Přidawa słownikej por klučowych zapiskow. Wróći True, jeli je wuspěšna.

### Syntaksa:

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

### Parametry:

key: Hódnota znamješkoweho rjećazka, kotraž so wužiwa, zo by zapisk identifikowała. Wulko-/małopisanje kluča so při wutworjenju słownika postaja.

item: Někajka hódnota, kotraž matriks, objekt Basic, objekt UNO, słownik atd. wobsahuje

### Přikład:

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

Kóždy kluč dyrbi w samsnym słowniku jónkróćny być. Jeli kluč hižo w słowniku eksistuje, so DUPLICATEKEYERROR wuwabi. Kluče, kotrež z mjezotow wobsteju, zmylk INVALIDKEYERROR wuwabjeja.

## ConvertToArray

Składuje wobsah słownika w dwušpaltowej na nulu bazowacej matriksy. Kluče so w prěnjej špalće składuja a zapiski so w druhej špalće składuja.

Jeli słownik je prózdny, tuta metoda prózdnu matriks wróći.

### Syntaksa:

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

### Přikład:

          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řetworja wobsah słownika do teksta JSON (Javascript Object Notation).

### Wobmjezowanja

Tuta metoda slědowace datowe typy podpěruje: String, Boolean, numbers, Null a Empty. Matriksy, kotrež zapiski tutych typow wobsahuja, su tež dowolene, njewotwisujo wot jich wotměrow. Datum so do znamješkowy rjećazk přetworja, njeda so wšak w matriksach wužiwać. Druhe datowe typy so z pomocu słužby SF_String.Represent do wotpowědnych znamješkowych rjećazkow přetworjeja.

### Syntaksa:

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

### Parametry:

indent: Hdyž indent je pozitiwna ličba abo tekst, matriksowe elementy JSON a objektowe čłony so z tutej zasuwanskej runinu so rjenje ćišća. Negatiwna hódnota indent negatiwne linki bjez zasunjenja přidawa. Standardna hódnota je prózdny znamješkowy rjećazk "", kotryž najkompaktnišu reprezentaciju wuběra. Wužiwanje pozitiwneje cyłeje ličby za indent wo wjele mjezotow zasuwa. Hdyž indent je znamješkowy rjećazk, na přikład Chr(9) abo Tab(1), so tabulatorowe znamješko ↹ wužiwa, zo by so kóžda runina zasunyła.

### Přikład:

          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

Składuje wobsah słownika do matriksy PropertyValues.

Kóždy zapisk w matriksy je com.sun.star.beans.PropertyValue. Kluč so w Name składuje, so zapisk w Value składuje.

Jeli jedyn ze zapiskow ma typ Date, přetworja so do struktury com.sun.star.util.DateTime. Jeli jedyn ze zapiskow je prózdny matriks, přetworja so do Null. Rezultowaca matriks je prózdna, hdyž słownik je prózdny.

### Syntaksa:

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

### Přikład:

##### W Basic

        Dim myDict as Variant
        myDict = CreateScriptService("Dictionary")
        ' Přidawa słownikej kajkosće
        myDict.Add("Color", "Blue")
        myDict.Add("Width", 20)
        ' Přetworja do matriksy objektow PropertyValue
        Dim prop as Variant
        prop = myDict.ConvertToPropertyValues()

##### W Python

Dźiwajće w slědowacym přikładźe na to, zo słownik Python dyrbi so jako druhi argument metody CreateScriptService přepodać.

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

Wjele słužbow a metodow w bibliotece UNO parametry přijimaja, kotrež so z pomocu struct PropertyValue reprezentuja, štož je dźěl API LibreOfficeDev.

## Exists

Postaja, hač kluč w słowniku eksistuje.

### Syntaksa:

dict.Exists(key: str): bool

### Parametry:

key: Kluč, za kotrymž so ma w słowniku pytać.

### Přikład:

        Dim myDict as Variant
        myDict = CreateScriptService("Dictionary")
        ' Přidawa słownikej někotre kajkosće
        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řidawa aktualnemu słownikej wobsah znamješkoweho rjećazka JSON (JavaScript Object Notation). Wróći True, jeli je wuspěšna.

### Wobmjezowanja

Znamješkowy rjećazk JSON móže ličby, tekst, logiske hódnoty (boolean), nulowe hódnoty a matriksy wobsahuje, kotrež tute typy wobsahuja. Njesměje objekty JSON wobsahować, mjenujcy podsłowniki.

Pospytuje so, tekst do datuma přetworić, jeli zapisk jednomu z tutych mustrow wotpowěduje: LLLL-MM-DD, HH:MM:SS abo LLLL-MM-DD HH:MM:SS.

### Syntaksa:

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

### Parametry:

inputstr: Znamješkowy rjećazk, kotryž so ma importować.

overwrite: Hdyž True, móža zapiski ze samsnym mjenom w słowniku eksistować a jich hódnoty so přepisuja. Hdyž False (standard), wospjetowane kluče zmylk wuwabjeja. Dźiwajće na to, zo słownikowe kluče na wulkopisanje njedźiwaja, mjeztym zo mjena w znamješkowych rjećazkach na wulkopisanje dźiwaja.

### Přikład:

        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)
        ' Podsłownikaj "adresa" a "Telefonowe čisła" (0) a (1) so jako prózdnej hódnoće importujetej.

## ImportFromPropertyValues

Zasadźuje wobsah matriksy objektow PropertyValue do aktualneho słownika. Mjena PropertyValue so jako kluče w słowniku wužiwaja, mjeztym zo Hódnoty wotpowědne hódnoty wobsahuja. Wróći True, jeli je wuspěšna.

### Syntaksa:

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

### Parametry:

propertyvalues: Na nuli bazowaca jednodimensionalna matriks, kotraž objekty com.sun.star.beans.PropertyValue wobsahuje. Tutón parameter móže tež jednotliwy objekt PropertyValue być, kotryž w matriksy wobsahowany njeje.

overwrite: Hdyž True, móža zapiski ze samsnym mjenom w słowniku eksistować a jich hódnoty so přepisuja. Hdyž False (standard), wospjetowane kluče zmylk wuwabjeja. Dźiwajće na to, zo słownikowe kluče na wulkopisanje w Basic njedźiwaja, mjeztym zo mjena w sadźbach kajkostnych hódnotow a w słownikach Python na wulkopisanje dźiwaja.

### Přikład:

Slědowace přikłady najprjedy matriks z dwěmaj objektomaj PropertyValue wutworjeja a přetworjeja potom do słownika.

##### W Basic

        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

##### W Python

        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

Wotwołuje eksistowacy słownikowy zapisk, kotryž na jeho kluču bazuje. Wróći hódnotu zapiski, hdyž je wuspěšna, hewak Empty.

### Syntaksa:

dict.Item(key: str): any

### Parametry:

key: Jeli njeeksistuje, so hódnota Empty wróći.

### Přikład:

Slědowacy přikład wšě kluče w słowniku přeběži a wužiwa metodu Item, zo by přistup k jich hódnotam dóstał.

        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

Wotstronja eksistowacy słownikowy zapisk, kotryž na swój kluč bazuje. Wróći True, jeli je wuspěšna.

### Syntaksa:

dict.Remove(key: str): bool

### Parametry:

key: Dyrbi w słowniku eksistować, hewak so zmylk UNKNOWNKEYERROR wuwabi.

### Přikład:

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

## RemoveAll

Wotstronja wšě zapiski ze słownika. Wróći True, jeli je wuspěšna.

### Syntaksa:

dict.RemoveAll(): bool

### Přikład:

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

## ReplaceItem

Wuměni eksistowacy zapisk, na jeho kluč bazowacy. Wróći True, jeli je wuspěšna.

### Syntaksa:

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

### Parametry:

key: Hódnota znamješkoweho rjećazka, kotraž kluč reprezentuje, kotrehož hódnota so wuměni. Jeli kluč w słowniku njeeksistuje, so zmylk UNKNOWNKEYERROR wuwabi.

value: Nowa hódnota zapiska, na kotryž so z parametrom key wotkazuje.

### Přikład:

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

## ReplaceKey

Wuměni eksistowacy kluč w słowniku přez nowy kluč. Zapiskowa hódnota njezměnjena wostawa. Wróći True, jeli je wuspěšna.

### Syntaksa:

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

### Parametry:

key: Hódnota znamješkoweho rjećazka, kotraž kluč reprezentuje, kotryž so ma wuměnić. Jeli kluč w słowniku njeeksistuje, so zmylk UNKNOWNKEYERROR wuwabi.

value: Hódnota znamješkoweho rjećazka za nowy kluč. Jeli nowy kluč w słowniku hižo eksistuje, so zmylk DUPLICATEKEYERROR wuwabi.

### Přikład:

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

Wšě rutiny Basic ScriptForge abo identifikatory, kotrež so z podsmužku „_“ započinaja, su za interne wužiwanje wuměnjene. Njejsu za to myslene, so w makrach Basic abo skriptach Python wužiwać.

Podobne temy

Słužba ScriptForge.Array

Collection Object

Prošu podpěrajće nas!