Conteúdo

# 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

##### Em Basic

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

##### Em Python

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

Nome | Apenas para leitura | Tipo | Descrição
--- | --- | --- | ---
Count | Sim | Long | O número de verbetes no dicionário
Items | Sim | Conjunto de variantes | A lista de elementos como uma matriz unidimensional
Keys | Sim | Matriz de cadeias de caracteres | A lista de chaves como um tabular unidimensional

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.

### Exemplo:

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

Lista de métodos do serviço de dicionário
Add ConvertToArray ConvertToJson ConvertToPropertyValues | Exists ImportFromJson ImportFromPropertyValues Item | Remove RemoveAll ReplaceItem ReplaceKey

## Add

Adiciona um novo par chave-valor ao dicionário. Devolve True se a operação for bem-sucedida.

### Sintaxe:

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

### Parâmetros:

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.

### Exemplo:

          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.

### Sintaxe:

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

### 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 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.

### Sintaxe:

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

### Parâmetros:

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.

### 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 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.

### Sintaxe:

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

### Exemplo:

##### Em Basic

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

##### Em Python

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.

### Sintaxe:

dict.Exists(key: str): bool

### Parâmetros:

chave: A chave a pesquisar 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 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.

### Sintaxe:

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

### Parâmetros:

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.

### 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 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.

### Sintaxe:

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

### Parâmetros:

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.

### Exemplo:

Os exemplos abaixo criam, em primeiro lugar, um array com dois objetos PropertyValue e, em seguida, convertem-no num dicionário.

##### Em Basic

        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

##### Em Python

        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.

### Sintaxe:

dict.Item(key: str): any

### Parâmetros:

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

### Exemplo:

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.

### Sintaxe:

dict.Remove(key: str): bool

### Parâmetros:

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

### Exemplo:

        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.

### Sintaxe:

dict.RemoveAll(): bool

### Exemplo:

        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.

### Sintaxe:

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

### Parâmetros:

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.

### Exemplo:

        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.

### Sintaxe:

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

### Parâmetros:

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.

### Exemplo:

        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.

Tópicos relacionados

ScriptForge.Array serviço

Objeto de coleção

Necessitamos da sua ajuda!