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

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.

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}