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

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

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

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

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
    

Add

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

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

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.

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

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

      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.

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

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.

      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.

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

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

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.

dict.Exists(key: str): bool

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

    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.

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

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.

    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.

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

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.

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

    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
  

    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.

dict.Item(key: str): any

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

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.

dict.Remove(key: str): bool

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

    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.

dict.RemoveAll(): bool

    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.

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

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

    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.

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

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.

    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.