Contenuto

# 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

##### In Basic

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

##### In Python

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à

Nome | Solo lettura | Tipo | Descrizione
--- | --- | --- | ---
Count | Sì | Long | Il numero di elementi nel dizionario
Items | Sì | Matrice di varianti | L'elenco degli elementi in forma di matrice unidimensionale
Keys | Sì | Matrice di stringhe | L'elenco delle chiavi in forma di matrice unidimensionale

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

### Esempio:

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

Elenco dei metodi del servizio Dictionary
Add ConvertToArray ConvertToJson ConvertToPropertyValues | Exists ImportFromJson ImportFromPropertyValues Item | Remove RemoveAll ReplaceItem ReplaceKey

## Add

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

### Sintassi:

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

### Parametri:

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.

### Esempio:

          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.

### Sintassi:

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

### Esempio:

          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.

### Sintassi:

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

### Parametri:

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.

### Esempio:

          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.

### Sintassi:

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

### Esempio:

##### In Basic

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

##### In Python

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.

### Sintassi:

dict.Exists(key: str): bool

### Parametri:

key: la chiave da cercare nel dizionario.

### Esempio:

        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.

### Sintassi:

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

### Parametri:

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

### Esempio:

        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.

### Sintassi:

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

### Parametri:

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

### Esempio:

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

##### In 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

##### In 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

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.

### Sintassi:

dict.Item(key: str): any

### Parametri:

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

### Esempio:

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.

### Sintassi:

dict.Remove(key: str): bool

### Parametri:

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

### Esempio:

        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.

### Sintassi:

dict.RemoveAll(): bool

### Esempio:

        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.

### Sintassi:

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

### Parametri:

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.

### Esempio:

        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.

### Sintassi:

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

### Parametri:

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.

### Esempio:

        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.

Argomenti correlati

Servizio ScriptForge.Array

Oggetto Collection