Funções de array: referência CXPDOC2-13716

Esta página mantém a referência da versão identificada como CXPDOC2-13716 no documento oficial capturado em 14 de maio de 2026, com atualização indicada de 22 de abril. O antigo endereço da fonte retorna 404; a sintaxe e as descrições abaixo foram confrontadas com a referência oficial de funções de array, disponível em 26 de setembro de 2026.

As funções de array transformam listas de dados: permitem buscar valores, remover duplicados, extrair propriedades, ordenar itens e converter estruturas. Esta referência reorganiza a documentação oficial do Make, consultada em 26 de setembro de 2026.

Nas assinaturas abaixo, o ponto e vírgula separa argumentos. Os colchetes em uma assinatura indicam um argumento opcional. Nomes como Contacts[] e Emails[] representam arrays mapeados do cenário, não texto que deva ser digitado literalmente no lugar dos seus dados.

Adicionar e combinar

add(array; value1; value2; ...) acrescenta os valores informados ao array e retorna o array resultante.

merge(array1; array2; ...) reúne dois ou mais arrays em um só.

flatten(array) cria um novo array concatenando elementos de subarrays. A documentação descreve o achatamento recursivo até a profundidade especificada e remete à referência de Array.prototype.flat. A assinatura publicada pelo Make nesta página mostra apenas o argumento array; não acrescente um parâmetro não documentado com base na API JavaScript.

Comparar arrays e localizar valores

arrayDiff(array1; array2) retorna os itens presentes no primeiro array e ausentes no segundo. Como exemplo conceitual, comparar a lista 1, 2, 3, 4 com a lista 3, 4, 5, 6 deixa 1 e 2. A ordem dos dois argumentos importa para essa diferença.

arrayIntersect(array1; array2) retorna os itens comuns aos dois arrays. Nas mesmas listas, os itens comuns são 3 e 4.

contains(array; value) verifica se o array contém o valor informado.

Os exemplos de listas acima explicam o resultado; para usar as funções no editor, mapeie os arrays reais nos argumentos.

Remover itens e duplicados

deduplicate(array) remove valores duplicados.

distinct(array; [key]) remove duplicados e permite comparar uma propriedade de objetos complexos. Use o nome bruto da propriedade em key e notação de ponto para propriedades aninhadas. A documentação indica índice 1 para o primeiro item nesse contexto.

Exemplo: distinct(Contacts[]; name) remove duplicados comparando o campo name dos contatos.

remove(array; value1; value2; ...) remove os valores indicados. Segundo a referência, essa função se aplica a arrays primitivos de texto ou números, não à remoção por propriedade em arrays de objetos.

Acessar itens e contar

first(array) retorna o primeiro elemento.

last(array) retorna o último elemento.

length(array) retorna a quantidade de itens.

keys(object) retorna um array com as propriedades do objeto ou do array fornecido.

Extrair propriedades com map

A assinatura é map(complex array; key; [key for filtering]; [possible values for filtering separated by a comma]).

A função extrai os valores de uma propriedade de um array complexo e retorna um array primitivo. Ela também permite filtrar os itens de origem. Use os nomes brutos das variáveis, não os rótulos traduzidos que aparecem na interface.

• map(Emails[]; email) extrai os valores da propriedade email.
• map(Emails[]; email; label; work,home) extrai os e-mails cujos itens têm label igual a work ou home.

Para entender a estrutura de entrada, consulte mapeamento de arrays.

Transformar o array em texto

join(array; separator) junta os itens em uma string, inserindo o separador escolhido entre eles. Use essa função quando o destino precisa de texto, em vez de uma lista estruturada.

Mudar a sequência ou selecionar um trecho

reverse(array) inverte a sequência: o primeiro item passa a ser o último, e vice-versa.

shuffle(array) reorganiza os elementos aleatoriamente.

slice(array; start; [end]) retorna um novo array com os itens selecionados. Aqui, o primeiro item tem índice 0. Não confunda essa convenção com a indicação de índice 1 usada em outros contextos de mapeamento da referência.

Ordenar com sort

A assinatura é sort(array; [order]; [key]).

As opções de ordem são:

• asc: ordem crescente, padrão. Para números, 1, 2, 3; para texto, a referência exemplifica A, B, C, a, b, c.
• desc: ordem decrescente.
• asc ci: ordem crescente sem diferenciar maiúsculas de minúsculas.
• desc ci: ordem decrescente sem diferenciar maiúsculas de minúsculas.

Use key para ordenar objetos por uma propriedade. Informe o nome bruto e use notação de ponto para propriedades aninhadas. A referência indica índice 1 para o primeiro item nesse contexto.

Exemplos com a ordem explicitada:

• sort(Contacts[]; asc; name): contatos por nome em ordem crescente.
• sort(Contacts[]; desc; name): contatos por nome em ordem decrescente.
• sort(Contacts[]; asc ci; name): contatos por nome, ignorando diferença de caixa.
• sort(Emails[]; asc; sender.name): e-mails pela propriedade aninhada sender.name.

Converter estruturas

toArray(collection) converte uma coleção em um array de coleções com pares de chave e valor.

toCollection(array; key; value) converte um array de objetos com pares de chave e valor em uma coleção, usando os campos informados.

Cuidados editoriais para aplicar os exemplos

Antes de mapear uma função, confira se a entrada é um array de valores simples ou de objetos. Preserve os identificadores das propriedades e separe corretamente os argumentos. Esta recomendação editorial e os exemplos de sintaxe não equivalem a testes executados por este site.

A captura CXPDOC2-13716 já incluía arrayDiff e arrayIntersect; ambas também constam na referência oficial consultada para esta edição. A página preserva o conjunto de funções documentado, sem tratar o antigo endereço da fonte como prova de indisponibilidade das funções.