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

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

Insère des caractères dans la chaîne.

1) Insère count copies du caractère ch à la position index.

2) Insère la chaîne de caractères terminée par un caractère nul pointée par s à la position index. La longueur de la chaîne est déterminée par le premier caractère nul en utilisant Traits::length(s).

3) Insère les caractères de la plage [s, s + count) à la position index. La plage peut contenir des caractères nuls.

4) Insère la chaîne str à la position index.

5) Insère une chaîne, obtenue par str.substr(s_index, count) à la position index.

6) Insère le caractère ch avant le caractère pointé par pos.

7) Insère count copies du caractère ch avant l'élément (s'il existe) pointé par pos.

8) Insère les caractères de la plage [first, last) avant l'élément (s'il existe) pointé par pos, comme par insert(pos - begin(), basic_string(first, last, get_allocator())).

Cette surcharge ne participe pas à la résolution de surcharge si InputIt ne satisfait pas LegacyInputIterator.

(depuis C++11)

9) Insère les éléments de la liste d'initialisation ilist avant l'élément (s'il existe) pointé par pos.

10) Convertit implicitement t en une vue chaîne sv comme par std::basic_string_view<CharT, Traits> sv = t;, puis insère les éléments de sv avant l'élément (s'il existe) pointé par index, comme par insert(index, sv.data(), sv.size()).

Cette surcharge participe à la résolution de surcharge uniquement si std::is_convertible_v<const StringViewLike&,
std::basic_string_view<CharT, Traits>> est true et std::is_convertible_v<const StringViewLike&, const CharT*> est false.

11) Convertit implicitement t en une vue chaîne sv comme par std::basic_string_view<CharT, Traits> sv = t;, puis insère, avant l'élément (s'il existe) pointé par index, les caractères de la sous-vue [t_index, t_index + count) de sv.

Si la sous-vue demandée dépasse la fin de sv, ou si count == npos, la sous-vue résultante est [t_index, sv.size()).
Si t_index > sv.size(), ou si index > size(), std::out_of_range est levée.

Cette surcharge participe à la résolution de surcharge uniquement si std::is_convertible_v<const StringViewLike&,
std::basic_string_view<CharT, Traits>> est true et std::is_convertible_v<const StringViewLike&, const CharT*> est false.

Si pos n'est pas un itérateur valide sur *this, le comportement est indéfini.

Paramètres

index	-	position à laquelle le contenu sera inséré
pos	-	itérateur avant lequel les caractères seront insérés
ch	-	caractère à insérer
count	-	nombre de caractères à insérer
s	-	pointeur vers la chaîne de caractères à insérer
str	-	chaîne à insérer
first, last	-	intervalle définissant les caractères à insérer
s_index	-	position du premier caractère dans str à insérer
ilist	-	std::initializer_list pour insérer les caractères depuis
t	-	objet (convertible en std::basic_string_view ) pour insérer les caractères depuis
t_index	-	position du premier caractère dans t à insérer
Exigences de type
- `InputIt` doit satisfaire aux exigences de LegacyInputIterator .

Valeur de retour

1-5) * this

6-9) Un itérateur qui fait référence à la copie du premier caractère inséré ou pos si aucun caractère n'a été inséré ( count == 0 ou first == last ou ilist. size ( ) == 0 )

10,11) * this

Exceptions

1-4,10) Lance std::out_of_range si index > size ( ) .

5) Lance std::out_of_range si index > size ( ) ou si s_index > str. size ( ) .

11) Lance std::out_of_range si index > size ( ) ou si t_index > sv. size ( ) .

Dans tous les cas, lance std::length_error si size ( ) + ins_count > max_size ( ) où ins_count est le nombre de caractères qui seront insérés.

Dans tous les cas, si std:: allocator_traits < Allocator > :: allocate lève une exception, elle est relancée.

(depuis C++20)

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 <iterator>
#include <string>
using namespace std::string_literals;
int main()
{
    std::string s = "xmplr";
    // insert(size_type index, size_type count, char ch)
    s.insert(0, 1, 'E');
    assert("Exmplr" == s);
    // insert(size_type index, const char* s)
    s.insert(2, "e");
    assert("Exemplr" == s);
    // insert(size_type index, string const& str)
    s.insert(6, "a"s);
    assert("Exemplar" == s);
    // insert(size_type index, string const& str,
    //        size_type s_index, size_type count)
    s.insert(8, " is an example string."s, 0, 14);
    assert("Exemplar is an example" == s);
    // insert(const_iterator pos, char ch)
    s.insert(s.cbegin() + s.find_first_of('n') + 1, ':');
    assert("Exemplar is an: example" == s);
    // insert(const_iterator pos, size_type count, char ch)
    s.insert(s.cbegin() + s.find_first_of(':') + 1, 2, '=');
    assert("Exemplar is an:== example" == s);
    // insert(const_iterator pos, InputIt first, InputIt last)
    {
        std::string seq = " string";
        s.insert(s.begin() + s.find_last_of('e') + 1,
            std::begin(seq), std::end(seq));
        assert("Exemplar is an:== example string" == s);
    }
    // insert(const_iterator pos, std::initializer_list<char>)
    s.insert(s.cbegin() + s.find_first_of('g') + 1, {'.'});
    assert("Exemplar is an:== example string." == s);
}

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 correct
LWG 7	C++98	la surcharge (8) faisait référence à une surcharge inexistante	fait référence correctement à la surcharge (4)
LWG 847	C++98	il n'y avait aucune garantie de sécurité d'exception	garantie de sécurité d'exception forte ajoutée
LWG 2946	C++17	la surcharge (10) provoquait une ambiguïté dans certains cas	évitée en la rendant template

Voir aussi

insert_range (C++23)	insère une plage de caractères (fonction membre publique)
append	ajoute des caractères à la fin (fonction membre publique)
push_back	ajoute un caractère à la fin (fonction membre publique)

Support des compilateurs
Freestanding 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 d'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