Conteúdo
Índice 🔎︎

# Serviço ScriptForge.Dictionary

Um dicionário é uma coleção de pares de chaves-itens.

- Uma chave é uma string não sensível ao caso.

- Itens podem ser de qualquer tipo.

Chaves e itens podem ser recuperadas, contadas, atualizadas, entre outras operações.

O objeto Collection do LibreOffice Basic não suporta a recuperação de chaves.
Além disso, seus itens contêm apenas tipos de dados primitivos da linguagem Basic, tais como datas, strings, números, etc.

## Invocação do serviço

O exemplo a seguir cria myDict como um dicionário vazio.

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

É recomendado liberar recursos após o uso:

         Set myDict = myDict.Dispose()

## Propriedades

Nome | Somente leitura | Tipo | Descrição
Count | Sim | Long | Número de entradas em um dicionário
Items | Sim | Array de Variants | Lista de itens como um array de uma dimensão
Keys | Sim | Array de Strings | Lista de chaves como um array de uma dimensão

As propriedades Keys (Chaves) e Items (Itens) retornam seus respectivos conteúdos, usando uma ordem idêntica. A ordem de retorno não está relacionada à ordem de inserção dos itens.

### Exemplo:

O exemplo a seguir usa a propriedade Keys para iterar sobre todas as chaves do dicionário myDict.

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

| Métodos |
Add ConvertToArray ConvertToJson ConvertToPropertyValues | Exists ImportFromJson ImportFromPropertyValues Item | Remove RemoveAll ReplaceItem ReplaceKey

## Add

Adiciona um novo par chave-item ao dicionário. Retorna True se bem-sucedido.

### Sintaxe:

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

### Parâmetros:

Key : Valor string usado para identificar o item. A chave não é sensível ao caso.

Item : Qualquer valor, incluindo arrays, objetos Basic, objetos UNO, outros dicionários, etc.

### Exemplo:

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

Toda chave deve ser única num mesmo dicionário. Se a chave já existe no dicionário, uma exceção DUPLICATEKEYERROR será lançada. Chaves que contém espaços em branco causarão a exceção INVALIDKEYERROR.

## ConvertToArray

Armazena os conteúdos de um dicionário em um array indexado em zero com duas colunas. As chaves são armazenadas na primeira coluna e os itens são armazenadas na segunda coluna.

Se o dicionário estiver vazio, este método retornará um Array vazio.

### Sintaxe:

              myDict.ConvertToArray() As Variant

### Exemplo:

            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 os conteúdos de um dicionário em texto no formato JSON (JavaScript Object Notation).

### Limitações

Este método suporta os seguintes tipos de dados: String, Boolean, tipos numéricos, Null e Empty. Arrays que contém desses tipos são permitidos, independente de suas dimensões. Datas são convertidas para strings, contudo datas não podem ser usadas em arrays. Outros tipos de dados são convertidos para sua representação textual usando o serviço SF_String.Represent.

### Sintaxe:

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

### Parâmetros:

Indent : Quando Indent é um número positivo ou texto, elementos array e objetos JSON são impressos usando este nível de indentação. Um valor Indent negativo adicionará novas linhas sem indentação. O valor padrão de Indent é "", o que leva à escolha da representação mais compacta. Se um número positivo por usado para Indent, essa quantidade de espaços será adicionada por nível. Quando Indent for uma string, tal como Chr(9) ou Tab(1), o caractere Tab será usado para indentar cada nível.

### Exemplo:

                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

Armazena os conteúdos do dicionário em um array do tipo PropertyValues.

Cada entrada no array é um objeto com.sun.star.beans.PropertyValue. A chave é armazenada no campo Name e o item é armazenado no campo Value.

Se um dos itens for do tipo Date, ele é então convertido para um struct do tipo com.sun.star.util.DateTime. Se um dos itens for um array vazio, ele é convertido para Null. Se o dicionário for vazio, então um array vazio é retornado.

### Sintaxe:

              myDict.ConvertToPropertyValues() As Variant

### Exemplo:

              Dim myDict as Variant
              myDict = CreateScriptService("Dictionary")
              'Adiciona algumas propriedades ao dicionário
              myDict.Add("Color", "Blue")
              myDict.Add("Width", 20)
              'Converte para um Array de objetos PropertyValue
              Dim prop as Variant
              prop = myDict.ConvertToPropertyValues()

Muitos serviços e métodos da biblioteca UNO recebem como parâmetros objetos representados com o struct PropertyValue, o qual faz parte da API do LibreOffice.

## Exists

Determina se a chave existe no dicionário.

### Sintaxe:

              myDict.Exists(Key As String) As Boolean

### Parâmetros:

Key : Chave a ser procurada no dicionário.

### Exemplo:

              Dim myDict as Variant
              myDict = CreateScriptService("Dictionary")
              'Adiciona algumas propriedades ao dicionário
              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

Adiciona o conteúdo de uma string JSON (JavaScript Object Notation) ao dicionário atual. Retorna True se bem-sucedido.

### Limitações

A string JSON pode conter números, texto, valores booleanos, null e arrays contendo tais tipos. Contudo, a string não pode conter objetos JSON como sub-dicionários.

Uma tentativa de converter texto em datas é feita se o item seguir um destes padrões de formato: YYYY-MM-DD, HH:MM:SS ou YYYY-MM-DD HH:MM:SS.

### Sintaxe:

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

### Parâmetros:

InputStr : String a ser importada.

Overwrite : Quando for igual a True, entradas com o mesmo nome podem existir no dicionário e seus valores são sobrescritos. Se for igual a False (padrão), chaves repetidas causarão o lançamento de uma exceção. Lembre-se que as chaves dos dicionários não são sensíveis ao caso, porém elas são sensíveis ao caso em strings JSON.

### Exemplo:

                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)
                'Os sub-dicionários "address" e "phoneNumbers" (0) e (1) são importados como valores Empty

## ImportFromPropertyValues

Insere os conteúdos de um array de objetos PropertyValue em um dicionário. O campo Name do PropertyValue é usado como a chave do dicionário, e o campo Value contém o valor correspondente. Retorna True se bem sucedido.

### Sintaxe:

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

### Parâmetros:

PropertyValues : Array de uma dimensão contendo objetos com.sun.star.beans.PropertyValue. Este parâmetro também pode ser um único objeto PropertyValue não contido em um Array.

Overwrite : Quando for igual a True, entradas com o mesmo nome podem existir no dicionário e seus valores são sobrescritos. Se for igual a False (padrão), chaves repetidas causarão o lançamento de uma exceção. Lembre-se que as chaves dos dicionários não são sensíveis ao caso, porém elas são sensíveis ao caso em objetos PropertyValue.

### Exemplo:

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

## Item

Recupera um valor do dicionário com base em sua chave. Retorna o valor do item se for bem-sucedido, caso contrário retorna Empty.

### Sintaxe:

              myDict.Item(Key As String) As Variant

### Parâmetros:

Key : Não sensível ao caso. Deve existir no dicionário, caso contrário uma exceção UNKNOWNKEYERROR será lançada.

### Exemplo:

O exemplo a seguir itera sobre todas as chaves do dicionário e usa o método Item para acessar seus valores.

              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

Remove uma entrada do dicionário com base em sua chave. Retorna True se bem-sucedido.

### Sintaxe:

              myDict.Remove(Key As String) As Boolean

### Parâmetros:

Key : Não sensível ao caso. Deve existir no dicionário, caso contrário uma exceção UNKNOWNKEYERROR será lançada.

### Exemplo:

              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

Remove todas as entradas do dicionário. Retorna True se bem-sucedido.

### Sintaxe:

              myDict.RemoveAll() As Boolean

### Exemplo:

              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

Substitui um item existente no dicionário com base em sua chave. Retorna True se bem-sucedido.

### Sintaxe:

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

### Parâmetros:

Key : Valor string representando a chave cujo valor deve ser substituído. Não é sensível ao caso. Se a chave não existe, uma exceção UNKNOWNKEYERROR será lançada.

Value : Novo valor do item a ser associado ao parâmetro Key.

### Exemplo:

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

## ReplaceKey

Substitui uma chave existente no dicionário por uma nova chave. O valor do item permanece inalterado. Retorna True se bem-sucedido.

### Sintaxe:

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

### Parâmetros:

Key : Valor string representando a chave a ser substituída. Não é sensível ao caso. Se a chave não existir no dicionário, uma exceção UNKNOWNKEYERROR será lançada.

Value : Valor string para a nova chave. Não é sensível ao caso. Se a nova chave não existir, uma exceção DUPLICATEKEYERROR será lançada.

### Exemplo:

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

Todas as rotinas básicas ou identificadores do ScriptForge que possuem o caractere "_" como prefixo são reservados apenas para uso interno. Elas não devem ser usadas em macros Basic.