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

basic_string & insert ( size_type index, const StringViewLike & t,

size_type t_index, size_type count = npos ) ;
(11) (desde C++17)
(constexpr desde C++20)

Inserta caracteres en la cadena.

1) Inserta count copias del carácter ch en la posición index .
2) Inserta la cadena de caracteres terminada en nulo apuntada por s en la posición index . La longitud de la cadena se determina por el primer carácter nulo usando Traits :: length ( s ) .
3) Inserta los caracteres en el rango [ s , s + count ) en la posición index . El rango puede contener caracteres nulos.
4) Inserta la cadena str en la posición index .
5) Inserta una cadena, obtenida mediante str. substr ( s_index, count ) en la posición index .
6) Inserta el carácter ch antes del carácter apuntado por pos .
7) Inserta count copias del carácter ch antes del elemento (si existe) apuntado por pos .
8) Inserta caracteres del rango [ first , last ) antes del elemento (si existe) apuntado por pos , como si fuera mediante insert ( pos - begin ( ) , basic_string ( first, last, get_allocator ( ) ) ) .

Esta sobrecarga no participa en la resolución de sobrecarga si InputIt no satisface LegacyInputIterator .

(desde C++11)
9) Inserta elementos desde la lista de inicializadores ilist antes del elemento (si existe) apuntado por pos .
10) Convierte implícitamente t a una vista de cadena sv como si fuera mediante std:: basic_string_view < CharT, Traits > sv = t ; , luego inserta los elementos de sv antes del elemento (si existe) apuntado por index , como si fuera mediante insert ( index, sv. data ( ) , sv. size ( ) ) .
Esta sobrecarga participa en la resolución de sobrecarga solo si std:: is_convertible_v < const StringViewLike & ,
std:: basic_string_view < CharT, Traits >> es true y std:: is_convertible_v < const StringViewLike & , const CharT * > es false .
11) Convierte implícitamente t a una string view sv como si fuera mediante std:: basic_string_view < CharT, Traits > sv = t ; , luego inserta, antes del elemento (si existe) apuntado por index , los caracteres del subvista [ t_index , t_index + count ) de sv .
  • Si el subvista solicitado excede el final de sv , o si count == npos , el subvista resultante es [ t_index , sv. size ( ) ) .
  • Si t_index > sv. size ( ) , o si index > size ( ) , std::out_of_range es lanzada.
Esta sobrecarga participa en la resolución de sobrecarga solo si std:: is_convertible_v < const StringViewLike & ,
std:: basic_string_view < CharT, Traits >> es true y std:: is_convertible_v < const StringViewLike & , const CharT * > es false .

Si pos no es un iterador válido en * this , el comportamiento es indefinido.

Contenidos

Parámetros

index - posición en la que se insertará el contenido
pos - iterador antes del cual se insertarán los caracteres
ch - carácter a insertar
count - número de caracteres a insertar
s - puntero a la cadena de caracteres a insertar
str - cadena a insertar
first, last - rango que define los caracteres a insertar
s_index - posición del primer carácter en str a insertar
ilist - std::initializer_list para insertar los caracteres desde
t - objeto (convertible a std::basic_string_view ) para insertar los caracteres desde
t_index - posición del primer carácter en t a insertar
Requisitos de tipo
-
InputIt debe cumplir con los requisitos de LegacyInputIterator .

Valor de retorno

1-5) * this
6-9) Un iterador que se refiere a la copia del primer carácter insertado o pos si no se insertaron caracteres ( count == 0 o first == last o ilist. size ( ) == 0 )
10,11) * this

Excepciones

1-4,10) Lanza std::out_of_range si index > size ( ) .
5) Lanza std::out_of_range si index > size ( ) o si s_index > str. size ( ) .
11) Lanza std::out_of_range si index > size ( ) o si t_index > sv. size ( ) .

En todos los casos, lanza std::length_error si size ( ) + ins_count > max_size ( ) donde ins_count es el número de caracteres que serán insertados.

En todos los casos, si std:: allocator_traits < Allocator > :: allocate lanza una excepción, esta es relanzada.

(desde C++20)

Si se lanza una excepción por cualquier razón, esta función no tiene efecto ( strong exception safety guarantee ).

Ejemplo

Ejecutar este código 
#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);
}

Informes de defectos

Los siguientes informes de defectos que modifican el comportamiento se aplicaron retroactivamente a los estándares de C++ publicados anteriormente.

DR Aplicado a Comportamiento publicado Comportamiento correcto
LWG 7 C++98 la sobrecarga (8) hacía referencia a una sobrecarga inexistente hace referencia correctamente a la sobrecarga (4)
LWG 847 C++98 no existía garantía de seguridad de excepciones se añadió garantía de seguridad de excepciones fuerte
LWG 2946 C++17 la sobrecarga (10) causaba ambigüedad en algunos casos se evitó convirtiéndola en plantilla

Véase también

(C++23)
inserta un rango de caracteres
(función miembro pública)
añade caracteres al final
(función miembro pública)
añade un carácter al final
(función miembro pública)