Vsebina

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

Podobne teme

Storitev ScriptForge.Array

Predmet Collection