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

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)
basic_string& insert( size_type index, const basic_string& str, size_type s_index, size_type count );	(5)	(hasta C++14)
basic_string& insert( size_type index, const basic_string& str, size_type s_index, size_type count = npos );	(5)		(desde C++14) (constexpr desde C++20)
iterator insert( iterator pos, CharT ch );	(6)	(hasta C++11)
iterator insert( const_iterator pos, CharT ch );	(6)		(desde C++11) (constexpr desde C++20)
void insert( iterator pos, size_type count, CharT ch );	(7)	(hasta C++11)
iterator insert( const_iterator pos, size_type count, CharT ch );	(7)		(desde C++11) (constexpr desde C++20)
template< class InputIt > void insert( iterator pos, InputIt first, InputIt last );	(8)	(hasta C++11)
template< class InputIt > iterator insert( const_iterator pos, InputIt first, InputIt last );	(8)		(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 mediante el primer carácter nulo usando Traits::length(s).

3) Inserta los caracteres del 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 sobrecargas si InputIt no satisface LegacyInputIterator.

(desde C++11)

9) Inserta elementos de la lista de inicialización 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 sobrecargas 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 vista de cadena 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 de la subvista [t_index, t_index + count) de sv.

Si la subvista solicitada se extiende más allá del final de sv, o si count == npos, la subvista resultante es [t_index, sv.size()).
Si t_index > sv.size(), o si index > size(), se lanza std::out_of_range.

Esta sobrecarga participa en la resolución de sobrecargas 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 no está definido.

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

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

Soporte del compilador
Independiente y alojado
Lenguaje
Biblioteca estándar
Encabezados de la biblioteca estándar
Requisitos nombrados
Macros de prueba de características (C++20)
Biblioteca de soporte del lenguaje
Biblioteca de conceptos (C++20)
Biblioteca de diagnóstico
Biblioteca de gestión de memoria
Biblioteca de metaprogramación (C++11)
Biblioteca de utilidades generales
Biblioteca de contenedores
Biblioteca de iteradores
Biblioteca de rangos (C++20)
Biblioteca de algoritmos
Biblioteca de cadenas
Biblioteca de procesamiento de texto
Biblioteca numérica
Biblioteca de fecha y hora
Biblioteca de entrada/salida
Biblioteca del sistema de archivos (C++17)
Biblioteca de soporte de concurrencia (C++11)
Biblioteca de control de ejecución (C++26)
Especificaciones técnicas
Índice de símbolos
Bibliotecas externas

Clases
basic_string
basic_string_view (C++17)
char_traits

es.cppreference.net

Namespaces

Variants