CKTIS / C++
std::basic_string::push_back — ajouter une unité de code
Ajoutez une unité de code à une chaîne, directement ou via un itérateur de sortie, sans perdre les caractères nuls inclus dans des données de longueur connue.
Version : ISO C++23; implementation support may vary
Syntaxe
constexpr void push_back(CharT ch);std::basic_string::push_back est une fonction membre non constante déclarée dans <string>, constexpr depuis C++20. Elle prend une valeur CharT par valeur (char pour std::string), l’ajoute à la fin, même si la chaîne est vide, augmente size() de un et renvoie void. Il n’y a pas de surcharge pour une chaîne ou une plage. s.append(1, ch) et s += ch ont le même effet, mais renvoient une référence à s. Pour ajouter une plage valide de n éléments à partir de p, utilisez s.append(p, n).
Un appel ajoute une unité de code, pas forcément un caractère Unicode entier, et n’encode ni ne valide le texte. Dans std::string, un '\0' ajouté fait partie du contenu et compte dans size(). Il se distingue du terminateur supplémentaire à s.data()[s.size()]. Pour des données contenant des caractères nuls, transmettez data() et size() à une interface qui respecte la longueur.
Le coût de l’ajout est constant en temps amorti, mais un appel peut allouer de la mémoire et déplacer le contenu existant. Un appel à reserve() avant une série d’ajouts peut réduire les allocations. La modification peut invalider pointeurs, références et itérateurs vers les éléments ; récupérez-les de nouveau ensuite, y compris le pointeur de data(). Un dépassement de max_size() déclenche std::length_error ; l’allocation peut aussi échouer. Si l’appel lève une exception, la chaîne reste inchangée.
std::back_inserter(s), fourni par <iterator>, crée un itérateur de sortie de type std::back_insert_iterator. Une affectation telle que *out++ = ch appelle s.push_back(ch) plutôt que d’écraser un élément existant. L’adaptateur désigne l’objet chaîne, non son tampon. La chaîne doit rester en vie pendant les écritures, et l’adaptateur ne supprime pas les allocations.
Exemples
#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';
}
Résultat
ID: size: 6 embedded NUL: true
`push_back(':')` ajoute le séparateur, puis `std::copy` ajoute via l’adaptateur les trois éléments de la plage de longueur explicite. Le contrôle de la taille protège la lecture à l’indice 4, qui confirme le caractère nul sans l’afficher.
Leçons associées
- C++ · Leçon 46 · Avancé · Version : 3
- C++ · Leçon 53 · Avancé · Version : 3
- C++ · Leçon 58 · Avancé · Version : 3
Sources
- [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++