CKTIS / C++
Ajouter à une chaîne : std::basic_string::append
Choisissez la surcharge de `append` adaptée à la source : chaîne entière, tranche ou tampon de longueur connue. Ajoutez les séparateurs explicitement et conservez les caractères nuls intégrés.
Version : ISO C++23; implementation support may vary
Syntaxe
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, déclaré dans <string>, ajoute des éléments CharT à la fin d’une chaîne existante (std::string est la spécialisation pour char). La fonction renvoie *this par référence, ce qui permet d’enchaîner les appels. Contrairement à assign, elle ne remplace pas le contenu et n’insère aucun séparateur automatiquement. Pour un seul caractère, utilisez push_back(ch) ou += ch ; push_back renvoie void.
append(str) copie toute la chaîne. append(str, pos, count) copie au plus count éléments à partir de l’indice pos dans la source, sans dépasser sa fin. Omettez count ou passez npos pour copier jusqu’à la fin. Dans la source, pos == size() donne une tranche vide et pos > size() déclenche std::out_of_range. Les surcharges pour les types assimilables à une vue, disponibles depuis C++17, fonctionnent de la même façon. En C++23, les deux surcharges ne participent à la résolution de surcharge que si const T& est implicitement convertible en std::basic_string_view<CharT, Traits>. Seule la surcharge qui copie la source entière exige en plus que const T& ne soit pas implicitement convertible en const CharT*.
append(p) exige une séquence valide terminée par un caractère nul et copie jusqu’au premier caractère nul, exclu. append(p, count) copie exactement count éléments, y compris les caractères nuls intégrés. La fonction ne limite pas le nombre à la longueur du tampon : vérifiez-le par rapport à la taille réelle du tampon, car une plage invalide entraîne un comportement indéfini. Transmettez data() et size() à un récepteur qui accepte des données de longueur explicite.
append(count, ch) ajoute count copies de ch. Vous pouvez aussi fournir une plage valide d’itérateurs d’entrée [first, last) ou une liste d’initialisation. Ces surcharges de append sont constexpr depuis C++20. append_range(range) est une fonction membre distincte introduite en C++23 ; vérifiez que votre bibliothèque standard la prend en charge.
Un ajout peut invalider les pointeurs, références et itérateurs vers les éléments de la chaîne cible, et donc les vues sur son stockage. Récupérez-les après la modification. Un dépassement de max_size() déclenche std::length_error ; l’allocation peut aussi échouer. Si un appel à append lève une exception, la chaîne cible reste dans l’état où elle se trouvait juste avant cet appel.
Exemples
#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";
}
Résultat
accepted: 8 bytes
Le programme vérifie la présence du `=` obligatoire dans l’en-tête en comparant le résultat de `find` à `std::string::npos`. Il ajoute ensuite la tranche qui précède `=`, le séparateur explicite `:` et les trois octets de données. Le récepteur compare les huit octets, y compris le `\0` intégré. Sans longueur explicite, `append(payload)` ne copierait que `A`.
Leçons associées
- C++ · Leçon 58 · Avancé · Version : 3