CKTIS / C++
std::vector::emplace_back — construir um elemento no fim do vetor
Constrói um elemento no fim do vetor a partir dos argumentos recebidos. Saiba o que a função devolve e quando as referências existentes ficam inválidas.
Versão: ISO C++23; implementation support may vary
Sintaxe
#include <vector>
// Member declaration inside std::vector<T, Allocator> (C++23):
template<class... Args>
constexpr reference emplace_back(Args&&... args);
// Call on a vector v:
v.emplace_back(args...);std::vector::emplace_back, declarado em <vector>, acrescenta um elemento no fim do vetor e aumenta size() em um se a chamada for bem-sucedida. Os parâmetros Args&&... são referências de encaminhamento: std::forward preserva a distinção entre lvalue e rvalue, mas encaminha um prvalue como xvalue. No modelo primário, o elemento de tipo T é construído diretamente na memória do vetor através de uma chamada a std::allocator_traits<Allocator>::construct com os argumentos encaminhados. T tem de cumprir EmplaceConstructible para esses argumentos e MoveInsertable para esse vetor, mesmo que já haja capacidade suficiente. A especialização std::vector<bool> não é obrigada a usar allocator_traits::construct para construir os seus valores.
emplace_back pode usar um construtor explicit sem que seja necessário criar um T temporário no local da chamada. Se já tiver um T, push_back exprime claramente a intenção de o copiar (const T&) ou de o passar para movimento (T&&). A construção no local não garante a ausência de cópias ou movimentos. Em C++11 e C++14, a função devolvia void; desde C++17, devolve uma reference para o novo elemento (T& no modelo primário, um objeto proxy em std::vector<bool>). É constexpr desde C++20, sujeita às regras da avaliação constante.
Acrescentar no fim demora tempo constante amortizado; uma chamada que realoque memória demora tempo linear no número de elementos. Se o novo tamanho exceder a capacity() anterior, a realocação invalida todos os ponteiros, referências e iteradores existentes para elementos, bem como o antigo end(). Sem realocação, só o antigo end() é invalidado. Uma chamada bem-sucedida a reserve(n) garante uma capacidade de pelo menos n, mas não altera size() nem cria elementos.
Se a inserção lançar uma exceção, o vetor normalmente não é alterado. No entanto, se a exceção vier do construtor de movimento de um T que não cumpra CopyInsertable para esse vetor, os efeitos não são especificados. Não aceda a elementos através de referências ou ponteiros invalidados.
Exemplos
#include <iostream>
#include <string>
#include <utility>
#include <vector>
struct Result {
std::string name;
int score;
explicit Result(std::string n, int s) : name(std::move(n)), score(s) {}
};
int main() {
std::vector<Result> results;
results.reserve(2);
std::cout << "size after reserve: " << results.size() << '\n';
auto& first = results.emplace_back("Ada", 40);
results.emplace_back("Lin", 35);
first.score += 2;
std::cout << "size after insertion: " << results.size() << '\n';
for (const auto& result : results) {
std::cout << result.name << ": " << result.score << '\n';
}
}
Resultado
size after reserve: 0 size after insertion: 2 Ada: 42 Lin: 35
`reserve(2)` não cria elementos, mas garante que nenhuma das duas inserções provoca uma realocação. Assim, `first` continua a referir-se ao primeiro resultado e, ao alterá-lo, a pontuação de Ada passa de 40 para 42.
Lições relacionadas
- C++ · Lição 18 · Avançado · Versão: 3
- C++ · Lição 32 · Avançado · Versão: 3
- C++ · Lição 36 · Avançado · Versão: 3
Fontes
- WG21 N4950 — Working Draft, Standard for Programming Language C++ (C++23)
- C++ working draft — [vector.modifiers]
- C++ working draft — [sequence.reqmts]
- C++ working draft — [container.alloc.reqmts]
- C++ working draft — [vector.capacity]
- C++ working draft — [vector.overview]
- C++ working draft — [vector.bool.pspc]