Servizio ScriptForge.Dictionary

Un dizionario è una raccolta di coppie chiave-elemento

• The key is a string. In Basic scripts, the case sensitivity of the key is determined at Dictionary creation. In Python scripts, the key is always case-sensitive.

• Gli elementi possono essere di qualunque tipo

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

The Dictionary service is similar to the built-in LibreOffice Basic Collection object, however with more features. For example, Collection objects do not support the retrieval of keys. Moreover, Dictionaries provide additional capabilities as replacing keys, testing if a specific key already exists and converting the Dictionary into an array of PropertyValues or a JSON string.

Invocazione del servizio

L'esempio seguente crea myDict come dizionario vuoto.

    GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
    Dim myDict As Variant
    myDict = CreateScriptService("Dictionary", True)
                ' The keys are case-sensitive, hence the second argument is True
 

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)
    # Initialize myDict as an empty Dictionary object
    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()
  

Because Python has built-in dictionary support, most of the methods in the Dictionary service are available for Basic scripts only. Exceptions are the ConvertToPropertyValues and ImportFromPropertyValues methods that are supported in both Basic and 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: String value used to identify the Item. The case sensitivity of the key was determined at Dictionary creation..

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: If it does not exist, the Empty value is returned.

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: Must exist in the dictionary, otherwise an UNKNOWNKEYERROR error is raised.

    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: String value representing the key whose value will be replaced. If the key does not exist in the dictionary, an UNKNOWNKEYERROR error is raised.

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: String value representing the key to be replaced. If the key does not exist in the dictionary, a UNKNOWNKEYERROR error is raised.

value: String value for the new key. If the new key already exists in the dictionary, a DUPLICATEKEYERROR error is raised.

    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.