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

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