ScriptForge.Dicionário serviço

Um dicionário é uma coleção de pares chave-elemento

• A chave é uma cadeia de caracteres. Nos scripts em Basic, a distinção entre maiúsculas e minúsculas da chave é determinada aquando da criação do dicionário. Nos scripts em Python, a chave distingue sempre entre maiúsculas e minúsculas.

• Os artigos podem ser de qualquer tipo

É possível recuperar, contar, atualizar chaves e itens, entre outras operações.

O serviço «Dicionário» é semelhante ao objeto LibreOffice Basic Collection integrado, mas com mais funcionalidades. Por exemplo, os objetos Collection não suportam a recuperação de chaves. Além disso, os «Dicionários» oferecem capacidades adicionais, como a substituição de chaves, a verificação da existência de uma chave específica e a conversão do «Dicionário» numa matriz de PropertyValues ou numa cadeia JSON.

Chamada de serviço

O exemplo seguinte cria myDict como um dicionário vazio.

    GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
    Dim myDict As Variant
    myDict = CreateScriptService("Dictionary", True)
                ' As chaves distinguem maiúsculas de minúsculas, pelo que o segundo argumento é True
 

Recomenda-se libertar os recursos após a utilização:

     Set myDict = myDict.Dispose()
  

O exemplo abaixo cria uma instância vazia do serviço Dictionary e utiliza o método nativo do Python update para a preencher com o conteúdo de um objeto dict do Python.

    dico = dict('A' = 1, 'B' = 2, 'C' = 3)
    # Inicializar myDict como um objeto Dictionary vazio
    myDict = CreateScriptService('Dictionary')
    # Carregar os valores de dico para 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 utilizando um objeto dict do Python como argumento, tal como se mostra no exemplo seguinte.

    dico = dict('A' = 1, 'B' = 2, 'C' = 3)
    # Inicializar 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 o Python possui suporte integrado a dicionários, a maioria dos métodos do serviço Dictionary está disponível apenas para scripts em Basic. As exceções são os métodos ConvertToPropertyValues e ImportFromPropertyValues, que são suportados tanto em Basic como em Python.

Propriedades

As propriedades Keys e Items devolvem os respetivos conteúdos, utilizando uma ordem idêntica. A ordem não está relacionada com a sequência de criação.

O exemplo seguinte utiliza a propriedade Keys para percorrer 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-valor ao dicionário. Devolve True se a operação for bem-sucedida.

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

chave: Valor de tipo String utilizado para identificar o Item. A distinção entre maiúsculas e minúsculas da chave foi definida aquando da criação do Dicionário.

item: Qualquer valor, incluindo um array, um objeto Basic, um objeto UNO, um dicionário, etc.

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

Cada chave deve ser única no mesmo dicionário. Se a chave já existir no dicionário, será gerado um erro DUPLICATEKEYERROR. As chaves compostas por espaços gerarão um erro INVALIDKEYERROR.

ConvertToArray

Armazena o conteúdo do dicionário numa matriz de duas colunas, com indexação a partir de zero. As chaves são armazenadas na primeira coluna e os elementos na segunda coluna.

Se o dicionário estiver vazio, este método irá devolver 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 o conteúdo de um dicionário em texto JSON (JavaScript Object Notation).

Limitações

Este método suporta os seguintes tipos de dados: String, Boolean, números, Null e Empty. Também são permitidas matrizes que contenham elementos desses tipos, independentemente das suas dimensões. As datas são convertidas em cadeias de caracteres, mas não podem ser utilizadas dentro de matrizes. Outros tipos de dados são convertidos para a sua representação como cadeia de caracteres utilizando o serviço SF_String.Represent.

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

indent: Quando indent é um número positivo ou um texto, os elementos de um array JSON e os membros de um objeto são formatados com esse nível de indentação. Um valor negativo para indent irá adicionar novas linhas sem indentação. O valor predefinido é uma cadeia vazia "" que seleciona a representação mais compacta. A utilização de um número inteiro positivo para indent indenta esse número de espaços por nível. Quando indent é uma cadeia, como Chr(9) ou Tab(1), o carácter Tab é utilizado 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 o conteúdo do dicionário numa matriz de PropertyValues.

Cada entrada na matriz é um com.sun.star.beans.PropertyValue. A chave é armazenada em Name e o valor é armazenado em Value.

Se um dos elementos for do tipo Date, é convertido para uma estrutura com.sun.star.util.DateTime. Se um dos elementos for uma matriz vazia, é convertido para Null. A matriz resultante fica vazia quando o dicionário está vazio.

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 num array de objetos PropertyValue
    Dim prop as Variant
    prop = myDict.ConvertToPropertyValues()
  

Repare no exemplo abaixo que é necessário passar um dicionário Python como 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 aceitam parâmetros representados através da estrutura PropertyValue, que faz parte da API LibreOffice.

Exists

Determina se uma chave existe no dicionário.

dict.Exists(key: str): bool

chave: A chave a pesquisar 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 cadeia de caracteres JSON (JavaScript Object Notation) ao dicionário atual. Devolve True se a operação for bem-sucedida.

Limitações

A cadeia JSON pode conter números, texto, valores booleanos, valores nulos e matrizes que contenham esses tipos. Não deve conter objetos JSON, nomeadamente subdicionários.

Tenta-se converter o texto em data se o elemento corresponder a um destes formatos: AAAA-MM-DD, HH:MM:SS ou AAAA-MM-DD HH:MM:SS.

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

inputstr: A cadeia de caracteres a importar.

substituir: Quando True, podem existir entradas com o mesmo nome no dicionário e os seus valores são substituídos. Quando False (por predefinição), as chaves repetidas provocam um erro. Tenha em atenção que as chaves do dicionário não distinguem maiúsculas de minúsculas, ao passo que os nomes distinguem maiúsculas de minúsculas nas cadeias de caracteres 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 vazios.
  

ImportFromPropertyValues

Inserir o conteúdo de um array de objetos PropertyValue no dicionário atual. Os nomes PropertyValue são utilizados como chaves no dicionário, enquanto os valores contêm os valores correspondentes. Devolve True se a operação for bem-sucedida.

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

propertyvalues: Uma matriz unidimensional com índice a partir de zero que contém objetos com.sun.star.beans.PropertyValue. Este parâmetro também pode ser um único objeto PropertyValue que não esteja incluído numa matriz.

sobrescrever: Quando True, podem existir entradas com o mesmo nome no dicionário e os seus valores são sobrescritos. Quando False (por predefinição), as chaves repetidas provocam um erro. Note-se que as chaves do dicionário não distinguem maiúsculas de minúsculas no Basic, ao passo que os nomes distinguem maiúsculas de minúsculas nos conjuntos de valores de propriedades e nos dicionários do Python.

Os exemplos abaixo criam, em primeiro lugar, um array com dois objetos PropertyValue e, em seguida, convertem-no num 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 uma entrada existente no dicionário com base na sua chave. Devolve o valor do item se a operação for bem-sucedida; caso contrário, devolve Vazio.

dict.Item(key: str): any

chave: Se não existir, é devolvido o valor Vazio.

O exemplo seguinte percorre todas as chaves do dicionário e utiliza o método Item para aceder aos respetivos 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 existente do dicionário com base na sua chave. Devolve True se a operação for bem-sucedida.

dict.Remove(key: str): bool

chave: Tem de existir no dicionário; caso contrário, é gerado um erro UNKNOWNKEYERROR.

    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. Devolve True se a operação for bem-sucedida.

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 o valor de um elemento existente com base na sua chave. Devolve True se a operação for bem-sucedida.

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

chave: Valor de tipo String que representa a chave cujo valor será substituído. Se a chave não existir no dicionário, é gerado um erro UNKNOWNKEYERROR.

valor: O novo valor do item a que se refere o parâmetro chave.

    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 elemento permanece inalterado. Devolve True se a operação for bem-sucedida.

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

chave: Valor de tipo String que representa a chave a substituir. Se a chave não existir no dicionário, é gerado um erro UNKNOWNKEYERROR.

valor: Valor de tipo String para a nova chave. Se a nova chave já existir no dicionário, é gerado um erro DUPLICATEKEYERROR.

    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 Basic que tenham o caractere de sublinhado «_» como prefixo estão reservados para uso interno. Não se destinam a ser utilizados em macros do Basic ou em scripts Python.