Matrizes

As informações desta página de ajuda se aplicam tanto a Studio quanto a Desktop Studio.

Uma matriz é uma estrutura de dados que contém um grupo de valores. As Matrizes são úteis quando você tem uma lista de itens semelhantes em tipo. Por exemplo, listas de códigos de área, números de telefone ou nomes de clientes.

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

  • Arrays de strings: strings delimitadas por pipe 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ê tiver uma lista em que os dados são todos tipos diferentes de informações sobre uma única entidade, um objeto de dados dinâmicos é uma estrutura de dados mais adequada para usar. Uma comparação entre matrizes e objetos está disponível na página de ajuda Estruturas de dados.

Fatos Principais sobre Matrizes de chave

  • Uma matriz deve ter pelo menos dois elementos. Uma matriz com apenas um elemento aparenta ser uma variável comum. Ainda é uma matriz e você pode chamá-la como uma matriz. O mesmo se aplica para matrizes dinâmicas.
  • Em Studio, os índices de matriz começam em 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. Porém, para ser lido nativamente, uma matriz de strings deve usar um caractere de barra vertical como delimitador.

  • O tamanho máximo de matrizes em Studio é de 63 milhões de elementos. Exceder esse tamanho de matriz resulta no seguinte erro na variável __err em um rastreamento de script: Array index out of bounds. The current array index ([index]) exceeds the maximum allowed index (63000000).

Tente

Baixe o script de exemplos de Matriz e importe-o para Studio. Muitos dos exemplos desta página de ajuda estão disponíveis em ações Snippet no script de exemplo. Você pode abrir a janela do editor de Snippet e executar o depurador para ver o exemplo.

Resumo da 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 strings, use esta sintaxe:

 <var>[index]

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

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

Elementos e índices

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

Em Studio, os índices da matriz começam em 1. Índices devem ser números inteiros positivos. Você precisa conhecer o índice para interagir com um elemento específico na matriz. Você pode usar a indexof() função para determinar o índice de um elemento, caso não o conheça.

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

Ao se referir a um elemento individual de uma matriz de strings, use esta sintaxe: <arrayElement>[<index>]. Você pode usar essa sintaxe em qualquer um dos lados 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. Estes elementos têm os mesmos índices ao visualizar a matriz no formato delimitado por barras verticais: name = "Beowulf|Sir Gawain|Byrhtnoth".Para determinar os índices de uma matriz nesse formato, conte os elementos da esquerda para a direita, começando com 1.

Os índices são preenchidos em ordem numérica

Os índices são preenchidos um por um em ordem NUMÉRICA. Se você referenciar um índice que não existe atualmente na matriz, o script o criará e ele estará vazio, a menos que você atribua um valor a ele. O script cria todos os índices que não existem entre o que você referencia e o 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 de matriz vazio for referenciado em um contexto que espera um número, o script se comporta como se o valor fosse zero.

Determinar o próximo índice inutilizado

Para evitar a criação de elementos vazios desnecessários em uma matriz, você pode determinar o próximo índice não utilizado. Você deve contar os elementos na matriz e, em seguida, somar 1 a esse número. Isso resulta no próximo número de índice aberto.

Para isso, 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 name. O valor de totalNames é 3. Ao adicionar um a esse valor e usar a variável nextIndex no lugar do número do índice, você pode adicionar um elemento à matriz.

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

Matrizes de comando

Matrizes de string podem ser definidas de duas formas.A primeira é nomeando explicitamente cada elemento individualmente. O exemplo a seguir mostra uma matriz de cadeia de caracteres 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 entre colchetes após o nome da matriz é o número de índice do elemento. Este é o identificador para cada elemento.

A segunda maneira de definir uma matriz de strings é com uma string delimitada por barras verticais, usando um único caractere de barra vertical ( | ) entre cada elemento. Este exemplo mostra a matriz do primeiro exemplo definida como uma string delimitada por barras verticais. Quando você cria uma matriz de strings delimitada por barras verticais, 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 strings produzem o mesmo resultado, uma variável que contém uma matriz de elementos.

A utilização da palavra-chave ASSIGN ao declarar uma matriz de strings não é obrigatória. No entanto, usá-la pode ser útil. Incluir ASSIGN facilita a localização, usando a Busca Avançada, do local em seu script onde você introduziu a matriz. Sem ASSIGN, você deve pesquisar o nome da matriz. Os resultados da pesquisa conterão toda referência à matriz em seu script. Quando você inclui ASSIGN no termo de pesquisa, a pesquisa retorna somente os resultados em que a variável é explicitamente atribuída. Para declarar uma variável sem ASSIGN, use esta sintaxe: <name> = "<value>"

Matrizes Dinâmicas

Matrizes Dinâmicas podem ter vários formulários:

  • 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 de string ou numéricos, ou 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 visualizar o conteúdo dos objetos dinâmicos e da matriz de strings ao usar o depurador de Snippet.

    Esse tipo de matriz dinâmica não pode ser usado quando você precisa que seu script funcione com outros sistemas, como ao se conectar a API. Os dados que a matriz de strings contém não podem ser serializados ou convertidos em strings JSON ou XML.

Referência a um elemento de Matriz por Localização

Você pode fazer referência a um elemento em uma matriz de cadeia de caracteres ou matriz dinâmica usando sua localização na matriz, especificada pelo seu índice. 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 lugar do número de índice em qualquer um dos lados 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 índice no lado esquerdo da instrução ASSIGN.Isso também demonstra o uso da count() função 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 do índice, não é necessário usar chaves em volta do nome da variável. O script espera um valor numérico entre os colchetes 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 em que você atribua um valor numérico. Se não houver uma, ele resultará no seguinte erro:

_ERR=Na linha 12 do Snippet: o índice da Matriz deve ser >= 1.

Se o branch Erro da ação Snippet estiver conectado, o script o utilizará quando esse erro ocorrer.

Usar FOREACH com uma Matriz de string

Você pode usar uma instrução FOREACH com arrays de strings 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. No final de cada iteração, elem e aName contêm o mesmo valor, mas no meio da iteração, elem contém o novo valor e aName o valor antigo (ou nenhum valor, no caso do início da primeira iteração).

Você pode ver isso claramente no FOREACH Loop with a string Array snippet no Array Examples script. Para ver a forma como as variáveis são atualizadas, percorra o snippet linha por 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 é atualizado em cada iteração do loop FOR com o conteúdo da matriz heroes na localização de índice especificada pelo valor de i. O loop FOR para de iterar depois de atingir o final da matriz de strings, conforme indicado por heroes.count.

Você pode ver esse loop no snippet FOR Loop with a string Array no script Array Examples.

Usar funções com Matrizes

Você pode usar funções com matrizes. Use o nome da matriz com o índice entre colchetes e, em seguida, 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ê deseja usar funciona.

Você pode usar funções com matrizes dinâmicas. No entanto, dependendo da matriz dinâmica específica e do que ela contém, pode ser necessário usar a propriedade especial do objeto, .$value. Algumas funções não funcionam 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 dos objetos na matriz para uma variável separada. Você pode então usar lower() no conteúdo da variável e, se necessário, copiar o valor convertido de volta para o objeto.

As funções na tabela a seguir são voltadas especificamente para trabalhar com matrizes. Você testa essas funções no snippet Functions and Arrays no script Array Examples.

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 (texto)

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(delimitador)

Converte o conteúdo de uma variável em uma string delimitada por pipe que pode ser tratada como uma matriz. Substitui o delimiter especificado e existente por um caractere de barra.