ArrayInsert

Insere na matriz de destino o número especificado de elementos da matriz de origem, iniciando no índice especificado.

bool  ArrayInsert(
   void&        dst_array[],          // matriz de destino
   const void&  src_array[],          // matriz de origem
   uint         dst_start,            // índice na matriz de destino para inserir
   uint         src_start=0,          // índice na matriz de origem para copiar
   uint         count=WHOLE_ARRAY     // número de elementos a serem inseridos
   );

Parâmetros

dst_array[]

[in][out] Matriz receptor à qual você deseja adicionar elementos.

src_array[]

[in] Matriz de origem a partir da qual você deseja adicionar elementos

dst_start

[in] Índice na matriz de destino para inserir elementos da matriz de origem.

src_start=0

[in] Índice na matriz de destino a partir do qual são tomados os elementos da matriz de origem para serem inseridos.

count=WHOLE_ARRAY

[in]  Número de elementos adicionados a partir da matriz de origem. O valor WHOLE_ARRAY significa que serão inseridos todos os elementos do índice especificado até o final da matriz.

Valor retornado

Retorna true em caso de sucesso, caso contrário, false. Para obter informações de erro, chame a função GetLastError(). Possíveis erros:

  • 5052 — ERR_SMALL_ARRAY (parâmetros start e/ou count inválidos ou matriz de origem src_array[] está vazia),
  • 5056 — ERR_SERIES_ARRAY (a matriz não pode ser alterada, buffer de indicador),
  • 4006 — ERR_INVALID_ARRAY (a cópia para si próprio é inválida, ou as matrizes têm um tipo diferente ou possuem uma matriz de tamanho fixo, que contém objetos de uma classe ou de uma estrutura com um destruidor),
  • 4005 - ERR_STRUCT_WITHOBJECTS_ORCLASS (a matriz não contém estruturas POD, isto é, é impossível copiar),
  • erros de redimensionamento da matriz de destino dst_array[] — eles são dados na descrição da função ArrayRemove().

 

Observação

Se a função é usada para uma matriz de tamanho fixo, o tamanho da própria matriz de destino dst_array[] não muda, a partir da posição dst_start os elementos da matriz de destino são deslocados para a direita (o último count dos elementos cai), e os elementos são copiados da matriz de origem para o local liberado.

Você não pode inserir elementos em matrizes dinâmicas, que são designadas como buffers de indicador, através da função SetIndexBuffer(). Para buffers de indicador, todas as operações de redimensionamento são executadas pelo subsistema em execução do terminal.

Na matriz de origem, os elementos são copiados a partir do índice src_start. O tamanho da matriz de origem não é alterado. Os elementos adicionados à matriz de destino não são referências aos elementos da matriz de origem, o que significa que alterações subsequentes nos elementos em qualquer uma das matrizes não são refletidas na seguinte.

Exemplo:

//+------------------------------------------------------------------+
//| Script program start function                                    |
//+------------------------------------------------------------------+
void OnStart()
  {
//--- declara uma matriz de tamanho fixo e preenche com valores
   int array_dest[10];
   for(int i=0;i<10;i++)
     {
      array_dest[i]=i;
     }
   //--- matriz de origem   
   int array_source[10];
   for(int i=0;i<10;i++)
     {
      array_source[i]=10+i;
     }
//--- mostra matrizes antes de inserir elementos
   Print("Antes de chamar a ArrayInsert()");
   ArrayPrint(array_dest);
   ArrayPrint(array_source);
//--- insere 3 elementos da matriz de origem e mostra a nova composição da matriz de destino
   ArrayInsert(array_dest,array_source,4,0,3);
   Print("Depois de chamar a ArrayInsert()");
   ArrayPrint(array_dest);
/*
  Resultado de execução
   Antes de chamar a ArrayInsert()
   0 1 2 3 4 5 6 7 8 9
   Depois de chamar aArrayInsert()
   0 1 2 3 10 11 12 7 8 9
*/

Veja também

ArrayRemove, ArrayCopy, ArrayResize, ArrayFree