Arrays em

Sobre Arrays

O JSON define um array como:

Um array é uma coleção ordenada de valores. Um array começa com [, o parêntese reto esquerdo, e termina com ], o parêntese reto direito. Os valores são separados por , (vírgula).

Os arrays podem conter zero ou mais valores JSON de qualquer tipo. Os elementos de um array não precisam de ser todos do mesmo tipo.

Criar arrays

Usa parênteses retos para reunir elementos num array.

[1, 2, 3]

Os elementos de um stream podem ser capturados num array, envolvendo-o em parênteses retos.

range(5)     # => a stream of 5 numbers
[range(5)]   # => the array [0, 1, 2, 3, 4]

Tamanho

A função length devolve o número de elementos de um array.

Indexação e fatias

A indexação dos arrays começa em zero.

Obtém um elemento de um array com uma expressão entre parênteses retos: .[2] obtém o terceiro elemento.

Os índices negativos contam de trás para a frente a partir do fim do array: .[-1] obtém o último elemento; .[-2] obtém o penúltimo.

Uma fatia é uma subsequência do array. .[10:15] devolve 5 elementos a partir do índice 10; o índice final não é incluído.

Há algumas funções de conveniência:

• first obtém o primeiro elemento.
• last obtém o último elemento.
• nth(n) obtém o elemento no índice n.

Conversão num stream de elementos

Há situações em que queremos obter os elementos de um array um a um, como um stream. Para isso, usamos .[].

Suponhamos que queremos um stream com os comprimentos das strings de um array.

["a", "be", "cat", "door"] | length        # => 4 -- the number of elements in the array
["a", "be", "cat", "door"] | .[] | length  # => 1, 2, 3, 4 -- the lengths of each element

Podemos colocar os parênteses retos vazios ao lado da expressão anterior, omitindo o pipe.

["a", "be", "cat", "door"][] | length      # => 1, 2, 3, 4 -- the lengths of each element
# ........................^^

Concatenação e subtração

Usa + para concatenar arrays.

[1, 2, 3] + [4, 5]          # => [1, 2, 3, 4, 5]

O operador - remove do array da esquerda os elementos que estão no array da direita.

[range(10)] - [2, 4, 6]     # => [0, 1, 3, 5, 7, 8, 9]

Iteração

O jq disponibiliza muitas funções que cobrem a iteração mais comum:

• map(expr) devolve um novo array onde a expr é aplicada a cada elemento, sucessivamente.

  [1, 2, 3] | map(. * 10)    # => [10, 20, 30]
  
  

• select(expr) é uma função que aplica a expr a um único valor; se o resultado da expressão for verdadeiro, o valor é devolvido; se o resultado for falso, nada é devolvido: não é null, é mesmo nada.

  Para aplicar isso a um array, combina o select com o map.

  [range(10)] | map(select(. % 2 == 0))    # => [0, 2, 4, 6, 8]
  

  Em alternativa, aplica o select a um stream e recolhe os resultados.

  [range(10) | select(. % 2 == 0)]    # => [0, 2, 4, 6, 8]
  

• any(condition) e all(condition) devolvem verdadeiro ou falso, consoante algum ou todos os elementos do array cumpram a condição.

  [1, 2, 3, 4] | any(. > 4)    # false
  [1, 2, 3, 4] | any(. >= 4)   # true
  
  [1, 2, 3, 4] | all(. >= 4)   # false
  [1, 2, 3, 4] | all(. <= 4)   # true
  

Pertença

Podemos testar se um array contém um elemento com index. Esta função devolve o índice do elemento indicado, se ele estiver no array; caso contrário, devolve null.

["carrots", "beef", "potatoes"] | index("beef")    # => 1
["carrots", "beef", "potatoes"] | index("bees")    # => null

Existe uma função inversa chamada IN (sim, em maiúsculas). O pormenor do IN é que o seu argumento não é um array, mas um stream.

"beef" | IN(["carrots", "beef", "potatoes"][])    # => true
"bees" | IN(["carrots", "beef", "potatoes"][])    # => false

Outras funções (consulta o manual para mais detalhes)

• O Ruby tem um método prático, each_with_index, que emparelha o valor do elemento com o seu índice. O Python tem enumerate. O jq tem algo semelhante, chamado to_entries. Esta função transforma o array num array de objetos {key: index, value: value}.

  [11, 22, 33, 44] | to_entries
  # => [{key: 0, value: 11}, {key: 1, value: 22}, {key: 2, value: 33}, {key: 3, value: 44}]
  

• sort e sort_by

• group_by

• min, max, min_by, max_by

• unique, unique_by

• flatten