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 desde C++20)
basic_string & append ( const CharT * s, size_type count ) ;
(2) (constexpr desde C++20)
basic_string & append ( const CharT * s ) ;
(3) (constexpr desde C++20)
template < class SV >
basic_string & append ( const SV & t ) ;
(4) (desde C++17)
(constexpr desde C++20)
template < class SV >

basic_string & append ( const SV & t, size_type pos,

size_type count = npos ) ;
(5) (desde C++17)
(constexpr desde C++20)
basic_string & append ( const basic_string & str ) ;
(6) (constexpr desde C++20)
(7)
basic_string & append ( const basic_string & str,
size_type pos, size_type count ) ;
(hasta C++14)
basic_string & append ( const basic_string & str,
size_type pos, size_type count = npos ) ;
(desde C++14)
(constexpr desde C++20)
template < class InputIt >
basic_string & append ( InputIt first, InputIt last ) ;
(8) (constexpr desde C++20)
basic_string & append ( std:: initializer_list < CharT > ilist ) ;
(9) (desde C++11)
(constexpr desde C++20)

Añade caracteres adicionales a la cadena.

1) Añade count copias del carácter ch .
2) Añade los caracteres en el rango [ s , s + count ) .
Si [ s , s + count ) no es un rango válido , el comportamiento es indefinido.
3) Equivalente a return append ( s, Traits :: length ( s ) ) ; .
4,5) Añade caracteres de una vista de cadena sv construida a partir de t .
  • Si solo se proporciona t , se añaden todos los caracteres en sv .
  • Si también se proporciona pos :
    • Si count es npos , se añaden todos los caracteres en sv comenzando desde pos .
    • De lo contrario, se añaden std:: min ( count, sv. size ( ) - pos ) caracteres en sv comenzando desde pos .
Estas sobrecargas participan en la resolución de sobrecarga solo si se cumplen todas las siguientes condiciones:
4) Equivalente a std:: basic_string_view < CharT, Traits > sv = t ;
return append ( sv. data ( ) , sv. size ( ) ) ; .
5) Equivalente a std:: basic_string_view < CharT, Traits > sv = t ;
return append ( sv. substr ( pos, count ) ) ; .
6,7) Añade caracteres de otra cadena str .
  • Si solo se proporciona str , se añaden todos sus caracteres.
  • Si también se proporciona pos :
    • Si count es npos , se añaden todos los caracteres de str comenzando desde pos .
    • De lo contrario, se añaden std:: min ( count, str. size ( ) - pos ) caracteres de str comenzando desde pos .
6) Equivalente a return append ( str. data ( ) , str. size ( ) ) ; .
7) Equivalente a return append ( std:: basic_string_view < CharT, Traits >
( str ) . substr ( pos, count ) ) ; .
(desde C++20)
8) Equivalente a return append ( basic_string ( first, last, get_allocator ( ) ) ) ; .

Esta sobrecarga tiene el mismo efecto que la sobrecarga (1) si InputIt es un tipo integral.

(hasta C++11)

Esta sobrecarga participa en la resolución de sobrecarga solo si InputIt cumple con los requisitos de LegacyInputIterator .

(desde C++11)
9) Equivalente a return append ( ilist. begin ( ) , ilist. size ( ) ) ; .

Contenidos

Parámetros

count - número de caracteres a añadir
ch - valor del carácter a añadir
s - puntero a la cadena de caracteres a añadir
t - objeto convertible a std::basic_string_view con los caracteres a añadir
pos - índice del primer carácter a añadir
str - cadena a añadir
first, last - rango de caracteres a añadir
ilist - lista de inicialización con los caracteres a añadir

Valor de retorno

* this

Complejidad

No hay garantías estándar de complejidad, las implementaciones típicas se comportan de manera similar a std::vector::insert() .

Excepciones

Si la operación causara que size() exceda max_size() , lanza std::length_error .

5) Si pos > sv. size ( ) es true , lanza std::out_of_range .
7) Si pos > str. size ( ) es true , lanza std::out_of_range .

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 <string>
int main()
{
    std::string str = "std::string";
    const char* cptr = "C-string";
    const char carr[] = "range";
    std::string result;
    // 1) Añadir un carácter 3 veces.
    // Nota: Esta es la única sobrecarga que acepta "CharT".
    result.append(3, '*');
    assert(result == "***");
    // 2) Añadir una cadena C de longitud fija
    result.append(cptr, 5);
    assert(result == "***C-str");
    // 3) Añadir una cadena C terminada en nulo
    // Nota: Como "append" devuelve *this, podemos encadenar llamadas.
    result.append(1, ' ').append(cptr);
    assert(result == "***C-str C-string");
    // 6) Añadir una cadena completa
    result.append(1, ' ').append(str);
    assert(result == "***C-str C-string std::string");
    // 7) Añadir parte de una cadena
    result.append(str, 3, 2);
    assert(result == "***C-str C-string std::string::");
    // 8) Añadir rango
    result.append(&carr[2], &carr[3]);
    assert(result == "***C-str C-string std::string::n");
    // 9) Añadir lista de inicialización
    result.append({'p', 'o', 's'});
    assert(result == "***C-str C-string std::string::npos");
}

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 847 C++98 no existía garantía de seguridad de excepciones se añadió garantía de seguridad de excepciones fuerte
LWG 2250 C++98 el comportamiento de la sobrecarga (7) era
indefinido si pos > str. size ( ) es true 		siempre lanza una excepción en este caso
LWG 2788 C++98 la sobrecarga (8) usaba un asignador construido por defecto
para construir la cadena temporal 		obtiene el asignador
de get_allocator()
LWG 2946 C++17 la sobrecarga (4) causa ambigüedad en algunos casos evitado al convertirla en plantilla

Véase también

(C++23)
agrega un rango de caracteres al final
(función miembro pública)
agrega caracteres al final
(función miembro pública)
concatena dos cadenas
(función)
concatena una cantidad determinada de caracteres de dos cadenas
(función)
agrega una copia de una cadena ancha a otra
(función)
agrega una cantidad determinada de caracteres anchos de una cadena ancha a otra
(función)