Funções de Dicionário e Array

Introdução

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

Diferença Entre Matrizes e Dicionários

Embora muito semelhantes em muitos aspectos como método de armazenamento de 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 possuem 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 os arrays 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 na forma como são recuperadas. Matrizes geralmente são melhores para conjuntos ordenados.

Definir e Recuperar Valores em Matrizes 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'];

Encontre Valores em Dicionários e Matrizes

Para os dicionários, o HasKey função permite testar se uma chave está presente. Para uma matriz, você pode usar o FindValue funcione de maneira semelhante, passando duas instâncias do array 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 Obrigatórios

• dict: Um dicionário existente
• key: Chave a ser usada 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 valor é 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á existisse e o valor dessa chave fosse atualizado. Se o primeiro argumento não estiver definido ou não for um dicionário, ele será inicializado como um dicionário vazio antes de o valor ser 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, este 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 apelido para Array. Veja a função Array.

CollectValues

Declaração

array CollectValues(dictionary dict, array names)

Sintaxe

CollectValues(<dict>, <names>)

Parâmetros Obrigatórios

• dict: Um dicionário existente
• names: Um conjunto de chaves a serem consultadas no dicionário

Descrição

Retorna uma matriz contendo os valores correspondentes aos nomes na matriz de argumentos, retornados na mesma ordem que as 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 onde o valor é recuperado com base em um valor-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 Obrigatórios

• dict: Um dicionário existente

Descrição

Retorna uma matriz de 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 Obrigató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 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 de um nó.

Para entrar em um n path na função, arraste e solte a pasta do nó XML desejada da guia Source Objects da aba de paleta de componentes de script para o script para inserir seu caminho qualificado no local do cursor ou insira seu caminho de referência manualmente. Para obter mais informações, consulte as instruções sobre inserir objetos de origem.

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 Obrigató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 entrar em um n path na função, arraste e solte a pasta do nó XML desejada da guia Source Objects da aba de paleta de componentes de script para o script para inserir seu caminho qualificado no local do cursor ou insira seu caminho de referência manualmente. Para obter mais informações, consulte as instruções sobre inserir objetos de origem.

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 Obrigató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 entrar em um n path na função, arraste e solte a pasta do nó XML desejada da guia Source Objects da aba de paleta de componentes de script para o script para inserir seu caminho qualificado no local do cursor ou insira seu caminho de referência manualmente. Para obter mais informações, consulte as instruções sobre inserir objetos de origem.

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 Obrigató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 entrar em um n path na função, arraste e solte a pasta do nó XML desejada da guia Source Objects da aba de paleta de componentes de script para o script para inserir seu caminho qualificado no local do cursor ou insira seu caminho de referência manualmente. Para obter mais informações, consulte as instruções sobre inserir objetos de origem.

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 Obrigató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 esta função, consulte GetSourceInstanceArray.

Para entrar em um n path na função, arraste e solte a pasta do nó XML desejada da guia Source Objects da aba de paleta de componentes de script para o script para inserir seu caminho qualificado no local do cursor ou insira seu caminho de referência manualmente. Para obter mais informações, consulte as instruções sobre inserir objetos de origem.

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 Obrigató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 esta função, consulte GetSourceInstanceElementArray.

Para entrar em um n path na função, arraste e solte a pasta do nó XML desejada da guia Source Objects da aba de paleta de componentes de script para o script para inserir seu caminho qualificado no local do cursor ou insira seu caminho de referência manualmente. Para obter mais informações, consulte as instruções sobre inserir objetos de origem.

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 Obrigató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 for 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 apelido 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 Obrigató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

Esta 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 da 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 Obrigatórios

• arrayMultiD: Uma matriz multidimensional

Descrição

Dado um array multidimensional com n dimensões, a função retorna um array com n-1 dimensões. A dimensão mais baixa da matriz de entrada desaparecerá e seus membros serão coletados para a dimensão do próximo 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 Obrigató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 Obrigatórios

• arrayToSort: Um array a ser classificado
• 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 um array 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 matrizes multidimensionais, a função classifica a matriz 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.

Após o retorno da função, o array será classificado no local. Se especificado, será classificado de acordo com o índice.

A classificação múltipla do mesmo array é 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}