Funções de dicionário e array no Jitterbit Design Studio

Introdução

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

Diferença entre arrays e dicionários

Embora sejam muito semelhantes em muitos aspectos como um método de armazenamento de informações, arrays e dicionários diferem nessas características importantes:

• Arrays
  • Os elementos são ordenados
  • Os elementos são recuperados por posição
• Dicionários
  • Os elementos são armazenados sem considerar a ordem e não têm uma 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 têm 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. Dicionários são mais adequados para informações que variam na forma como são recuperadas. Arrays costumam ser melhores para conjuntos ordenados.

Definindo 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 arrays

Para dicionários, a função HasKey permite testar se uma chave está presente. Para um array, você pode usar a função FindValue 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 em string, com chaves nulas não permitidas. Qualquer valor é permitido, mesmo valores nulos.

Retorna true se o valor foi adicionado e a nova chave foi adicionada ao dicionário ou false se a chave já existia e o valor naquela chave foi 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 que o valor seja adicionado.

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

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 um array vazio. 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. Os arrays são baseados 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 alias 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 array de chaves a serem buscadas no dicionário

Descrição

Retorna um array contendo os valores correspondentes aos nomes no array de argumentos, retornados na mesma ordem que as chaves no array.

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 uma chave de string. Qualquer valor é permitido, até mesmo valores nulos. A chave deve ser uma string ou ter uma representação em string. Chaves nulas não são permitidas. Veja também a função AddToDict().

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 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 obrigató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 caminho n na função, clique duas vezes na pasta do nó XML desejado para inserir seu caminho qualificado na localização do seu cursor. Para mais informações, consulte as instruções sobre inserindo caminhos de nós 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 obrigató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 sub-elementos 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 caminho n na função, clique duas vezes na pasta do nó XML desejado para inserir seu caminho qualificado na localização do seu cursor. Para mais informações, consulte as instruções sobre inserindo caminhos de nós XML.

Examples

// 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

Declaration

array GetSourceInstanceArray(node n)

Syntax

GetSourceInstanceArray(<n>)

Required parameters

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

Description

Retorna um array contendo o valor do atributo de um nó de elemento. O valor no array é rotulado com o nome do atributo e pode ser recuperado tanto pelo seu índice quanto pelo seu nome, como em um elemento de dados de dicionário.

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

Para inserir um caminho n na função, clique duas vezes na pasta do nó XML desejado para inserir seu caminho qualificado na localização do seu cursor. Para mais informações, consulte as instruções sobre inserindo caminhos de nós 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 obrigató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 o valor do sub-elemento de um nó de elemento. O valor no array é rotulado com o nome do sub-elemento e pode ser recuperado tanto pelo seu índice quanto pelo seu nome, como no elemento de dados do dicionário.

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

Para inserir um caminho n na função, clique duas vezes na pasta do nó XML desejado para inserir seu caminho qualificado na localização do seu cursor. Para mais informações, veja as instruções sobre inserindo caminhos de nós 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 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, veja GetSourceInstanceArray.

Para inserir um caminho n na função, clique duas vezes na pasta do nó XML desejado para inserir seu caminho qualificado na localização do seu cursor. Para mais informações, veja as instruções sobre inserindo caminhos de nós XML.

Exemplos

map = GetSourceInstanceMap([Values$Value.]);
v = map["Attr1"];
// Retorna o valor do atributo "Attr1"

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 sub-elemento de um nó de elemento.

Como alternativa a esta função, veja GetSourceInstanceElementArray.

Para inserir um caminho n na função, clique duas vezes na pasta do nó XML desejado para inserir seu caminho qualificado na localização do seu cursor. Para mais informações, veja as instruções sobre inserindo caminhos de nós XML.

Examples

map = GetSourceInstanceElementMap([Values$Value.]);
v = map["e1"];
// Retorna o valor do sub-elemento "e1"

HasKey

Declaration

bool HasKey(dictionary dict, string key)

Syntax

HasKey(<dict>, <key>)

Required parameters

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

Description

Verifica se um dicionário contém uma chave especificada. Retorna false se o primeiro argumento não for um dicionário ou se a chave não for encontrada. Para uma função equivalente que funciona para arrays, veja os exemplos da função FindValue.

Examples

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

Map

Declaration

dictionary Map()

Syntax

Map()

Description

Um alias para Dict. Veja a função Dict.

MapCache

Declaration

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

Syntax

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

Required parameters

• 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 um par chave/valor em um dicionário. Se a chave já existir no dicionário, o valor correspondente será retornado; 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 obrigatórios

• arrayMultiD: Um array multidimensional

Descrição

Dado um array multidimensional com n dimensões, a função retorna um array com n-1 dimensões. A menor dimensão do array de entrada desaparecerá, e seus membros serão coletados para a próxima dimensão.

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 em string, e valores nulos não são permitidos. Retorna true se o par chave-valor foi removido e false se a chave não existia.

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 ordenado
• index: Para arrays multidimensionais, índice do array a ser ordenado (padrão 0)

Parâmetros opcionais

• isAscending: Se o array deve ser ordenado em ordem crescente (o padrão)

Descrição

Ordena um array por referência. O valor de retorno é indefinido e deve ser ignorado.

Na primeira forma, o segundo parâmetro (opcional) especifica a ordem de classificação.

Na segunda forma, para arrays multidimensionais, a função ordena 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 ambas as formas.

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

Várias ordenações do mesmo array são possíveis aplicando a função SortArray 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}