Tjenesten ScriptForge.Dictionary

Indhold

# Tjenesten ScriptForge.Ordbog

En ordbog er samling af nøgle-element-par

- Nøglen er en streng, der ikke skelner mellem Store og små bogstaver

- Elementer kan være af enhver type

Nøgler og elementer kan hentes, tælles, opdateres og meget mere.

Tjenesten Dictionary (ordliste) ligner det indbyggede LibreOffice Basic-objekt Collection (Samling), men har flere funktionaliteter. For eksempel understøtter Collection (Samling)-objekter ikke genoprettelse af nøgler- Desuden leverer Dictionaries (Ordlister) yderligere kapaciteter som erstatning af nøgler, test af, om en angiven nøgle allerede findes og konvertering af Dictionary (ordlisten) til et matrix-objekt eller en JSON-streng.

## Kald af tjeneste

##### I Basic

Det følgende eksempel opretter myDict som en tom ordbog.

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

Det anbefales at frigøre ressourcer efter brug:

         Set myDict = myDict.Dispose()

##### I Python

Eksemplet herunder opretter et tomt eksemplar af tjenesten Dictionary (ordbog) og bruger Pythons medfødte metode update (opdater) til at fylde den med indholdet af Python-objektet dict (ordliste).

        dico = dict('A' = 1, 'B' = 2, 'C' = 3)
        # Initialiser myDict som et tomt ordliste-objekt
        myDict = CreateScriptService('Dictionary')
        # Indlæs dico's værdier i myDict
        myDict.update(dico)
        myDict['D'] = 4
        print(myDict)   # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
        propval = myDict.ConvertToPropertyValues()

Det er muligt at oprette et eksemplar af tjenesten Dictionary (ordliste) med Python-objektet dict som argument som vist i det følgende eksempel.

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

Fordi Python har indbygget understøttelse af ordliste, er de fleste af metoderne i tjenesten Dictionary udelukkende tilgængelige for Basic-scripts. Undtagelser er ConvertToPropertyValues og ImportFromPropertyValues, der understøttes i både Basic og Python.

## Egenskaber

Navn | Skrivebeskyttet | Type | Beskrivelse
--- | --- | --- | ---
Count | Ja | Long | Antallet af indførsler i ordbogen
Items | Ja | Matrix af varianter | Listen over elementer som en en-dimensinel matrix
Keys | Ja | Matrix af strenge | Listen over nøgler som en en-dimensionel matrix

Egenskaberne Keys og Items returnerer deres respektive indhold, i en identisk rækkefølge. Rækkefølgen er ikke relateret til oprettelsesrækkefølgen.

### Eksempel:

Det følgende eksempel bruger egenskaben Keys til flere gange at gennemgå alle nøglerne i myDict.

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

List of Methods in the Dictionary Service
Add ConvertToArray ConvertToJson ConvertToPropertyValues | Exists ImportFromJson ImportFromPropertyValues Item | Remove RemoveAll ReplaceItem ReplaceKey

## Add

Tilføjer et nyt nøgle-element-par til ordbogen. Returnerer True, hvis det lykkes.

### Syntaks:

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

### Parametre:

nøgle: Strengværdier bruges til identificere elementet. Nøglen er ikke Stort-og-småt.

element: Enhver værdi, herunder en matrix, et Basic-objekt, en ordliste og så videre.

### Eksempel:

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

Hver nøgle i den samme ordbog skal være unik. Hvis, nøglen allerede eksisterer i ordbogen, sættes der et , DUPLICATEKEYERROR-flag. Nøgler, der udgøres af mellemrumstegn, sætter et INVALIDKEYERROR-flag.

## ConvertToArray

Gemmer indholder ordbogens indhold i en to-kolonners, nul-baseret matrix.Nøglerne er gemt i den første kolonne og elementerne gemmes i den anden kolonne.

Hvis ordbogen er tom, returnerer denne metode en tom Array (matrix).

### 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 ordbogens indhold til tekst i JSON (JavaScript Object Notation).

### Begrænsninger

Denne metode understøtter følgende datatyper: String, Boolean, numbers, Null and Empty. Matrixer, der indeholder elementer af disse er også tilladt, uanset deres dimensioner. Datoer er konverteret til strenge, der bruges inden for matrixerne. Andre datatyper konverteres til deres repræsentation til strenge ved hjælp af tjenesten SF_String.Represent.

### Syntaks:

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

### Parametre:

indrykning: når indent (indrykning) er et positivt tal eller en tekst. JSON-matrixelementer og objekt-elementer fintrykkes med dette indrykningsniveau. En negativ indents-værdi tilføjer nye linjer uden nogen indrykning. Standardværdien er en tom streng "", som vælger den mest kompakte repræsentation. Anvendelse af et positivt heltal i indent indrykkes så mange mellemrum pr. niveau. Når indent er en streng, som for eksempel Chr(9) eller Tab(1), bruges Tabulatortegnet til at indrykke hvert niveau.

### 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 ordlistens indhold i en matrix med PropertyValues (egenskabsværdier).

Hver indførsel er en com.sun.star.beans.PropertyValue. Nøglen gemmes i Name, elementet i Value.

Hvis et af elementerne har en type, Dato, konverteres den til strukturen com.sun.star.util.DateTime. Hvis et af elementerne er en tomt matrix, konverteres det til Null. Den resulterende matrix er tom, når ordbogen er tom.

### Syntaks:

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

### Eksempel:

##### I Basic

        Dim myDict as Variant
        myDict = CreateScriptService("Dictionary")
        'Tilføjer nogle egenskaber til ordbogen
        myDict.Add("Color", "Blue")
        myDict.Add("Width", 20)
        'Konverterer til en matrix af objekterne PropertyValue
        Dim prop as Variant
        prop = myDict.ConvertToPropertyValues()

##### I Python

Bemærk i eksemplet herunder, at en Python-ordliste skal videregives som det andet argument i metoden CreateScriptService (opret scripttjeneste).

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

Mange tjenester og metoder i UNO-biblioteket tager parametere ind, der er repræsenteret med structen PropertyValue, som er en del af LibreOffice API.

## Exists

Bestemmer, om der eksisterer en nøgle i ordbogen.

### Syntaks:

dict.Exists(key: str): bool

### Parametre:

nøgle: Den nøgle, der slås op i ordlisten.

### Eksempel:

        Dim myDict as Variant
        myDict = CreateScriptService("Dictionary")
        'Tilføjer nogle egenskaber til ordbogen
        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

Tilføjer indholdet af en streng i JSON (JavaScript Object Notation) til den aktuelle ordbog. Returnerer True, hvis det lykkes.

### Begrænsninger

JSON-strengen kan indeholde tal, tekst, boolske værdier, null-værdier og matrixer, der indeholder disse typer. Den må ikke indeholde JSON-objekter, især ikke undermapper.

Der gøres et forsøg på at konvertere tekst til dato, hvis elementet matcher et af disse mønstre: YYYY-MM-DD, HH:MM:SS eller YYYY-MM-DD HH:MM:SS.

### Syntaks:

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

### Parametre:

inputstr: Den streng, der skal importeres.

overwrite: When True, entries with same name may exist in the dictionary and their values are overwritten. When False (default), repeated keys will raise an error. Be aware that dictionary keys are not case-sensitive while names are case-sensitive in JSON strings.

### 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)
        '(Del)-ordbøgerne "Addresse" and "Telefonnumre" (0) og (1)importeres som tomme værdier..

## ImportFromPropertyValues

Indsætter indholdet af en matrix af PropertyValue-objekterne ind i den aktuelle ordbog. Navne under PropertyValue bruges som nøgler i ordbogen, hvorimod Værdier indeholder de tilsvarende værdier. Returnerer True, hvis det lykkes.

### Syntaks:

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

### Parametre:

propertyvalues (egenskabsværdier): Et nul-baseret 1-dimensionelt matrix, der indeholder objekter fra com.sun.star.beans.PropertyValue. Denne parameter kan også være et enkelt PropertyValue-objekt, der ikke er indeholdt i en matrix.

overskriv: Når True (sand), kan der findes indførsler med det samme navn i ordlisten og deres værdier overskrives. Når False (falsk) (standard), sætter gentagne taster et fejlflag. Bemærk, at ordliste-taster ikke skrives Stort-og-småt i Basic, mens navne skrives Stort-og-småt i grupper af egenskabsværdier og i Python-ordlister.

### Eksempel:

Eksemplerne herunder opretter først en matrix med to PropertyValue (egenskabsværdi)-objekter og derefter konverterer den til en ordliste.

##### 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 ordbogsindførsel baseret på dens nøgle. Returnerer elementets værdi, hvis det lykkes, ellers returneres Empty.

### Syntaks:

dict.Item(key: str): any

### Parametre:

nøgle: Ikke Stort-og-småt. Hvis den ikke eksisterer, returneres værdien Empty (Tom).

### Eksempel:

Det følgende eksempel gennemgår alle nøgler i ordbogen flere gange og bruger metoden Item til at tilgå deres værdier.

        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 ordbogsindførsel baseret på dets nøgle. Returnerer True, hvis det lykkes.

### Syntaks:

dict.Remove(key: str): bool

### Parametre:

nøgle: Skrives ikke Stort-og-småt. Skal findes i en ordliste, ellers sættes et UNKNOWNKEYERROR (ukendt_nøgle_fejl)-flag.

### 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 indførsler fra ordbogen. Returnerer True, hvis det lykkes.

### 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 elementværdi baseret på dens nøgle. Returnerer True,hvis det lykkes.

### Syntaks:

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

### Parametre:

nøgle: Strengværdi, der repræsenterer den nøgle, hvis værdi bliver erstattet. Skrives ikke Stort-og-småt. Hvis nøglen ikke findes i ordlisten, sættes et UNKNOWNKEYERROR (ukendt_nøgle_fejl)-flag.

værdi: Den nye værdi af det element, der henvises til med parameterenkey (nøgle).

### Eksempel:

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

## ReplaceKey

Erstatter en eksisterende nøgle i ordbogen med en ny nøgle. Elementværdien efterlades uændret. Returnerer True, hvis det lykkes.

### Syntaks:

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

### Parametre:

nøgle: Strengværdi, der repræsenterer den nøgle, hvis værdi bliver erstattet. Skrives ikke Stort-og-småt. Hvis nøglen ikke findes i ordlisten, sættes et UNKNOWNKEYERROR (ukendt_nøgle_fejl)-flag.

værdi: Den nye nøgles strengværdi. Skrives ikke Stort-og småt. Hvis den nye nøgle allerede findes i ordlisten, sættes et DUPLICATEKEYERROR (dobbelt_nøgle_fejl)-flag.

### Eksempel:

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

Alle ScriptForge Basic-rutiner eller identifikatorer, der er indledet med et understreget tegn "_" er reserveret til internt brug. Det er ikke meningen, at de skal bruges i Basic-makroer eller Python-scripts.

Relaterede emner

ScriptForge.Array-tjeneste

Samlingsobjekt