Namespaces
Variants

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

From cppreference.net
C++
Strings library
std::basic_string
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)
(7)
basic_string & append ( const basic_string & str,
size_type pos, size_type count ) ;
(jusqu'à C++14)
basic_string & append ( const basic_string & str,
size_type pos, size_type count = npos ) ;
(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 dans la plage [ 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 vaut 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 participent à la résolution de surcharge seulement si toutes les conditions suivantes sont satisfaites :
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 vaut 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 participe à la résolution de surcharge seulement si InputIt satisfait aux exigences de LegacyInputIterator .

(depuis C++11)
9) Équivalent à return append ( ilist. begin ( ) , ilist. size ( ) ) ; .

Table des matières

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

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