Contenuto
Indice 🔎︎

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

L'oggetto Collection di LibreOffice Basic non supporta l'ottenimento delle chiavi.
Inoltre i suoi elementi contengono solo tipi di dati primitivi di Basic come date, testo, numeri e simili.

## Invocare il 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()

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

| Metodi |
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:

              myDict.Add(Key As String, Item As Variant) As Boolean

### Parametri:

Key : un valore in formato stringa usato per identificare l'elemento. La chiave non fa distinzione tra 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:

              myDict.ConvertToArray() As Variant

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

                myDict.ConvertToJson([Indent As Variant]) As String

### 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 di Indent "" seleziona la rappresentazione più compatta. Usando un numero intero positivo per Indent il rientro corrisponderà 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 ciascun 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 il contenuto di un dizionario in una matrice 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:

              myDict.ConvertToPropertyValues() As Variant

### Esempio:

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

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:

              myDict.Exists(Key As String) As Boolean

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

                myDict.ImportFromJson(InputStr As String, [Overwrite As Boolean]) As Boolean

### Parametri:

InputStr : La stringa da importare.

Overwrite : se è 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. Fate attenzione che le chiavi del dizionario non fanno distinzione tra lettere minuscole e maiuscole, mentre i nomi all'interno delle stringhe JSON fanno tale distinzione.

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

                myDict.ImportFromPropertyValues(PropertyValues As Variant [, Overwrite As Boolean]) As Boolean

### 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 all'interno di una matrice.

Overwrite : se è 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 non fanno distinzione tra lettere minuscole e maiuscole, mentre i nomi nei set di valori delle proprietà fanno tale distinzione.

### Esempio:

                Dim vProp As New com.sun.star.beans.PropertyValue
                vProp.Name = "prop"
                vProp.Value = CDateToUnoDateTime(Now)
                myDict.ImportFromPropertyValues(vProp, Overwrite := True)

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

              myDict.Item(Key As String) As Variant

### Parametri:

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

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

              myDict.Remove(Key As String) As Boolean

### 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) 'Prints "3"
              myDict.Remove("key2")
              MsgBox(myDict.Count) 'Prints "2"

## RemoveAll

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

### Sintassi:

              myDict.RemoveAll() As Boolean

### Esempio:

              myDict.Add("key1", 100)
              myDict.Add("key2", 200)
              myDict.Add("key3", 300)
              MsgBox(myDict.Count) 'Prints "3"
              myDict.RemoveAll()
              MsgBox(myDict.Count) 'Prints "0"

## ReplaceItem

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

### Sintassi:

              myDict.ReplaceItem(Key As String, Value As Variant) As Boolean

### Parametri:

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

Value : Il nuovo valore dell'elemento a cui fa riferimento il parametro Key.

### Esempio:

              myDict.Add("a", 1)
              MsgBox(myDict.Item("a")) 'Prints "1"
              myDict.ReplaceItem("a", 100)
              MsgBox(myDict.Item("a")) ' Prints "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:

              myDict.ReplaceKey(Key As String, Value As String) As Boolean

### Parametri:

Key: Valore in formato stringa che rappresenta la chiave da sostituire. Non fa distinzione 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 fa distinzione 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")) 'Prints "100"
              myDict.ReplaceKey("oldKey", "newKey")
              MsgBox(myDict.Item("newKey")) ' Prints "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.