Matrizes

Uma matriz é uma estrutura de dados que armazena um grupo de valores. Matrizes são úteis quando você tem uma lista de itens que são de tipos parecidos. Por exemplo, listas de códigos postais, números de telefone ou nomes de clientes.

Há dois tipos de matriz que você pode usar no Studio:

• Matrizes de string: Strings delimitadas por barras verticais (|) em uma variável. Elas armazenam valores de string, que podem ser compostas por caracteres alfanuméricos.
• Matrizes dinâmicas: Matrizes que são armazenadas em objetos de dados dinâmicos.

Se você tem uma lista onde os dados são todos de tipos diferentes de informação sobre uma única entidade, um objeto de dados dinâmicos é uma estrutura de dados mais apropriada para uso. Uma comparação de matrizes e objetos está disponível na página da ajuda Estruturas de dados.

Principais fatos sobre matrizes

• Uma matriz deve ter pelo menos dois elementos. Uma matriz com apenas um elemento aparece como uma variável regular. Ela ainda é uma matriz e você pode chamá-la como uma matriz. O mesmo se aplica para matrizes dinâmicas.

• No Studio, índices de matriz começam por 1.

• Algumas funções estão disponíveis para uso com matrizes, como index() e indexof().

• Você pode usar qualquer delimitador com matrizes de string. No entanto, para ser lida de forma nativa, uma matriz de string deve usar um caractere de barra vertical (|) como o delimitador.

Experimente

Baixe o script de exemplos de matriz e importe-o para o Studio. Muitos dos exemplos desta página de ajuda estão disponíveis nas ações Snippet no script de exemplo. É possível abrir a janela do editor Snippet e executar o depurador para ver o exemplo.

Resumo de sintaxe de matriz

Crie uma matriz de string com uma das seguintes sintaxes.

Atribua uma valor para cada elemento usando seus índices:

ASSIGN <var>[<index1>] = "<value1>"

ASSIGN <var>[<index2>] = "<value2>"

ASSIGN <var>[<index3>] = "<value3>"

Atribua todos os valores de elemento a uma variável em uma string delimitada por barra vertical:

ASSIGN <var> = "<value1> | <value2> | <value3>"

Crie uma matriz dinâmica com a seguinte sintaxe:

DYNAMIC <object>

ASSIGN <object>.<member>[<index>].<sub-member>= "value"

Formulários adicionais de matrizes dinâmicas são suportados.

Para se referir a um elemento específico em uma matriz de string, use esta sintaxe:

<var>[index]

Para se referir a um elemento específico em uma matriz dinâmica, use esta sintaxe:

ASSIGN <var> = <object>.<member>[<index>].<arrayElement>

Elementos e índices

Os valores que uma matriz armazena são chamados elementos. O script monitora a ordem dos elementos na matriz. Todo elemento em uma matriz tem um identificador numérico, chamado número de índice. O índice é atribuído automaticamente a cada elemento com base na sua posição na matriz. Se reordenar, adicionar ou remover elementos, seus índices podem ser mudados.

No Studio, índices de matriz começam por 1. Índices devem ser números inteiros positivos. Você precisa saber o índice para interagir com um elemento específico na matriz. Caso não saiba qual é o índice de um elemento, você pode usar a função indexof() para determiná-lo.

Fazer referência a um elemento individual de matriz de string

Quando se referir a um elemento individual de uma matriz de string, use esta sintaxe: <arrayElement>[<index>]. Você pode usar esta sintaxe em qualquer lado do sinal de igual. Por exemplo, você pode usá-la para atribuir um valor a um elemento ou para se referir a um valor de elemento, como quando atribui um valor a outra variável.

Por exemplo:

ASSIGN heroes[1] = "Beowulf"
ASSIGN heroes[2] = "Sir Gawain" 
ASSIGN heroes[3] = "Byrhtnoth"

Neste exemplo, o índice de Beowulf é 1, o de Sir Gawain é 2 e Byrtnoth é 3. Esses elementos têm os mesmos índices ao se olhar para a matriz no formato delimitado por barra vertical: name = "Beowulf|Sir Gawain|Byrhtnoth". Para determinar os índices de uma matriz neste formato, conte os elementos da esquerda para a direita, começando por 1.

Índices são preenchidos em ordem numérica

Índices são preenchidos um a um em ordem numérica. Se você se referir a um índice que atualmente não existe na matriz, o script o criará e ele ficará vazio a não ser que atribua um valor a ele. O script cria índices que não existiam entre aquele que você referenciou e o último elemento anterior na matriz. Os elementos que o script adiciona para preenchimento estão vazios. Por exemplo:

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth" 
ASSIGN heroes[6] = "Lancelot"

A matriz resultante é heroes = "Beowulf|Sir Gawain|Byrhtnoth|||Lancelot". O script adicionou elementos para os índices 4 e 5, mas como nenhum valor foi atribuído a eles, eles estão vazios.

Da mesma forma, se tentar puxar um valor de um elemento que não existe, o elemento é criado. Todos os elementos entre aquele que você tentou referenciar e o último elemento anterior também são criados e estarão vazios.

Se um elemento vazio da matriz é referido em um contexto que espera um número, o script se comportará como se o valor fosse zero.

Determinar o próximo índice inutilizado

Para evitar criar elementos vazios desnecessários em uma matriz, você pode determinar o próximo índice inutilizado. Você deve contar os elementos na matriz e adicionar 1 ao número obtido pela contagem. Isso resulta no próximo número de índice aberto.

Para fazer isto, use a função size(). Por exemplo:

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"  
ASSIGN nextIndex = heroes.size() + 1
ASSIGN heroes[nextIndex] = Roland

Neste exemplo, heroes.size() retorna o número de elementos na matriz nome. O valor de totalNames é 3. Ao adicionar um a ele e usar a variável nextIndex no lugar do número de índice, você pode adicionar um elemento à matriz.

Você também pode usar a função count().

Matrizes de string

Matrizes de string podem ser definidas de duas formas. A primeira é nomeando explicitamente cada elemento individualmente. O exemplo a seguir mostra uma matriz de string contendo valores de texto que são definidos elemento por elemento.

ASSIGN heroes[1] = "Beowulf"
ASSIGN heroes[2] = "Sir Gawain" 
ASSIGN heroes[3] = "Byrhtnoth"

O número nos colchetes quadrados após o nome da matriz é o número de índice do elemento. Este é o identificador para cada elemento.

A segunda forma de definir uma matriz de string é com uma string delimitada por barra vertical, usando o caractere barra vertical (|) entre cada elemento. Este exemplo mostra a matriz do primeiro exemplo definida com uma string delimitada por barra vertical. Ao criar uma matriz de string delimitada por barra vertical, os valores do lado direito da instrução devem ser colocados entre aspas duplas.

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"

Não há diferença entre as funções e você pode usá-las de forma intercambiável. Ambos os métodos de definição da matriz de string produzem o mesmo resultado, uma variável que contém uma matriz de elementos.

Matrizes dinâmicas

Matrizes dinâmicas podem ter várias formas:

• O objeto de dados dinâmicos contém uma matriz. Cada elemento da matriz também é um membro do objeto.

  DYNAMIC beowulfLocations 
  ASSIGN beowulfLocations[1] = "Land of the Geats"
  ASSIGN beowulfLocations[2] = "Heorot" 
  ASSIGN beowulfLocations[3] = "Earnanæs"

• O objeto dinâmico contém um membro que armazena uma matriz. Os outros membros do objeto podem armazenar valores numéricos ou de string, ou eles podem ser outras matrizes.

  DYNAMIC beowulfCharacteristics 
  ASSIGN beowulfCharacteristics.foe[1].characteristics[1] = "Grendel"
  ASSIGN beowulfCharacteristics.foe[1].characteristics[2] = "son of Cain"
  ASSIGN beowulfCharacteristics.foe[2] = $"Grendel\'s mother" 
  ASSIGN beowulfCharacteristics.foe[3] = "Dragon"

• Uma matriz de string armazena elementos que contêm, cada um, um objeto de dados dinâmicos.

  DYNAMIC epicPoems
  ASSIGN epicPoems.poemName = "Beowulf"
  DYNAMIC heroes 
  ASSIGN heroes.heroName = "Beowulf"
  DYNAMIC monsters
  ASSIGN monsters.monsterName = "Grendel"
  ASSIGN oldEnglish[1] = epicPoems
  ASSIGN oldEnglish[2] = heroes
  ASSIGN oldEnglish[3] = monsters

  Você pode ver os conteúdos de objetos dinâmicos e da matriz de string na guia Variáveis em árvore na janela do editor Snippet quando executa o depurador.

  Este tipo de matriz dinâmica não pode ser usado quando você precisa que seu script trabalhe com outros sistemas, como quando na conexão com APIs. Os dados que a matriz de string arrmazena não podem ser serializados ou convertidos em strings JSON ou XML.

Fazer referência a um elemento de matriz por localização

Você pode referenciar um elemento em uma matriz de string ou dinâmica usando sua localização na matriz, especificada pelo índice dele. Por exemplo:

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"
ASSIGN currentName = heroes[2]

O valor de currentName é Sir Gawain.

Você pode usar uma variável no ligar do número de índice em qualquer lado do sinal de igual em uma instrução ASSIGN. Isto permite que você se refira a índices específicos sem codificar rigidamente o índice no script. Por exemplo:

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"
ASSIGN location = 2
ASSIGN currentHero = heroes[location]
ASSIGN nextIndex = heroes.count() + 1
ASSIGN heroes[nextIndex] = "Roland"

O valor de currentHero neste exemplo é Sir Gawain. As duas últimas linhas do exemplo acima mostram o uso de uma variável como o índice no lado esquerdo da instrução ASSIGN. Ela também demonstra o uso da função count() para retornar o número de elementos na matriz. Esta informação é usada para adicionar um novo elemento no próximo índice vazio.

Quando você usa uma variável para o número de índice, não é preciso usar chaves ao redor do nome da variável. O script espera um valor numérico entre os colchetes quadrados no nome da matriz. Ele assume que tudo que não é um número é uma variável, portanto ele procura uma variável por aquele nome. Deve haver uma declaração de variável correspondente onde você atribui um valor numérico. Se não houver uma, ele resultará no seguinte erro:

_ERR=Na linha 12 do snippet: índice de matriz deve ser >= 1.

Se o ramal Error para ação Snippet estiver conectado, o script o tomará quando esse erro ocorrer.

Usar FOREACH com uma matriz de string

Você pode usar uma instrução FOREACH com matrizes de string para iterar por cada elemento.

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth|Lancelot"
 FOREACH elem IN heroes 
{
   ASSIGN aName = elem 
}

Neste exemplo, elem e aName são atualizados com cada iteração. A variável elem armazena o elemento atual que o loop FOREACH está processando. O script atualiza aName com os conteúdos de elem. Ao fim de cada iteração, elem e aName armazenam o mesmo valor, mas no meio da iteração, elem armazena o novo valor e aName o valor antigo (ou nenhum valor, no caso do começo da primeira iteração).

Você pode ver isso claramente no FOREACH Loop with a String Array snippet no script de exemplos de matriz. Para ver a forma como as variáveis são atualizadas, avance pelo snippet linha após linha.

Usar FOR com uma matriz de string

Você pode usar um loop FOR com uma matriz de string para iterar pela matriz e executar uma ação definida por um número de vezes especificado.

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth|Lancelot"
FOR i = 1 TO heroes.count 
   {    
      item = "{heroes[i]}" 
   } 
        

O resultado deste exemplo é que Item atualiza após cada iteração do loop FOR com os conteúdos da matriz heroes na localização de índice especificada pelo valor de i. O loop FOR para de iterar quando chega ao fim da matriz de string, conforme indicado por heroes.count.

Você pode ver este loop no FOR Loop with a String Array snippet no script de exemplos de matriz.

Usar Funções com matrizes

Você pode usar funções com matrizes. Use o nome da matriz com o índice em colchetes quadrados e adicione o nome da função usando notação de ponto. Isso é mostrado no exemplo a seguir:

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"
ASSIGN miniHero = "{heroes[2].lower}"
ASSIGN yellyHero = "{heroes[2].upper}"

Os resultados deste exemplo são miniHero = sir gawain e yellyHero = SIR GAWAIN.

Nem todas as funções funcionam com todas as matrizes. Algumas funcionam apenas com determinados tipos de valores. Verifique os tipos com os quais a função que você quer usar trabalham.

Você pode usar funções com matrizes dinâmicas. No entanto, dependendo da matriz dinâmica específica e o que ela contém, você pode precisar usar a propriedade objeto especial.$value. Algumas funções não funcionarão em um objeto inteiro. Por exemplo, você não pode usar a função lower() em uma matriz de objetos. O script ignoraria a função se você tentasse isso. Nesses casso, você deve aplicar alternativas. Por exemplo, você pode copiar valores específicos de objetos na matriz para um valor separado. Você pode então usar lower() nos conteúdos da variável e, se necessário, copiar o valor convertido de volta ao objeto.

As funções na tabela a seguir são voltadas especificamente para trabalhar com matrizes. Você pode testar essas funções no Functions and Arrays snippet no script de exemplos de matriz.

Função	Descrição
count()	Retorna o número de elementos em uma matriz ou objeto.
index(indexValue)	Retorna o elemento da matriz do conteúdo da variável de acordo com o indexValue especificado.
indexof(text)	Retorna a posição de caractere do text especificado no conteúdo da variável.
size()	Retorna o número de elementos em uma matriz.
split(delimiter)	Converte o conteúdo de uma variável em uma string delimitada por barra que pode ser tratada como uma matriz. Substitui o delimiter especificado e existente por um caractere de barra.