Categorias:

Funções de dados semiestruturados e estruturados (Matriz/objeto)

ARRAY_INSERT

Retorna uma matriz contendo todos os elementos da matriz de origem, bem como o novo elemento.

Sintaxe

ARRAY_INSERT( <array> , <pos> , <new_element> )
Copy
Consulte também:

ARRAY_APPEND , ARRAY_PREPEND

Argumentos

array

A matriz de origem.

pos

Uma posição (baseada em zero) na matriz de origem. O novo elemento é inserido nesta posição. O elemento original desta posição (se houver) e todos os elementos subsequentes (se houver) são deslocados por uma posição para a direita na matriz resultante (isto é, a inserção na posição 0 tem o mesmo efeito que a utilização de ARRAY_PREPEND).

Uma posição negativa é interpretada como um índice da parte de trás da matriz (por exemplo, -1 resulta em inserção antes do último elemento da matriz).

new_element

O elemento a ser inserido. O novo elemento está localizado na posição pos. A ordem relativa dos outros elementos da matriz de origem é preservada.

Retornos

O tipo de dados do valor retornado é ARRAY.

Notas de uso

  • Quando você passa uma ARRAY estruturada para a função, a função retorna uma ARRAY estruturada do mesmo tipo.

  • Se array for uma ARRAY estruturada, o tipo do novo elemento deverá ser coercível ao tipo de ARRAY.

  • Se o valor absoluto de pos excede o número de elementos em array, elementos vazios adicionais são inseridos entre o novo elemento e os elementos da matriz de origem.

  • Para anexar ou preender elementos a uma matriz, você deve usar ARRAY_APPEND ou ARRAY_PREPEND em seu lugar.

Exemplos

Isto mostra um exemplo simples de inserção em uma matriz:

SELECT ARRAY_INSERT(ARRAY_CONSTRUCT(0,1,2,3),2,'hello');
+--------------------------------------------------+
| ARRAY_INSERT(ARRAY_CONSTRUCT(0,1,2,3),2,'HELLO') |
|--------------------------------------------------|
| [                                                |
|   0,                                             |
|   1,                                             |
|   "hello",                                       |
|   2,                                             |
|   3                                              |
| ]                                                |
+--------------------------------------------------+
Copy

Isto mostra uma inserção que utiliza um índice maior do que o número de elementos existentes na matriz.

SELECT ARRAY_INSERT(ARRAY_CONSTRUCT(0,1,2,3),5,'hello');
+--------------------------------------------------+
| ARRAY_INSERT(ARRAY_CONSTRUCT(0,1,2,3),5,'HELLO') |
|--------------------------------------------------|
| [                                                |
|   0,                                             |
|   1,                                             |
|   2,                                             |
|   3,                                             |
|   undefined,                                     |
|   "hello"                                        |
| ]                                                |
+--------------------------------------------------+
Copy

Isto mostra uma inserção que utiliza um índice negativo.

SELECT ARRAY_INSERT(ARRAY_CONSTRUCT(0,1,2,3),-1,'hello');
+---------------------------------------------------+
| ARRAY_INSERT(ARRAY_CONSTRUCT(0,1,2,3),-1,'HELLO') |
|---------------------------------------------------|
| [                                                 |
|   0,                                              |
|   1,                                              |
|   2,                                              |
|   "hello",                                        |
|   3                                               |
| ]                                                 |
+---------------------------------------------------+
Copy
Linguagem: Português