Ir para o conteúdo

Funções de Dicionário e Matriz

Introdução

As funções de dicionário e array fornecem estruturas de armazenamento para informações em scripts. Veja Related Functions no painel lateral para funções adicionais que podem ser usadas com arrays.

Diferença Entre Arrays e Dicionários

Embora muito semelhantes em muitos aspectos como método para armazenar informações, arrays e dicionários diferem nestas características importantes:

  • Matrizes
    • Os elementos são ordenados
    • Os elementos são recuperados por posição
  • Dicionários
    • Os elementos são armazenados independentemente da ordem e não têm ordem intrínseca
    • Os elementos são recuperados por uma chave

A sintaxe para definir e recuperar um elemento é semelhante (ambos podem usar a notação de colchetes), mas as matrizes não possuem chaves associadas aos elementos e devem armazenar todos os itens sequencialmente, sem lacunas. Os dicionários podem ser esparsos, com chaves preenchidas apenas conforme necessário.

Qual usar depende da natureza da informação. Os dicionários se prestam a informações que variam em como são recuperadas. Matrizes geralmente são melhores para conjuntos ordenados.

Configurando e Recuperando Valores em Arrays e Dicionários

// Example of an array
$org.lookup.currency = Array();
$org.lookup.currency[1]="USD";
$org.lookup.currency[2]="EUR";

// currency will be "USD"
currency = $org.lookup.currency[1];

// Example of a dictionary
$common.dictionary.message = Dict();
AddToDict($common.dictionary.message, 'OP_START', 'Start');
AddToDict($common.dictionary.message, 'OP_END', 'End');
AddToDict($common.dictionary.message, 'API_PARMS', 'API Parameters');

// message will be "API Parameters"
message = $common.dictionary.message['API_PARMS'];

Encontrando Valores em Dicionários e Matrizes

Para os dicionários, o HasKey a função permite testar se uma tecla está presente. Para uma matriz, você pode usar o FindValue função de maneira semelhante, passando duas instâncias da matriz para a função:

arr = {1, 2, 3};
value = 1;
t = (FindValue(value, arr, arr) == value);
// t will be 1 (true)

value = 4;
t = (FindValue(value, arr, arr) == value);
// t will be 0 (false)

AddToDict

Declaração

bool AddToDict(dictionary dict, string key, type arg)

Sintaxe

AddToDict(<dict>, <key>, <arg>)

Parâmetros Necessários

  • dict: Um dicionário existente
  • key: Chave a ser utilizada no dicionário
  • arg: Valor a ser colocado nessa chave

Descrição

Adiciona um valor a um dicionário para uma chave específica.

A chave deve ser uma string ou ter uma representação de string, com chaves nulas não permitidas. Qualquer value é permitido, mesmo valores nulos.

devoluções true se o valor foi adicionado e a nova chave adicionada ao dicionário ou false se a chave já existia e o valor dessa chave foi atualizado. Se o primeiro argumento não estiver definido ou não for um dicionário, ele será inicializado em um dicionário vazio antes que o valor seja adicionado.

Veja também o Dict() função.

Exemplos

// Initialize a dictionary prior to use
d = Dict();


// Adds a value to a dictionary "d" if a key doesn't already exist
If(!HasKey(d, "key"), AddToDict(d, "key", "value"));

// To directly assign a key-value, use this syntax:
d["key"] = "value";

`WARNING: Use of a null key will cause an error and stop the execution of an operation.

Array

Declaração

array Array()

Sintaxe

Array()

Descrição

Cria uma matriz vazia. Embora os arrays não precisem ser inicializados antes do uso, esse método pode ser usado para ser explícito ou para redefinir um array já existente. As matrizes são baseadas em zero e os valores são recuperados usando índices.

Exemplos

// Create an empty array and set values
arr = Array();
arr[0] = "value1";
arr[1] = "value2";

// Create an array and set the first value directly:
arr2[0] = "value";

// Arrays can be created with { } syntax:
arr3 = {};

Collection

Declaração

array Collection()

Sintaxe

Collection()

Descrição

um pseudônimo para Array. Veja a função Array.

CollectValues

Declaração

array CollectValues(dictionary dict, array names)

Sintaxe

CollectValues(<dict>, <names>)

Parâmetros Necessários

  • dict: Um dicionário existente
  • names: Uma matriz de chaves a serem procuradas no dicionário

Descrição

Retorna uma matriz contendo os valores correspondentes aos nomes na matriz de argumentos, retornados na mesma ordem das chaves na matriz.

Exemplos

// Retrieve a map from a source instance
map = GetSourceInstanceMap([Values$Value.]);
names = Array();
names[0] = "Attr1";
names[1] = "Attr2";
// Array containing the values of
// the attributes named in the names array
values = CollectValues(map, names);

Dict

Declaração

dictionary Dict()

Sintaxe

Dict()

Descrição

Cria um dicionário vazio. Um dicionário é uma coleção de pares nome-valor em que o valor é recuperado com base em um valor de chave de string. Qualquer valor é permitido, mesmo valores nulos. A chave deve ser uma string ou ter uma representação de string. Chaves nulas não são permitidas. Veja também o AddToDict() função.

Aviso

Os dicionários devem ser inicializados antes de serem usados.

Aviso

O uso de uma chave nula causará um erro e interromperá a execução de uma operação.

Exemplos

// Creating a dictionary "myDictionary"
myDictionary = Dict();

// Assigning a value ("text") to the key "myKey"
myDictionary["myKey"] = "text";
// Using the AddToDict function instead
AddToDict(myDictionary, "myKey", "text");

GetKeys

Declaração

array GetKeys(dictionary dict)

Sintaxe

GetKeys(<dict>)

Parâmetros Necessários

  • dict: Um dicionário existente

Descrição

Retorna um array das chaves em um dicionário. O argumento deve ser um dicionário existente.

Exemplos

// Retrieving the keys from the dictionary "myDictionary"
// using GetKeys and then looping through the array
// to retrieve all the values in the dictionary
// and writing them to the Operation Log
keys = GetKeys(myDictionary);
i=0;
While(i < Length(keys),
 WriteToOperationLog(myDictionary[keys[i]]);
 i++;
);

GetSourceAttrNames

Declaração

array GetSourceAttrNames(node n)

Sintaxe

GetSourceAttrNames(<n>)

Parâmetros Necessários

  • n: Uma expressão de caminho de referência de string para um nó na transformação atual

Descrição

Retorna um array contendo os nomes dos atributos de um nó, na ordem em que os atributos aparecem no nó.

Compare com a função GetSourceInstanceMap que retorna um mapa das chaves (os atributos) e valores para um nó.

Para inserir um n path na função, clique duas vezes na pasta do nó XML desejada para inserir seu caminho qualificado no local do cursor. Para obter mais informações, consulte as instruções em inserir caminhos de nó XML.

Exemplos

// Appends all the attributes together without having
// to explicitly reference their source data elements
map = GetSourceInstanceMap([Values$Value.]);
names = GetSourceAttrNames([Values$Value.]);
i = 0;
n = Length(names);
str = "";

While(i < n,
  str = str + map[names[i]];
  i++;
);

GetSourceElementNames

Declaração

array GetSourceElementNames(node n)

Sintaxe

GetSourceElementNames(<n>)

Parâmetros Necessários

  • n: Uma expressão de caminho de referência de string para um nó na transformação atual

Descrição

Retorna uma matriz contendo os nomes dos subelementos simples de um nó na ordem em que os atributos aparecem no nó.

Compare com a função GetSourceInstanceElementMap que retorna um mapa de um nó.

Para inserir um n path na função, clique duas vezes na pasta do nó XML desejada para inserir seu caminho qualificado no local do cursor. Para obter mais informações, consulte as instruções em inserir caminhos de nó XML.

Exemplos

// Appends all the attributes together without having
// to explicitly reference their source data elements
map = GetSourceInstanceElementMap([Values$Value.]);
names = GetSourceElementNames([Values$Value.]);

// The values as an array of values from the sub-elements
values = CollectValues(map, names);

GetSourceInstanceArray

Declaração

array GetSourceInstanceArray(node n)

Sintaxe

GetSourceInstanceArray(<n>)

Parâmetros Necessários

  • n: Uma expressão de caminho de referência de string para um nó na transformação atual

Descrição

Retorna uma matriz contendo o valor do atributo de um nó de elemento. O valor na matriz é rotulado com o nome do atributo e pode ser recuperado por seu índice ou por seu nome como em um elemento de dados de dicionário.

Como alternativa a esta função, consulte GetSourceInstanceMap.

Para inserir um n path na função, clique duas vezes na pasta do nó XML desejada para inserir seu caminho qualificado no local do cursor. Para obter mais informações, consulte as instruções em inserir caminhos de nó XML.

Exemplos

arr = GetSourceInstanceArray([Values$Value.]);
// To retrieve the value of the "Attr1" attribute:
// If "Attr1" is the first attribute name, you can use:
v = arr[0];
// Or, you can use the name "Attr1":
v = arr["Attr1"];

GetSourceInstanceElementArray

Declaração

array GetSourceInstanceElementArray(node n)

Sintaxe

GetSourceInstanceElementArray(<n>)

Parâmetros Necessários

  • n: Uma expressão de caminho de referência de string para um nó na transformação atual

Descrição

Retorna uma matriz contendo o valor do subelemento de um nó de elemento. O valor na matriz é rotulado com o nome do subelemento e pode ser recuperado por seu índice ou por seu nome como no elemento de dados do dicionário.

Como alternativa a esta função, consulte GetSourceInstanceElementMap.

Para inserir um n path na função, clique duas vezes na pasta do nó XML desejada para inserir seu caminho qualificado no local do cursor. Para obter mais informações, consulte as instruções em inserir caminhos de nó XML.

Exemplos

arr = GetSourceInstanceElementMap([Values$Value.]);
// To retrieve the value of the "e1" sub-element:
// If "el" is the first sub-element, you can use:
v = arr[0];
// Or, you can use the name "e1":
v = arr["e1"];

GetSourceInstanceMap

Declaração

dictionary GetSourceInstanceMap(node n)

Sintaxe

GetSourceInstanceMap(<n>)

Parâmetros Necessários

  • n: Uma expressão de caminho de referência de string para um nó na transformação atual

Descrição

Retorna um dicionário (mapa) contendo o nome do atributo e seu valor de um nó de elemento.

Como alternativa a essa função, consulte GetSourceInstanceArray.

Para inserir um n path na função, clique duas vezes na pasta do nó XML desejada para inserir seu caminho qualificado no local do cursor. Para obter mais informações, consulte as instruções em inserir caminhos de nó XML.

Exemplos

map = GetSourceInstanceMap([Values$Value.]);
v = map["Attr1"];
// Returns the value of the "Attr1" attribute

GetSourceInstanceElementMap

Declaração

dictionary GetSourceInstanceElementMap(node n)

Sintaxe

GetSourceInstanceElementMap(<n>)

Parâmetros Necessários

  • n: Uma expressão de caminho de referência de string para um nó na transformação atual

Descrição

Retorna um dicionário (mapa) contendo o valor do subelemento de um nó de elemento.

Como alternativa a essa função, consulte GetSourceInstanceElementArray.

Para inserir um n path na função, clique duas vezes na pasta do nó XML desejada para inserir seu caminho qualificado no local do cursor. Para obter mais informações, consulte as instruções em inserir caminhos de nó XML.

Exemplos

map = GetSourceInstanceElementMap([Values$Value.]);
v = map["e1"];
// Returns the value of the "e1" sub-element

HasKey

Declaração

bool HasKey(dictionary dict, string key)

Sintaxe

HasKey(<dict>, <key>)

Parâmetros Necessários

  • dict: Um dicionário existente
  • key: Uma chave para verificar no dicionário

Descrição

Verifica se um dicionário contém uma chave especificada. devoluções false se o primeiro argumento não for um dicionário ou se a chave não foi encontrada. Como uma função equivalente que funciona para arrays, veja os exemplos do FindValue função.

Exemplos

// Update the value in a dictionary "myDictionary"
// only if the key already exists
If(HasKey(myDictionary, "key"),
    myDictionary["key"] = "value");

Map

Declaração

dictionary Map()

Sintaxe

Map()

Descrição

um pseudônimo para Dict. Veja a função Dict.

MapCache

Declaração

string MapCache(dictionary dict, string key, string value)

Sintaxe

MapCache(<dict>, <key>, <value>)

Parâmetros Necessários

  • dict: Um dicionário existente
  • key: Uma chave para verificar no dicionário
  • value: Um valor a ser usado (e armazenado) se a chave não estiver no dicionário

Descrição

Essa função armazena em cache um par chave/valor em um dicionário. Caso a chave já exista no dicionário, será retornado o valor correspondente; caso contrário, o terceiro argumento será avaliado e esse valor será armazenado no dicionário para a chave.

Exemplos

// Creating a dictionary "myDictionary"
// and caching values in it,
// if they don't already exist
myDictionary = Dict();
i=0;
a=MapCache(myDictionary, "key1", ++i);
b=MapCache(myDictionary, "key2", ++i);
c=MapCache(myDictionary, "key1", ++i);
result = i;
// The result will be
// result=2, a=1, b=2, and c=1
// as c's value will be retrieved
// rather than incremented

ReduceDimension

Declaração

array ReduceDimension(array arrayMultiD)

Sintaxe

ReduceDimension(<arrayMultiD>)

Parâmetros Necessários

  • arrayMultiD: Uma matriz multidimensional

Descrição

Dada uma matriz multidimensional com dimensões n, a função retorna uma matriz com dimensões n-1. A dimensão mais baixa da matriz de entrada desaparecerá e seus membros serão coletados para a próxima dimensão de nível.

Exemplos

prices = ReduceDimension(orders$company.order#.detail#.price);
// If orders$company.order#.detail#.price
// is a 2-dimensional source data element array,
// the function will return a one-dimensional array

a = {{"0_0", "0_1"}, {"1_0", "1_1"}};
result = ReduceDimension(a);
// result will be {0_0, 0_1, 1_0, 1_1}

RemoveKey

Declaração

bool RemoveKey(dictionary dict, string key)

Sintaxe

RemoveKey(<dict>, <key>)

Parâmetros Necessários

  • dict: Um dicionário existente
  • key: Uma chave para verificar no dicionário

Descrição

Remove um par chave-valor com uma chave específica de um dicionário. A chave deve ser uma string ou ter uma representação de string, e valores nulos não são permitidos. devoluções true se o par chave-valor foi removido e false se a chave não existisse.

Exemplos

// Removes a key-value pair if it
// exists in dictionary "myDictionary"
If(HasKey(myDictionary, "key"),
    RemoveKey(myDictionary, "key"));

SortArray

Declaração

void SortArray(array arrayToSort[, bool isAscending])

void SortArray(array arrayToSort, int index[, bool isAscending])

Sintaxe

SortArray(<arrayToSort>[, <isAscending>])

SortArray(<arrayToSort>, <index>[, <isAscending>])

Parâmetros Necessários

  • arrayToSort: Um array a ser ordenado
  • index: Para arrays multidimensionais, índice do array a ser classificado (padrão 0)

Parâmetros Opcionais

  • isAscending: Se o array for classificado em ordem crescente (o padrão)

Descrição

Classifica uma matriz por referência. O valor de retorno é indefinido e deve ser ignorado.

No primeiro formulário, o segundo parâmetro (opcional) especifica a ordem de classificação.

Na segunda forma, para arrays multidimensionais, a função classifica o array de acordo com um índice baseado em zero especificado no segundo parâmetro (obrigatório). Na segunda forma, o terceiro argumento (opcional) especifica a ordem de classificação.

A ordem de classificação padrão é crescente em ambos os formulários.

Depois que a função retornar, a matriz será classificada no local. Se especificado, será classificado de acordo com o índice.

A classificação múltipla da mesma matriz é possível aplicando o SortArray funcionar repetidamente.

Exemplos

// Sorting a one-dimensional array
arr1 = {"Carol", "Bob", "Alice"};
SortArray(arr1);
// arr1 is now {Alice, Bob, Carol}

// Sorting a two-dimensional array
arr2 = {{"a", 20, 1}, {"bc", 7, 12}, {"x", 20, 13}, {"d", 5, 4}};

// Sort arr2, order by third column, descending
SortArray(arr2, 2, false);
// arr2 is now {{x, 20, 13}, {bc, 7, 12}, {d, 5, 4}, {a, 20, 1}}

// Sort arr2, order by second column, ascending
SortArray(arr2, 1);
// arr2 is now {{d, 5, 4}, {bc, 7, 12}, {x, 20, 13}, {a, 20, 1}