Namespaces
Variants

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

From cppreference.net
C++
Strings library
std::basic_string
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)
(5)
basic_string & insert ( size_type index, const basic_string & str,
size_type s_index, size_type count ) ;
(jusqu'à C++14)
basic_string & insert ( size_type index, const basic_string & str,
size_type s_index, size_type count = npos ) ;
(depuis C++14)
(constexpr depuis C++20)
(6)
iterator insert ( iterator pos, CharT ch ) ;
(jusqu'en C++11)
iterator insert ( const_iterator pos, CharT ch ) ;
(depuis C++11)
(constexpr depuis C++20)
(7)
void insert ( iterator pos, size_type count, CharT ch ) ;
(jusqu'en C++11)
iterator insert ( const_iterator pos, size_type count, CharT ch ) ;
(depuis C++11)
(constexpr depuis C++20)
(8)
template < class InputIt >
void insert ( iterator pos, InputIt first, InputIt last ) ;
(jusqu'en C++11)
template < class InputIt >
iterator insert ( const_iterator pos, InputIt first, InputIt last ) ;
(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 dans 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 l'intervalle [ 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 de chaîne sv comme si 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 si par insert ( index, sv. data ( ) , sv. size ( ) ) .
Cette surcharge participe à la résolution de surcharge seulement 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 de chaîne sv comme si 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 seulement 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.

Table des matières

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

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