Słužba ScriptForge.Dictionary

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

• Kluč je znamješkowy rjećazk, kotryž na wulkopisanje 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 na zatwarjeny objekt LibreOffice Basic Collection podobna, ale z wjace funkcijemi. Objekty Collection na přikład wotwołanje klučow njepodpěruja. Nimo toho słowniki přidatne funkcije kaž wuměnjenje klučow, testowanje, hač wěsty kluč hižo eksistuje a přetworjenje słownika do matriksoweho objekta abo do znamješkoweho rjećazka JSON skića.

Słužbowe wuwołanje

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

    GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
    Dim myDict As Variant
    myDict = CreateScriptService("Dictionary", True)
                ' The keys are case-sensitive, hence the second argument is True
 

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

     Set myDict = myDict.Dispose()
  

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 dict 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 zatwarjenu słownikowu podpěru, je najwjace metodow w słužbje Dictionary jenož za skripty Basic k dispoziciji. Wuwzaća su ConvertToPropertyValues a ImportFromPropertyValues, kotrejž so w Basic kaž tež w Python podpěrujetej.

Kajkosće

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

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
    

Add

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

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

Key: Hódnota znamješkoweho rjećazka, kotraž so wužiwa, zo by zapisk identifikowała. Kluč na wulkopisanje njedźiwa.

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

      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.

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

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.

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

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.

      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.

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

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

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

Exists

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

dict.Exists(key: str): bool

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

    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.

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

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.

    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.

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

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.

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

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

Item

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

dict.Item(key: str): any

key: Njedźiwa na wulkopisanje. Jeli njeeksistuje, so hódnota Empty wróći.

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.

dict.Remove(key: str): bool

key: Njedźiwa na wulkopisanje. Dyrbi w słowniku eksistować, hewak so zmylk UNKNOWNERROR wuwabi.

    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.

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
  

ReplaceItem

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

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

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

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

    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.

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

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č. Njedźiwa na wulkopisanje. Jeli nowy kluč hižo w słowniku eksistuje, so zmylk DUPLICATEKEYERROR wuwabi.

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