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 serviço Dictionary é similar ao objeto Collection da linguagem LibreOffice Basic, porém com um conjunto mais amplo de funcionalidades. Por exemplo, objetos Collection não suportam a exclusão de chaves. Além disso, dicionários fornecem possibilidades adicionais como a substituição de chaves, teste de existência de chaves específicas e conversão de dicionários em objetos Array ou strings JSON.

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

O exemplo abaixo cria uma instância vazia do serviço Dictionary e usa o método nativo do Python update para preenchê-la com os conteúdos de um objeto Python dict.

    dico = dict('A' = 1, 'B' = 2, 'C' = 3)
    # Inicializa myDict como um objeto dict vazio
    myDict = CreateScriptService('Dictionary')
    # Carrega os valores de dico para dentro de myDict
    myDict.update(dico)
    myDict['D'] = 4
    print(myDict)   # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
    propval = myDict.ConvertToPropertyValues()
  

É possível criar uma instância do serviço Dictionary usando um objeto Python dict como argumento conforme mostrado no exemplo a seguir.

    dico = dict('A' = 1, 'B' = 2, 'C' = 3)
    # Inicializa myDict com o conteúdo de dico
    myDict = CreateScriptService('Dictionary', dico)
    myDict['D'] = 4
    print(myDict) # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
    propval = myDict.ConvertToPropertyValues()
  

Como a linguagem Python possui suporte integrado a dicionários, a maioria dos métodos no serviço Dictionary estão disponíveis apenas para scripts que usam a linguagem Basic. As exceções são os métodos ConvertToPropertyValues e ImportFromPropertyValues que são suportados tanto em Basic como Python.

Propriedades

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.

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
    

Add

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

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

key: Valor string usado para identificar o item. A chave não é sensível à caixa.

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

      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.

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

      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.

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

indent: Quando indent é um número positivo ou texto, elementos array e objetos membros 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 é uma string vazia "", o que leva à escolha da representação mais compacta. Se um número positivo for 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.

      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 composto por objetos 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.

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

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

Note que no exemplo abaixo o dicionário Python precisa ser passado como o segundo argumento do método CreateScriptService.

    myDict = dict()
    myDict["Color"] = "Blue"
    myDict["Width"] = 30
    sfDic = CreateScriptService("Dictionary", myDict)
    prop = sfDic.ConvertToPropertyValues()
  

Muitos serviços e métodos da biblioteca UNO recebem parâmetros representados como uma estrutura PropertyValue, a qual faz parte da API do LibreOffice.

Exists

Determina se a chave existe no dicionário.

dict.Exists(key: str): bool

key: Chave a ser buscada no dicionário.

    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.

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

inputstr: String a ser importada.

overwrite: Quando True, entradas com o mesmo nome podem existir no dicionário e seus valores são substituídos. Quando False (padrão), teclas repetidas gerarão um erro. Esteja ciente de que as chaves do dicionário não diferenciam maiúsculas de minúsculas, enquanto os nomes diferenciam maiúsculas de minúsculas em strings JSON.

    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.

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

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 à caixa em Basic, porém elas são sensíveis à caixa em objetos PropertyValue e em dicionários nativos da linguagem Python.

Os exemplos abaixo criam um array com dois objetos PropertyValue e converte o array em um dicionário.

    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
  

    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

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.

dict.Item(key: str): any

key: Não sensível à caixa. Se não existir, o valor Empty é retornado.

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.

dict.Remove(key: str): bool

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

    myDict.Add("key1", 100)
    myDict.Add("key2", 200)
    myDict.Add("key3", 300)
    MsgBox(myDict.Count) ' 3
    myDict.Remove("key2")
    MsgBox(myDict.Count) ' 2
  

RemoveAll

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

dict.RemoveAll(): bool

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

ReplaceItem

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

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

key: Valor string representando a chave cujo valor será substituído. Não é sensível à caixa. Se a chave não existir, uma exceção UNKNOWNKEYERROR será lançada.

value: Novo valor do item associado ao parâmetro key.

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

ReplaceKey

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

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

key: Valor string representando a chave a ser substituída. Não é sensível à caixa. 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 à caixa. Se a nova chave não existir, uma exceção DUPLICATEKEYERROR será lançada.

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

Todas as rotinas ou identificadores do ScriptForge em Basic que possuem o caractere "_" como prefixo são reservadas para uso interno. Elas não devem ser usadas em macros escritas em Basic ou em Python.