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

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

Fontes