CKTIS / C++
Acrescentar ao fim de uma cadeia: std::basic_string::append
Escolhe a sobrecarga de `append` de acordo com a origem: uma cadeia inteira, um excerto ou um buffer de comprimento conhecido. Acrescenta separadores explícitos e preserva os caracteres nulos internos.
Versão: ISO C++23; implementation support may vary
Sintaxe
In <string>, for std::basic_string<CharT, Traits, Allocator> dst (C++23):
dst.append(str); // whole basic_string
dst.append(str, pos, count = npos); // slice of a basic_string
dst.append(viewLike); // whole view
dst.append(viewLike, pos, count = npos); // slice of a view
dst.append(p); // null-terminated sequence
dst.append(p, count); // exactly count elements
dst.append(count, ch); // count copies of ch
dst.append(first, last); // valid input-iterator range [first, last)
dst.append({ch1, ch2}); // initializer list
All forms return basic_string&. The notation count = npos denotes a default argument, not an assignment at the call site. append_range(range) is a separate C++23 member.std::basic_string::append, declarado em <string>, acrescenta elementos CharT ao fim de uma cadeia existente (std::string é a especialização para char). Devolve *this por referência, o que permite encadear chamadas. Ao contrário de assign, não substitui o conteúdo existente nem insere separadores automaticamente. Para um só carácter, usa push_back(ch) ou += ch; push_back devolve void.
append(str) copia a cadeia inteira. append(str, pos, count) copia até count elementos a partir do índice pos na origem, sem passar do fim. Omite count ou passa npos para copiar até ao fim. Na origem, pos == size() dá um excerto vazio e pos > size() lança std::out_of_range. As sobrecargas para tipos compatíveis com uma vista, disponíveis desde C++17, funcionam da mesma forma. Em C++23, ambas só participam na resolução de sobrecargas se const T& for implicitamente convertível em std::basic_string_view<CharT, Traits>. Só a sobrecarga que copia a origem inteira exige também que const T& não seja implicitamente convertível em const CharT*.
append(p) exige uma sequência válida terminada por um carácter nulo e copia até ao primeiro nulo, sem o incluir. append(p, count) copia exatamente count elementos, incluindo os nulos internos. Não limita a contagem ao comprimento do buffer: compara-a com o tamanho real do buffer, pois um intervalo inválido resulta em comportamento indefinido. Passa data() e size() a um recetor que aceite dados com comprimento explícito.
append(count, ch) acrescenta count cópias de ch. Também podes passar um intervalo válido de iteradores de entrada [first, last) ou uma lista de inicialização. Estas sobrecargas de append são constexpr desde C++20. append_range(range) é uma função membro distinta introduzida em C++23; verifica se a tua biblioteca padrão a suporta.
Acrescentar dados pode invalidar ponteiros, referências e iteradores para os elementos da cadeia de destino e, por isso, as vistas sobre a sua memória. Obtém-nos novamente após a alteração. Ultrapassar max_size() lança std::length_error; a alocação de memória também pode falhar. Se uma chamada a append lançar uma exceção, a cadeia de destino fica como estava imediatamente antes dessa chamada.
Exemplos
#include <iostream>
#include <string>
#include <string_view>
int main() {
const std::string header = "kind=sample";
const char payload[] = {'A', '\0', 'B'};
const auto cut = header.find('=');
if (cut == std::string::npos) {
return 1;
}
std::string message;
message.append(header, 0, cut)
.append(1, ':')
.append(payload, sizeof payload);
const std::string_view received{message.data(), message.size()};
if (received != std::string_view{"kind:A\0B", 8}) {
return 2;
}
std::cout << "accepted: " << received.size() << " bytes\n";
}
Resultado
accepted: 8 bytes
O programa verifica se o cabeçalho contém o `=` obrigatório, comparando o resultado de `find` com `std::string::npos`. Depois acrescenta o excerto anterior a `=`, o separador explícito `:` e três bytes de dados. O recetor compara os oito bytes, incluindo o `\0` interno. Usar `append(payload)` sem indicar o comprimento copiaria apenas `A`.
Lições relacionadas
- C++ · Lição 58 · Avançado · Versão: 3