ScriptForge.Ordbok tjeneste

En ordbok er en samling av nøkkelelementpar

• Nøkkelen er en streng. I Basic-skript bestemmes nøkkelens skille mellom store og små bokstaver når ordboken opprettes. I Python-skript skiller nøkkelen alltid 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.

Ordboktjenesten 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 tilleggsfunksjoner som å erstatte nøkler, teste om en bestemt nøkkel allerede finnes og konvertere ordboken til en matrise med PropertyValues eller en JSON-streng.

Tjenestepåkallelse

Følgende eksempel oppretter myDict som en tom ordbok.

    GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
    Dim myDict As Variant
    myDict = CreateScriptService("Dictionary", True)
                ' Nøklene skiller mellom store og små bokstaver, derfor er det andre argumentet Sann
 

Det anbefales å frigjøre ressurser etter bruk:

     Set myDict = myDict.Dispose()
  

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 ordbokobjekt
    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 ordboksstøtte, er de fleste metodene i Dictionary-tjenesten bare tilgjengelige for Basic-skript. Unntak er metodene ConvertToPropertyValues og ImportFromPropertyValues, som støttes i både Basic og Python.

Egenskaper

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

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
    

Add

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

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

nøkkel: Strengverdi brukt til å identifisere elementet. Nøkkelens store/små bokstavfølsomhet ble bestemt ved opprettelse av ordboken.

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

      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.

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

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

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

      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.

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

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

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.

dict.Exists(key: str): bool

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

    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.

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

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.

    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.

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

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.

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

    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 ordbokoppføring basert på nøkkelen. Returnerer verdien av elementet hvis det lykkes, ellers returnerer Tom.

dict.Item(key: str): any

nøkkel: Hvis den ikke finnes, returneres verdien Tom.

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.

dict.Remove(key: str): bool

nøkkel: Må finnes i ordboken, ellers oppstår en UNKNOWNKEYERROR-feil.

    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.

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 vareverdi basert på nøkkelen. Returnerer Sann hvis vellykket.

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

nøkkel: Strengverdi som representerer nøkkelen hvis verdi skal erstattes. Hvis nøkkelen ikke finnes i ordboken, oppstår en UNKNOWNKEYERROR-feil.

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

    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.

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

nøkkel: Strengverdi som representerer nøkkelen som skal erstattes. Hvis nøkkelen ikke finnes i ordboken, oppstår en UNKNOWNKEYERROR-feil.

verdi: Strengverdi for den nye nøkkelen. Hvis den nye nøkkelen allerede finnes i ordboken, oppstår det en DUPLICATEKEYERROR-feil.

    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.