Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / C++

std::vector::insert — inserir elementos num vetor

Insere um valor, várias cópias, uma lista de inicialização ou um intervalo de iteradores antes de uma posição. Usa o iterador devolvido e identifica o que fica inválido.

Versão: ISO C++23; implementation support may vary

Sintaxe

/* <vector>, public members of std::vector<T, Allocator> in C++23 */
constexpr iterator insert(const_iterator pos, const T& value);
constexpr iterator insert(const_iterator pos, T&& value);
constexpr iterator insert(const_iterator pos, size_type count, const T& value);
template<class InputIt>
constexpr iterator insert(const_iterator pos, InputIt first, InputIt last);
constexpr iterator insert(const_iterator pos, std::initializer_list<T> values);

std::vector::insert é uma função membro de <vector> que modifica o vetor v, inserindo elementos antes de pos. O parâmetro pos, do tipo const_iterator, tem de indicar uma posição válida em v: v.cbegin() permite inserir no início e v.cend() permite acrescentar no fim. A função devolve um iterator para o primeiro elemento inserido ou para a mesma posição que pos se nada for inserido. Não desreferencies o resultado se for igual a v.end().

insert(pos, value) com const T& copia um valor, enquanto a sobrecarga com T&& permite mover a partir de um rvalue. insert(pos, count, value) insere count cópias e insert(pos, {a, b}) insere os elementos da lista por ordem. T tem de cumprir os requisitos de construção e atribuição da sobrecarga escolhida; não esperes que as sobrecargas de cópia funcionem com um tipo que só admite movimento.

insert(pos, first, last) lê um intervalo semiaberto válido [first, last), excluindo last. Os iteradores normais de outro vetor permitem copiar os seus elementos. Aplicar std::make_move_iterator aos dois extremos permite mover a partir de elementos modificáveis da origem, se o tipo o permitir. Não uses iteradores do vetor de destino como origem: o comportamento é indefinido mesmo que haja capacidade suficiente. Se for preciso, copia primeiro o intervalo para outro contentor. insert_range(pos, range) é uma função membro distinta de C++23; a sua disponibilidade depende da implementação da biblioteca.

Se o novo tamanho exceder a capacidade anterior, a realocação invalida todos os iteradores, ponteiros e referências preexistentes do vetor de destino, incluindo o antigo end(). Se houver inserção de elementos sem realocação, só permanecem válidos os que antecedem o ponto de inserção; o antigo end() também fica inválido. Usa o iterador devolvido ou obtém novos iteradores. Com realocação, o custo é linear no tamanho resultante; sem realocação, é linear na soma do número de elementos inseridos e da distância de pos ao fim.

Nem todas as exceções deixam o vetor inalterado. Uma falha na alocação não modifica o vetor, mas não há uma garantia geral para exceções na cópia, no movimento ou na atribuição de elementos, nem nas operações dos iteradores de entrada. Ao inserir um único elemento no fim, uma exceção deixa o vetor inalterado se T for Cpp17CopyInsertable nesse vetor ou se std::is_nothrow_move_constructible_v<T> for verdadeiro. Caso contrário, se o construtor de movimento de um tipo que não cumpre Cpp17CopyInsertable lançar uma exceção, os efeitos não são especificados.

Exemplos

#include <iostream>
#include <vector>

int main() {
    std::vector<int> metrics{10, 40};
    const std::vector<int> batch{20, 30};

    const auto first = metrics.insert(metrics.cbegin() + 1,
                                      batch.begin(), batch.end());

    std::cout << "first inserted: " << *first << '\n';
    std::cout << "metrics:";
    for (int value : metrics) {
        std::cout << ' ' << value;
    }
    std::cout << "\nsize: " << metrics.size() << '\n';
}

Resultado

first inserted: 20
metrics: 10 20 30 40
size: 4

`batch` é um vetor separado. Os seus elementos ficam antes de `40`; `*first` vale `20` e `metrics.size()` vale `4`. O resultado apresentado não depende de haver ou não realocação.

Lições relacionadas

  • C++ · Lição 14 · Avançado · Versão: 3

Fontes