CKTIS / C++
std::basic_string::push_back — acrescentar uma unidade de código
Acrescente uma unidade de código a uma cadeia, diretamente ou através de um iterador de saída, preservando caracteres nulos em dados de comprimento conhecido.
Versão: ISO C++23; implementation support may vary
Sintaxe
constexpr void push_back(CharT ch);std::basic_string::push_back é uma função membro não const declarada em <string> e é constexpr desde C++20. Recebe um CharT por valor (char para std::string), acrescenta-o no fim mesmo de uma cadeia vazia, aumenta size() em um e devolve void. Não há sobrecargas para cadeias ou intervalos. s.append(1, ch) e s += ch têm o mesmo efeito, mas devolvem uma referência para s. Para acrescentar um intervalo válido de n elementos a partir de p, use s.append(p, n).
Uma chamada acrescenta uma unidade de código, não necessariamente um carácter Unicode completo, e não codifica nem valida o texto. Em std::string, um '\0' acrescentado faz parte do conteúdo e é contabilizado por size(). É distinto do terminador adicional em s.data()[s.size()]. Para dados com caracteres nulos no interior, passe data() e size() a uma interface que respeite o comprimento.
O acréscimo demora tempo constante amortizado, mas uma só chamada pode alocar memória e mover o conteúdo existente. Chamar reserve() antes de uma série de acréscimos pode reduzir as alocações. A modificação pode invalidar ponteiros, referências e iteradores para elementos; volte a obtê-los depois, incluindo o ponteiro de data(). Ultrapassar max_size() lança std::length_error; a alocação também pode falhar. Se a chamada lançar uma exceção, a cadeia fica inalterada.
std::back_inserter(s), de <iterator>, cria um iterador de saída do tipo std::back_insert_iterator. Uma atribuição como *out++ = ch chama s.push_back(ch) em vez de sobrescrever um elemento existente. O adaptador refere-se ao objeto da cadeia, não ao respetivo buffer. A cadeia tem de continuar a existir durante a escrita, e o adaptador não evita alocações.
Exemplos
#include <algorithm>
#include <iostream>
#include <iterator>
#include <string>
#include <string_view>
int main() {
constexpr std::string_view payload{"4\0" "2", 3};
std::string record{"ID"};
record.push_back(':');
std::copy(payload.begin(), payload.end(), std::back_inserter(record));
const bool has_embedded_nul = record.size() == 6 && record.data()[4] == '\0';
std::cout << record.substr(0, 3) << '\n'
<< "size: " << static_cast<unsigned long long>(record.size()) << '\n'
<< "embedded NUL: " << std::boolalpha << has_embedded_nul << '\n';
}
Resultado
ID: size: 6 embedded NUL: true
`push_back(':')` acrescenta o separador e `std::copy` usa o adaptador para acrescentar os três elementos do intervalo de comprimento explícito. A verificação do tamanho protege a leitura no índice 4, que confirma o carácter nulo sem o imprimir.
Lições relacionadas
- C++ · Lição 46 · Avançado · Versão: 3
- C++ · Lição 53 · Avançado · Versão: 3
- C++ · Lição 58 · Avançado · Versão: 3
Fontes
- [string.append] — basic_string::append and push_back
- [string.op.append] — basic_string::operator+=
- [string.require] — basic_string general requirements
- [basic.string.general] — basic_string storage and terminator
- [string.capacity] — basic_string size, capacity and reserve
- [back.insert.iterator] — back_insert_iterator and back_inserter
- std::basic_string<CharT,Traits,Allocator>::push_back — cppreference
- N4950 — Working Draft, Standard for Programming Language C++