Servizio ScriptForge.Dictionary

Un dizionario è una raccolta di coppie chiave-elemento

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

Icona di suggerimento

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


Icona di suggerimento

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

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

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"
       
warning

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.


Sosteneteci!