std::basic_string<CharT,Traits,Allocator>::append

basic_string& append( size_type count, CharT ch );	(1)	(constexpr depuis C++20)
basic_string& append( const CharT* s, size_type count );	(2)	(constexpr depuis C++20)
basic_string& append( const CharT* s );	(3)	(constexpr depuis C++20)
template< class SV > basic_string& append( const SV& t );	(4)	(depuis C++17) (constexpr depuis C++20)
template< class SV > basic_string& append( const SV& t, size_type pos, size_type count = npos );	(5)	(depuis C++17) (constexpr depuis C++20)
basic_string& append( const basic_string& str );	(6)	(constexpr depuis C++20)
basic_string& append( const basic_string& str, size_type pos, size_type count );	(7)	(jusqu'à C++14)
basic_string& append( const basic_string& str, size_type pos, size_type count = npos );	(7)		(depuis C++14) (constexpr depuis C++20)
template< class InputIt > basic_string& append( InputIt first, InputIt last );	(8)	(constexpr depuis C++20)
basic_string& append( std::initializer_list<CharT> ilist );	(9)	(depuis C++11) (constexpr depuis C++20)

Ajoute des caractères supplémentaires à la chaîne.

1) Ajoute count copies du caractère ch.

2) Ajoute les caractères de l'intervalle [s, s + count).

Si [s, s + count) n'est pas un intervalle valide, le comportement est indéfini.

3) Équivalent à return append(s, Traits::length(s));.

4,5) Ajoute les caractères d'une vue de chaîne sv construite à partir de t.

Si seul t est fourni, tous les caractères de sv sont ajoutés.
Si pos est également fourni :
- Si count est égal à npos, tous les caractères de sv à partir de pos sont ajoutés.
- Sinon, les std::min(count, sv.size() - pos) caractères de sv à partir de pos sont ajoutés.

Ces surcharges ne participent à la résolution de surcharge que si toutes les conditions suivantes sont satisfaites :

std::is_convertible_v<const SV&, std::basic_string_view<CharT, Traits>> est true.
std::is_convertible_v<const SV&, const CharT*> est false.

4) Équivalent à std::basic_string_view<CharT, Traits> sv = t;
return append(sv.data(), sv.size());.

5) Équivalent à std::basic_string_view<CharT, Traits> sv = t;
return append(sv.substr(pos, count));.

6,7) Ajoute les caractères d'une autre chaîne str.

Si seul str est fourni, tous ses caractères sont ajoutés.
Si pos est également fourni :
- Si count est égal à npos, tous les caractères de str à partir de pos sont ajoutés.
- Sinon, les std::min(count, str.size() - pos) caractères de str à partir de pos sont ajoutés.

6) Équivalent à return append(str.data(), str.size());.

7) Équivalent à return append(std::basic_string_view<CharT, Traits>
(str).substr(pos, count));.

(depuis C++20)

8) Équivalent à return append(basic_string(first, last, get_allocator()));.

Cette surcharge a le même effet que la surcharge (1) si `InputIt` est un type entier.	(jusqu'à C++11)
Cette surcharge ne participe à la résolution de surcharge que si `InputIt` satisfait aux exigences de LegacyInputIterator.	(depuis C++11)

9) Équivalent à return append(ilist.begin(), ilist.size());.

Paramètres

count	-	nombre de caractères à ajouter
ch	-	valeur du caractère à ajouter
s	-	pointeur vers la chaîne de caractères à ajouter
t	-	objet convertible en std::basic_string_view avec les caractères à ajouter
pos	-	index du premier caractère à ajouter
str	-	chaîne à ajouter
first, last	-	plage de caractères à ajouter
ilist	-	liste d'initialisation avec les caractères à ajouter

Valeur de retour

* this

Complexité

Il n'existe aucune garantie de complexité standard, les implémentations typiques se comportent de manière similaire à std::vector::insert() .

Exceptions

Si l'opération devait entraîner le dépassement de size() au-delà de max_size() , lève std::length_error .

5) Si pos > sv. size ( ) est true , lance std::out_of_range .

7) Si pos > str. size ( ) est true , lève std::out_of_range .

Si une exception est levée pour quelque raison que ce soit, cette fonction n'a aucun effet ( garantie forte de sûreté face aux exceptions ).

Exemple

Exécuter ce code

#include <cassert>
#include <string>
int main()
{
    std::string str = "std::string";
    const char* cptr = "C-string";
    const char carr[] = "range";
    std::string result;
    // 1) Ajouter un caractère 3 fois.
    // Note : C'est la seule surcharge acceptant les « CharT ».
    result.append(3, '*');
    assert(result == "***");
    // 2) Ajouter une chaîne C de longueur fixe
    result.append(cptr, 5);
    assert(result == "***C-str");
    // 3) Ajouter une chaîne C terminée par un caractère nul
    // Note : Comme « append » retourne *this, nous pouvons enchaîner les appels.
    result.append(1, ' ').append(cptr);
    assert(result == "***C-str C-string");
    // 6) Ajouter une chaîne entière
    result.append(1, ' ').append(str);
    assert(result == "***C-str C-string std::string");
    // 7) Ajouter une partie d'une chaîne
    result.append(str, 3, 2);
    assert(result == "***C-str C-string std::string::");
    // 8) Ajouter une plage
    result.append(&carr[2], &carr[3]);
    assert(result == "***C-str C-string std::string::n");
    // 9) Ajouter une liste d'initialisation
    result.append({'p', 'o', 's'});
    assert(result == "***C-str C-string std::string::npos");
}

Rapports de défauts

Les rapports de défauts modifiant le comportement suivants ont été appliqués rétroactivement aux normes C++ précédemment publiées.

DR	Appliqué à	Comportement publié	Comportement corrigé
LWG 847	C++98	il n'y avait aucune garantie de sécurité des exceptions	garantie de sécurité forte des exceptions ajoutée
LWG 2250	C++98	le comportement de la surcharge (7) était indéfini si pos > str. size ( ) est true	lève toujours une exception dans ce cas
LWG 2788	C++98	la surcharge (8) utilisait un allocateur construit par défaut pour construire la chaîne temporaire	obtient l'allocateur à partir de get_allocator()
LWG 2946	C++17	la surcharge (4) provoque une ambiguïté dans certains cas	évitée en la rendant template

Voir aussi

append_range (C++23)	ajoute une plage de caractères à la fin (fonction membre publique)
operator+=	ajoute des caractères à la fin (fonction membre publique)
strcat	concatène deux chaînes de caractères (fonction)
strncat	concatène un certain nombre de caractères de deux chaînes (fonction)
wcscat	ajoute une copie d'une chaîne large à une autre (fonction)
wcsncat	ajoute un certain nombre de caractères larges d'une chaîne large à une autre (fonction)

Support du compilateur
Environnement libre et hébergé
Langage
Bibliothèque standard
En-têtes de la bibliothèque standard
Exigences nommées
Macros de test de fonctionnalités (C++20)
Bibliothèque de support du langage
Bibliothèque de concepts (C++20)
Bibliothèque de diagnostics
Bibliothèque de gestion de la mémoire
Bibliothèque de métaprogrammation (C++11)
Bibliothèque d'utilitaires généraux
Bibliothèque de conteneurs
Bibliothèque d'itérateurs
Bibliothèque de plages (C++20)
Bibliothèque d'algorithmes
Bibliothèque de chaînes
Bibliothèque de traitement de texte
Bibliothèque numérique
Bibliothèque de date et heure
Bibliothèque d'entrée/sortie
Bibliothèque du système de fichiers (C++17)
Bibliothèque de support de la concurrence (C++11)
Bibliothèque de contrôle d'exécution (C++26)
Spécifications techniques
Index des symboles
Bibliothèques externes

Classes
basic_string
basic_string_view (C++17)
char_traits

fr.cppreference.net

Namespaces

Variants