Servizio ScriptForge.Dictionary

Un dizionario è una raccolta di coppie chiave-elemento

• La chiave è una stringa che non fa distinzione tra lettere maiuscole e minuscole

• Gli elementi possono essere di qualunque tipo

Le chiavi e gli elementi possono essere recuperati, contati, aggiornati e molto altro.

Il servizio Dictionary è simile all'oggetto Collection incorporato in LibreOffice Basic, ma con più funzionalità. Per esempio, gli oggetti Collection non supportano la ricerca per chiavi; inoltre i dizionari (oggetti Dictionary) forniscono capacità aggiuntive per la sostituzione delle chiavi, verificare se una specifica chiave esiste già e convertire il dizionario in una matrice (oggetto Array) o in una stringa JSON.

Invocazione del servizio

L'esempio seguente crea myDict come dizionario vuoto.

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

Si raccomanda di liberare le risorse dopo l'uso:

     Set myDict = myDict.Dispose()
  

L'esempio sottostante crea un'istanza vuota del servizio Dictionary e usa il metodo update nativo di Python per popolarla col contenuto di un oggetto dict di Python.

    dico = dict('A' = 1, 'B' = 2, 'C' = 3)
    # Inizializza myDict come oggetto dict vuoto
    myDict = CreateScriptService('Dictionary')
    # Carica i valori di dico in myDict
    myDict.update(dico)
    myDict['D'] = 4
    print(myDict)   # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
    propval = myDict.ConvertToPropertyValues()
  

Potete creare un'istanza del servizio Dictionary usando un oggetto dict di Python come argomento, come mostrato nell'esempio seguente.

    dico = dict('A' = 1, 'B' = 2, 'C' = 3)
    # Inizializza myDict con il contenuto di dico
    myDict = CreateScriptService('Dictionary', dico)
    myDict['D'] = 4
    print(myDict) # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
    propval = myDict.ConvertToPropertyValues()
  

Poiché Python incorpora il supporto per i dizionari, la maggior parte dei metodi del servizio Dictionary è disponibile solo per gli script in Basic. Le eccezioni sono i metodi ConvertToPropertyValues e ImportFromPropertyValues, supportati sia in Basic, sia in Python.

Proprietà

Le proprietà Keys e Items restituiscono il rispettivo contenuto usando il medesimo ordine. L'ordine è indipendente dalla sequenza di creazione.

L'esempio seguente usa la proprietà Keys per iterare tutte le chiavi del dizionario myDict.

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

Add

Aggiunge una nuova coppia chiave-elemento al dizionario. Restituisce True se l'inserimento ha esito positivo.

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

key: un valore in formato stringa usato per identificare l'elemento. La chiave non distingue le lettere maiuscole e minuscole.

item: qualunque valore, comprese matrici, oggetti Basic, oggetti UNO, dizionari, ecc.

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

Ogni chiave deve essere univoca all'interno dello stesso dizionario. Se nel dizionario la chiave esiste già, verrà generato un errore DUPLICATEKEYERROR. Le chiavi formate da caratteri di spazio genereranno un errore INVALIDKEYERROR.

ConvertToArray

Memorizza i contenuti di un dizionario in una matrice a due colonne con indice iniziale uguale a zero. Le chiavi sono memorizzate nella prima colonna e gli elementi nella seconda.

Se il dizionario è vuoto, questo metodo restituirà una matrice vuota Array.

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

Converte i contenuti di un dizionario in un testo in formato JSON (JavaScript Object Notation).

Limitazioni

Questo metodo supporta i seguenti tipi di dati: String, Boolean, numeri, Null ed Empty. Sono permesse anche le matrici che contengono questi tipi di dati, indipendentemente dalle loro dimensioni. Le date vengono convertire in stringhe e in ogni caso non possono essere usate all'interno di matrici. Gli altri tipi di dati vengono convertiti nella loro rappresentazione come stringa usando il servizio SF_String.Represent.

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

indent: se indent è un numero positivo o un testo, gli elementi delle matrici e gli oggetti presenti nel testo JSON vengono stampati con quel livello di rientro. Un valore negativo di indent aggiungerà nuove righe senza rientro. Il valore predefinito è una stringa vuota "" che seleziona la rappresentazione più compatta. Usando un numero intero positivo per indent i rientri corrisponderanno a quel numero di spazi per livello. Se indent è una stringa, come Chr(9) o Tab(1), il carattere Tab sarà usato per far rientrare ogni livello.

      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

Memorizza i contenuti di un dizionario in una matrice di PropertyValues.

Ogni record della matrice è un oggetto com.sun.star.beans.PropertyValue. La chiave è memorizzata in Name e l'elemento in Value.

Se uno degli elementi è di tipo Date, viene convertito in una struttura com.sun.star.util.DateTime. Se uno degli elementi è una matrice vuota, viene convertito in Null. La matrice risultante sarà vuota nel caso in cui il dizionario sia vuoto.

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

    Dim myDict as Variant
    myDict = CreateScriptService("Dictionary")
    'Aggiunge delle proprietà al dizionario
    myDict.Add("Color", "Blue")
    myDict.Add("Width", 20)
    'Converte in una matrice di oggetti PropertyValue
    Dim prop as Variant
    prop = myDict.ConvertToPropertyValues()
  

Fate attenzione che, nell'esempio sottostante, un dizionario di Python deve essere passato come secondo argomento del metodo CreateScriptService.

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

Molti servizi e metodi della libreria UNO ricevono i parametri rappresentati come strutture PropertyValue, che sono parte delle API di LibreOffice.

Exists

Determina se una chiave esiste già nel dizionario.

dict.Exists(key: str): bool

key: la chiave da cercare nel dizionario.

    Dim myDict as Variant
    myDict = CreateScriptService("Dictionary")
    'Aggiunge delle proprietà al dizionario
    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

Aggiunge il contenuto di una stringa JSON (JavaScript Object Notation) al dizionario in uso. Restituisce True se l'aggiunta ha ottenuto esito positivo.

Limitazioni

La stringa JSON può contenere numeri, testo, valori booleani, valori null e matrici che contengono gli stessi tipi di dati. Non deve contenere oggetti JSON ovvero dizionari nidificati.

Viene eseguito un tentativo di conversione del testo in data quando un elemento corrisponde a uno di questi modelli: AAAA-MM-GG, HH:MM:SS o AAAA-MM-GG HH:MM:SS.

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

inputstr: la stringa da importare.

overwrite: se impostato su True, nel dizionario possono esistere dei record con lo stesso nome e i relativi valori saranno sovrascritti. Se è False (predefinito), le chiavi duplicate genereranno un errore. È bene notare che le chiavi del dizionario non fanno distinzione tra lettere minuscole e maiuscole, mentre i nomi all'interno delle stringhe JSON sì.

    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)
    'I (sotto)-dizionari "address" e "phoneNumbers" (0) e (1) vengono importati come valori vuoti (Empty).
  

ImportFromPropertyValues

Inserisce nel dizionario corrente i contenuti di una matrice di oggetti PropertyValue. La proprietà Name di PropertyValue viene usata come chiave nel dizionario, mentre la proprietà Value contiene i valori corrrispondenti. Restituisce True se l'inserimento ha esito positivo.

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

propertyvalues: una matrice unidimensionale con indice a partire da zero, che contiene oggetti com.sun.star.beans.PropertyValue. Questo parametro può essere anche un singolo oggetto PropertyValue non compreso in una matrice.

overwrite: se impostato su True, nel dizionario possono esistere dei record con lo stesso nome e i loro valori saranno sovrascritti. Se è False (predefinito), le chiavi duplicate genereranno un errore. Fate attenzione che le chiavi del dizionario in Basic non fanno distinzione tra lettere minuscole e maiuscole, mentre i nomi all'interno dei set di valori delle proprietà e nei dizionari di Python sì.

Gli esempi sottostanti creano prima una matrice con due oggetti PropertyValue e poi la convertono in un dizionario.

    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

Trova un record all'interno di un dizionario esistente in base alla sua chiave. Restituisce il valore dell'elemento se la ricerca ha esito positivo, altrimenti restituisce Empty.

dict.Item(key: str): any

key: non fa distinzione tra minuscole e maiuscole. Se non esiste viene restituito il valore Empty.

L'esempio seguente esegue un'iterazione su tutte le chiavi del dizionario usando il metodo Item per accedere ai relativi valori.

    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

Elimina un record da un dizionario esistente in base alla sua chiave. Restituisce True se l'eliminazione è riuscita.

dict.Remove(key: str): bool

key: non fa distinzione tra lettere minuscole e maiuscole. Deve esistere nel dizionario, altrimenti viene generato un errore UNKNOWNKEYERROR.

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

RemoveAll

Elimina tutti i record da un dizionario. Restituisce True se l'eliminazione è riuscita.

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

Sostituisce il valore di un elemento esistente in base alla sua chiave. Restituisce True se la sostituzione è riuscita.

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

key: valore in formato stringa che rappresenta la chiave del valore da sostituire. Non distingue tra lettere minuscole e maiuscole. Se nel dizionario la chiave non esiste, viene generato un errore UNKNOWNKEYERROR.

value: il nuovo valore dell'elemento cui fa riferimento il parametro Key.

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

ReplaceKey

Sostituisce una chiave esistente nel dizionario con una nuova chiave. Il valore dell'elemento rimane immutato. Restituisce True se la sostituzione ha esito positivo.

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

key: valore in formato stringa che rappresenta la chiave da sostituire. Non distingue tra lettere minuscole e maiuscole. Se la chiave non esiste nel dizionario viene generato un errore UNKNOWNKEYERROR.

value: valore in formato stringa per la nuova chiave. Non distingue tra lettere minuscole e maiuscole. Se nel dizionario la chiave esiste già, viene generato un errore DUPLICATEKEYERROR.

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

Tutte le routine e gli identificatori Basic di ScriptForge che iniziano con un carattere di sottolineatura "_" sono riservati per uso interno. Non è previsto il loro utilizzo nelle macro in Basic o negli script in Python.