Storitev ScriptForge.Dictionary

Slovar je zbirka parov ključ-element

Ključ je niz, pri katerem razlike med velikimi in malimi črkami ne štejejo
Elementi so lahko poljubne vrste

Ključe in elemente lahko pridobimo, štejemo, posodobimo in še veliko več.

Storitev Dictionary je podobna vgrajenemu predmetu LibreOffice Basic Collection, vendar z več funkcionalnostmi. Primer: predmeti Collection ne podpirajo pridobivanja ključev. Še več, predmeti Dictionary ponujajo dodatne zmožnosti, kot je zamenjava ključev, preizkušanje, če določen ključ že obstaja, ter pretvorbo predmeta Dictionary v predmet Array ali niz JSON.

Priklic storitve

V Basicu

Naslednji primer ustvari myDict kot prazen slovar.


    GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
    Dim myDict As Variant
    myDict = CreateScriptService("Dictionary")

Priporočamo, da po uporabi sprostite vire:


     Set myDict = myDict.Dispose()

V Pythonu

Spodnji primer ustvari prazno instanco storitve Dictionary in uporablja domorodno metodo Python update, da ga napolni z vsebino predmeta Python dict.


    dico = dict('A' = 1, 'B' = 2, 'C' = 3)
    # Inicializiraj myDict prazen predmet dict
    myDict = CreateScriptService('Dictionary')
    # Naloži vrednosti dico v myDict
    myDict.update(dico)
    myDict['D'] = 4
    print(myDict)   # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
    propval = myDict.ConvertToPropertyValues()

Instanco storitve Dictionary lahko tvorite tudi s predmetom Python dict kot argumentom, kar prikazuje naslednji primer.


    dico = dict('A' = 1, 'B' = 2, 'C' = 3)
    # Inicializiraj myDict z vsebino predmeta dico
    myDict = CreateScriptService('Dictionary', dico)
    myDict['D'] = 4
    print(myDict) # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
    propval = myDict.ConvertToPropertyValues()

Python ima vgrajeno podporo za slovarje, zato je večina metod v storitvi Dictionary na voljo le za skripte Basic. Izjemi sta ConvertToPropertyValues in ImportFromPropertyValues, ki sta podprti v Basicu in Pythonu.

Lastnosti

Ime	Samo za branje	Vrsta	Opis
Count	Da	Long	Število vnosov v slovarju
Items	Da	Polje spremenljivk Variant	Seznam elementov kot enodimenzionalno polje
Keys	Da	Polje nizov	Seznam ključev kot enodimenzionalno polje

Lastnosti Keys (angl. ključi) in Items (angl. elementi) vrneta ustrezno vsebino, pri čemer uporabljata identično razvrstitev. Zaporedje ni odvisno od zaporedja ustvarjanja.

Primer:

Naslednji primer uporablja lastnost Keys, da gre po vseh ključih v slovarju myDict.


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

Seznam metod v storitvi Dictionary
Add ConvertToArray ConvertToJson ConvertToPropertyValues	Exists ImportFromJson ImportFromPropertyValues Item	Remove RemoveAll ReplaceItem ReplaceKey

Add

V slovar doda nov par ključ-element. Vrne True, če uspe.

Skladnja:

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

Parametri:

key: niz, s katerim boste identificirali element. Pri ključu razlike med velikimi in malimi črkami niso upoštevane.

item: poljubna vrednost, vključno s poljem, predmetom Basic, predmetom UNO, slovarjem itn.

Primer:


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

Vsak ključ mora biti edinstven v danem slovarju. Če v slovarju ključ že obstaja, prikliče napako DUPLICATEKEYERROR. Ključi s presledki prikličejo napako INVALIDKEYERROR.

ConvertToArray

Shrani vsebino slovarja v polje dveh stolpcev na osnovi ničel. Ključi so shranjeni v prvem stolpcu, v drugem stolpcu pa elementi.

Če je slovar prazen, ta metoda vrne prazno polje, Array.

Skladnja:

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

Primer:


      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

Pretvori vsebino slovarja v besedilo JSON (angl. JavaScript Object Notation).

Omejitve

Ta metoda podpira naslednje vrste podatkov: String, Boolean, numbers, Null in Empty. Dovoljena so tudi polja, ki vsebujejo elemente teh vrst, ne glede na njihove mere. Datumi so pretvorjeni v nize, ne morejo pa biti uporabljeni v poljih. Druge vrste podatkov so pretvorjene v njihovo reprezentacijo nizov z uporabo storitve SF_String.Represent.

Skladnja:

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

Parametri:

indent: če je indent pozitivno število ali besedilo, so elementi polja in člani predmeta JSON ozaljšano izpisani z ustrezno ravnjo zamika. Negativna vrednost indent doda nove vrstice brez zamika. Privzeta vrednost je prazen niz "", ki izbere najbolj strnjeno predstavitev. S pozitivnim celim številom za indent zamakne vsebino za toliko presledkov na raven. Če je indent niz, kot sta Chr(9) in Tab(1), se znak tabulatorja uporablja za zamik vsake ravni.

Primer:


      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

Shrani vsebino slovarja v polje vrednosti PropertyValues.

Vsak vnos v polju je com.sun.star.beans.PropertyValue. Ključ je shranjen v Name, element je shranjen v Value.

Če je eden od elementov vrste Date, se pretvori v strukturo com.sun.star.util.DateTime. Če je eden od elementov prazno polje, je pretvorjeno v Null. Če je slovar prazen, je rezultat prazno polje.

Skladnja:

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

Primer:

V Basicu


    Dim myDict as Variant
    myDict = CreateScriptService("Dictionary")
    'V slovar doda nekatere lastnosti
    myDict.Add("Color", "Blue")
    myDict.Add("Width", 20)
    'Pretvori v matriko predmetov PropertyValue
    Dim prop as Variant
    prop = myDict.ConvertToPropertyValues()

V Pythonu

Iz spodnjega primera je razvidno, da mora biti slovar Python podan kot drugi argument metode CreateScriptService.


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

Številne storitve in metode knjižnice UNO jemljejo za parametre, predstavljene s strukturo PropertyValue, ki je del API LibreOffice.

Exists

Ugotovi, ali ključ v slovarju obstaja.

Skladnja:

dict.Exists(key: str): bool

Parametri:

key: ključ, ki bo poiskan v slovarju.

Primer:


    Dim myDict as Variant
    myDict = CreateScriptService("Dictionary")
    'V slovar doda nekatere lastnosti
    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

Doda vsebino niza JSON (JavaScript Object Notation) v trenutni slovar. Vrne True, če uspe.

Omejitve

Niz JSON lahko vsebuje števila, besedilo, logične vrednosti, ničelne vrednosti (null) in polja, ki vsebujejo te vrste podatkov. Ne sme vsebovati predmetov JSON in sicer podslovarjev.

Izvede se poskus pretvorbe besedila v datum, če element ustreza enemu od naslednjih vzorcev: LLLL-MM-DD, HH:MM:SS ali LLLL-MM-DD HH:MM:SS.

Skladnja:

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

Parametri:

inputstr: niz, ki ga želite uvoziti.

overwrite: če je True, lahko v slovarju obstajajo istoimenski vnosi in njihove vrednosti bodo prepisane. Če je False (privzeto), ponovljeni ključi povzročijo napako. Upoštevajte, da pri ključih slovarja razlike med velikimi in malimi črkami ne štejejo, medtem ko ta razlika velja med imeni v množicah vrednosti lastnosti.

Primer:


    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)
    '(pod)slovarji "address" in "phoneNumbers" (0) in (1) se uvozijo kot vrednosti Empty.

ImportFromPropertyValues

Vstavi vsebino polja predmetov PropertyValue v trenutni slovar. Imena PropertyValue se uporabijo kot ključi (Keys) v slovarju, medtem ko Values vsebujejo ujemajoče vrednosti. Vrne True, če uspe.

Skladnja:

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

Parametri:

propertyvalues: ničelno enodimenzionalno polje, ki vsebuje predmete com.sun.star.beans.PropertyValue. Ta parameter je lahko tudi posamičen predmet PropertyValue, ki ni vsebovan v polju.

overwrite: če je True, lahko v slovarju obstajajo istoimenski vnosi in njihove vrednosti bodo prepisane. Če je False (privzeto), ponovljeni ključi povzročijo napako. Upoštevajte, da ključi slovarja v Basicu ne razlikujejo med velikimi in malimi črkami, medtem ko ta razlika med imeni velja v množicah vrednosti lastnosti ter v slovarjih v Pythonu.

Primer:

V spodnjih primerih najprej ustvarimo polje z dvema predmetoma PropertyValue in ga nato pretvorimo v slovar.

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

Pridobi obstoječi vnos slovarja glede na njegov ključ. Vrne vrednost elementa, če uspe, sicer vrne Empty (angl. prazno).

Skladnja:

dict.Item(key: str): any

Parametri:

key: ne razlikuje med velikimi in malimi črkami. Če ne obstaja, vrne vrednost Empty.

Primer:

Naslednji primer gre po vseh ključih v slovarju in uporablja metodo Item za dostop do njihovih vrednosti.


    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

Odstrani obstoječi vnos slovarja glede na njegov ključ. Vrne True, če uspe.

Skladnja:

dict.Remove(key: str): bool

Parametri:

key: ne razlikuje med velikimi in malimi črkami. Mora obstajati v slovarju, sicer javi napako UNKNOWNKEYERROR.

Primer:


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

RemoveAll

Odstrani vse vnose iz slovarja. Vrne True, če uspe.

Skladnja:

dict.RemoveAll(): bool

Primer:


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

ReplaceItem

Zamenja vrednost obstoječega elementa glede na njegov ključ. Vrne True, če uspe.

Skladnja:

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

Parametri:

key: niz, ki predstavlja ključ, katerega vrednost bo zamenjana. Razlike med velikimi in malimi črkami niso upoštevane. Če ključ ne obstaja v slovarju, prikliče napako UNKNOWNKEYERROR.

value: nova vrednost elementa, na katerega se sklicuje parameter key.

Primer:


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

ReplaceKey

Zamenja obstoječi ključ v slovarju z novim ključem. Vrednost elementa ostane nespremenjena. Vrne True, če uspe.

Skladnja:

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

Parametri:

key: niz, ki predstavlja ključ, ki bo zamenjan. Razlike med velikimi in malimi črkami niso upoštevane. Če ključ ne obstaja v slovarju, prikliče napako UNKNOWNKEYERROR.

value: niz, ki predstavlja vrednost za novi ključ. Razlike med velikimi in malimi črkami niso upoštevane. Če novi ključ že obstaja v slovarju, prikliče napako DUPLICATEKEYERROR.

Primer:


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

Vsi podprogrami ali identifikatorji ScriptForge Basic s predpono podčrtaja (»_«) so rezervirani za interno uporabo. Uporabi v makrih Basic ali skriptih Python niso namenjeni.

Storitev ScriptForge.Array

Predmet Collection