Tjenesten ScriptForge.Ordbog

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

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

Tipikon

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

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


Tipikon

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
    

Metoder

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

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

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.

overskriv: Når True (sand), kan der findes indtastninger med det samme navn i ordlisten og deres værdier overskrives. Når False (falsk) (standard), hejser gentagne taster et fejlflag. Bemærk, at taster i ordlister ikke er Stort-og-småt, mens navne i JSON-strenge er Stort-og-småt.

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
  
warning

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.


Støt os venligst!