ScriptForge.Dictionary tjeneste

Innhold
Innholdsliste 🔎︎

# ScriptForge.Ordbok tjeneste

En ordbok er en samling av nøkkelelementpar

- Nøkkelen er en streng som ikke skiller mellom store og små bokstaver

- Enheter kan være av hvilken som helst type

Nøkler og gjenstander kan hentes, telles, oppdateres og mye mer.

Ordbok-tjenesten ligner på det innebygde LibreOffice Basic Collection-objektet, men med flere funksjoner. For eksempel støtter ikke Collection-objekter henting av nøkler. I tillegg gir ordbøker ytterligere muligheter som å erstatte nøkler, teste om en spesifikk nøkkel allerede eksisterer og konvertere ordboken til et Array-objekt eller JSON-streng.

## Tjenestepåkallelse

##### I Basic

Følgende eksempel oppretter myDict som en tom ordbok.

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

Det anbefales å frigjøre ressurser etter bruk:

         Set myDict = myDict.Dispose()

##### I Python

Eksemplet nedenfor oppretter en tom forekomst av Dictionary-tjenesten og bruker Python native update-metoden for å fylle den med innholdet i et Python dict-objekt .

        dico = dict('A' = 1, 'B' = 2, 'C' = 3)
        # Initialiser myDict som et tomt dict-objekt
        myDict = CreateScriptService('Dictionary')
        # Last inn verdiene til dico i myDict
        myDict.update(dico)
        myDict['D'] = 4
        print(myDict)   # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
        propval = myDict.ConvertToPropertyValues()

Det er mulig å lage en forekomst av Dictionary-tjenesten ved å bruke et Python dict-objekt som argument som vist i følgende eksempel.

        dico = dict('A' = 1, 'B' = 2, 'C' = 3)
        # Initialiser myDict med innholdet i dico
        myDict = CreateScriptService('Dictionary', dico)
        myDict['D'] = 4
        print(myDict) # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
        propval = myDict.ConvertToPropertyValues()

Fordi Python har innebygd ordbokstøtte, er de fleste metodene i Ordbok-tjenesten kun tilgjengelig for grunnleggende skript. Unntak er ConvertToPropertyValues og ImportFromPropertyValues som støttes i både Basic og Python.

## Egenskaper

Navn | Skrivebeskyttet | Type | Beskrivelse
--- | --- | --- | ---
Count | Ja | Long | Antall oppføringer i ordboken
Items | Ja | En matrise med varianter | Listen over elementer som en endimensjonal matrise
Keys | Ja | En matrise med strenger | Listen over nøkler som en endimensjonal matrise

Egenskapene Keys og Items returnerer sitt respektive innhold, med identisk rekkefølge. Rekkefølgen er ikke relatert til opprettelsessekvensen.

### Eksempel:

Følgende eksempel bruker egenskapen Keys til å iterere over alle nøklene i ordboken myDict.

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

Liste over metoder i ordboktjenesten
Add ConvertToArray ConvertToJson ConvertToPropertyValues | Exists ImportFromJson ImportFromPropertyValues Item | Remove RemoveAll ReplaceItem ReplaceKey

## Add

Legger til et nytt nøkkelelementpar i ordboken. Returnerer True hvis vellykket.

### Syntaks:

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

### Parametre:

nøkkel: Strengverdi som brukes til å identifisere elementet. Nøkkelen skiller ikke mellom store og små bokstaver.

item: Enhver verdi, inkludert en matrise, et Basic-objekt, et UNO-objekt, en ordbok osv.

### Eksempel:

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

Hver nøkkel må være unik i samme ordbok. Hvis nøkkelen allerede finnes i ordboken, vises en DUPLICATEKEYERROR. Taster som er laget av mellomromstegn vil gi en INVALIDKEYERROR feil.

## ConvertToArray

Lagrer innholdet i ordboken i en nullbasert matrise med to kolonner. Nøklene lagres i den første kolonnen og elementene lagres i den andre kolonnen.

Hvis ordboken er tom, vil denne metoden returnere en tom Matrise.

### Syntaks:

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

### Eksempel:

          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

Konverterer innholdet i en ordbok til JSON (JavaScript Object Notation)-tekst.

### Begrensninger

Denne metoden støtter følgende datatyper: String, Boolean, tall, Null og Empty. Matriser som inneholder elementer av denne typen er også tillatt, uansett dimensjoner. Datoer konverteres til strenger, men de kan ikke brukes i Arrays. Andre datatyper konverteres til deres strengrepresentasjon ved å bruke SF_String.Represent-tjenesten.

### Syntaks:

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

### Parametre:

innrykk: Når innrykk er et positivt tall eller en tekst, er JSON-matriseelementer og objektmedlemmer ganske trykt med det innrykksnivået. En negativ innrykk verdi vil legge til nye linjer uten innrykk. Standardverdien er en tom streng "" som velger den mest kompakte representasjonen. Bruke et positivt heltall for innrykk innrykk så mange mellomrom per nivå. Når innrykk er en streng, for eksempel Chr(9) eller Tab(1), brukes Tab-tegnet til å rykke inn hvert nivå.

### Eksempel:

          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

Lagrer innholdet i ordboken i en matrise PropertyValues.

Hver oppføring i matrisen er en com.sun.star.beans.PropertyValue. Nøkkelen er lagret i Navn, elementet er lagret i Verdi.

Hvis en av elementene har en type Dato, konverteres den til en com.sun.star.util.DateTime struktur. Hvis ett av elementene er en tom matrise, konverteres den til Null. Den resulterende matrisen er tom når ordboken er tom.

### Syntaks:

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

### Eksempel:

##### I Basic

        Dim myDict as Variant
        myDict = CreateScriptService("Dictionary")
        'Legger til noen egenskaper i ordboken
        myDict.Add("Color", "Blue")
        myDict.Add("Width", 20)
        'Konverterer til en matrise med PropertyValue-objekter
        Dim prop as Variant
        prop = myDict.ConvertToPropertyValues()

##### I Python

Legg merke til i eksemplet nedenfor at en Python-ordbok må sendes som det andre argumentet for CreateScriptService-metoden.

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

Mange tjenester og metoder i UNO-biblioteket tar inn parametere representert ved hjelp av PropertyValue-strukturen, som er en del av LibreOffice API.

## Exists

Bestemmer om det finnes en nøkkel i ordboken.

### Syntaks:

dict.Exists(key: str): bool

### Parametre:

nøkkel: Nøkkelen som skal slås opp i ordboken.

### Eksempel:

        Dim myDict as Variant
        myDict = CreateScriptService("Dictionary")
        'Legger til noen egenskaper i ordboken
        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

Legger til innholdet i en JSON (JavaScript Object Notation)-streng i gjeldende ordbok. Returnerer Sann hvis vellykket.

### Begrensninger

JSON-strengen kan inneholde tall, tekst, booleaner, nullverdier og matriser som inneholder disse typene. Den må ikke inneholde JSON-objekter, nemlig underordbøker.

Det gjøres et forsøk på å konvertere tekst til dato hvis elementet samsvarer med ett av disse mønstrene: ÅÅÅÅ-MM-DD, TT:MM:SS eller ÅÅÅÅ-MM-DD TT:MM:SS.

### Syntaks:

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

### Parametre:

inputstr: Strengen som skal importeres.

overskriv: Når Sann, kan oppføringer med samme navn finnes i ordboken og verdiene deres overskrives. Når Usann (standard), vil gjentatte taster gi en feilmelding. Vær oppmerksom på at ordboknøkler ikke skiller mellom store og små bokstaver, mens navn skiller mellom store og små bokstaver i JSON-strenger.

### Eksempel:

        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)
        '(under)-ordbøkene "adresse" og "telefonnumre" (0) og (1) importeres som tomme verdier.

## ImportFromPropertyValues

Setter inn innholdet i en rekke PropertyValue-objekter i gjeldende ordbok. PropertyValue Navn brukes som nøkler i ordboken, mens verdier inneholder de tilsvarende verdiene. Returnerer Sann hvis vellykket.

### Syntaks:

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

### Parametre:

propertyvalues: En nullbasert 1-dimensjonal matrise som inneholder com.sun.star.beans.PropertyValue objekter. Denne parameteren kan også være et enkelt PropertyValue-objekt som ikke finnes i en matrise.

overskriv: Når True, kan oppføringer med samme navn finnes i ordboken og verdiene deres overskrives. Når False (standard), vil gjentatte taster gi en feilmelding. Merk at ordboknøkler ikke skiller mellom store og små bokstaver i Basic, mens navn skiller mellom store og små bokstaver i sett med egenskapsverdier og i Python-ordbøker.

### Eksempel:

Eksemplene nedenfor oppretter først en matrise med to PropertyValue-objekter og konverterer den deretter til en ordbok.

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

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

Henter en eksisterende ordbokoppføring basert på nøkkelen. Returnerer verdien av elementet hvis det lykkes, ellers returnerer Tom.

### Syntaks:

dict.Item(key: str): any

### Parametre:

nøkkel: Skiller ikke mellom store og små bokstaver. Hvis den ikke eksisterer, returneres verdien Tom.

### Eksempel:

Følgende eksempel itererer over alle nøklene i ordboken og bruker Element-metoden for å få tilgang til verdiene deres.

        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

Fjerner en eksisterende ordbokoppføring basert på nøkkelen. Returnerer Sann hvis vellykket.

### Syntaks:

dict.Remove(key: str): bool

### Parametre:

nøkkel: Skiller ikke mellom store og små bokstaver. Må finnes i ordboken, ellers oppstår en UNKNOWNKEYERROR feil.

### Eksempel:

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

## RemoveAll

Fjerner alle oppføringene fra ordboken. Returnerer Sann hvis vellykket.

### Syntaks:

dict.RemoveAll(): bool

### Eksempel:

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

## ReplaceItem

Erstatter en eksisterende vareverdi basert på nøkkelen. Returnerer Sann hvis vellykket.

### Syntaks:

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

### Parametre:

nøkkel: Strengverdi som representerer nøkkelen hvis verdi vil bli erstattet. Ikke skille mellom store og små bokstaver. Hvis nøkkelen ikke finnes i ordboken, vises en UNKNOWNKEYERROR feil.

verdi: Den nye verdien til elementet det refereres til med nøkkel parameteret.

### Eksempel:

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

## ReplaceKey

Erstatter en eksisterende nøkkel i ordboken med en ny nøkkel. Vareverdien forblir uendret. Returnerer Sann hvis vellykket.

### Syntaks:

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

### Parametre:

nøkkel: Strengverdi som representerer nøkkelen som skal erstattes. Ikke skille mellom store og små bokstaver. Hvis nøkkelen ikke finnes i ordboken, vises en UNKNOWNKEYERROR feil.

verdi: Strengverdi for den nye nøkkelen. Ikke skille mellom store og små bokstaver. Hvis den nye nøkkelen allerede finnes i ordboken, vises en DUPLICATEKEYERROR feil.

### Eksempel:

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

Alle ScriptForge Grunnleggende rutiner eller identifikatorer som er prefikset med et understrekingstegn "_" er reservert for intern bruk. De er ikke ment å brukes i grunnleggende makroer eller Python-skript.

Lignende emner

ScriptForge.Matrise tjeneste

Samlingsobjekt