Serviço ScriptForge.Dictionary

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

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

Ícone Dica

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


Ícone Dica

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

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

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

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.


♥ Doe para nosso projeto! ♥