Namespaces
Variants

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

From cppreference.net
C++
Strings library
std::basic_string
(1)
void reserve ( size_type new_cap = 0 ) ;
(hasta C++20)
constexpr void reserve ( size_type new_cap ) ;
(desde C++20)
void reserve ( ) ;
(2) (desde C++20)
(obsoleto en C++20)
(eliminado en C++26)
1) Informa a un objeto std::basic_string de un cambio planificado en el tamaño, para que pueda gestionar la asignación de almacenamiento adecuadamente.
  • Si new_cap es mayor que la capacity() actual, se asigna nuevo almacenamiento y capacity() se establece igual o mayor que new_cap .
  • Si new_cap es menor que la capacity() actual, esta es una solicitud de reducción no vinculante.
  • Si new_cap es menor que el size() actual, esta es una solicitud de reducción al tamaño necesario no vinculante equivalente a shrink_to_fit() (since C++11) .
(until C++20)
  • Si new_cap es menor o igual que la capacity() actual, no tiene efecto.
(since C++20)
Si se produce un cambio de capacidad, todos los iteradores y referencias, incluido el iterador pasado el final, quedan invalidados.
2) Una solicitud no vinculante de reducción al tamaño necesario. Después de esta llamada, capacity() tiene un valor no especificado mayor o igual que size() .

Contenidos

Parámetros

new_cap - nueva capacidad de la cadena

Valor de retorno

(ninguno)

Excepciones

Lanza std::length_error si new_cap es mayor que max_size() .

Puede lanzar cualquier excepción lanzada por std:: allocator_traits < Allocator > :: allocate ( ) , como std::bad_alloc .

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

Complejidad

Como máximo lineal en el size() de la cadena.

Ejemplo

Ejecutar este código 
#include <cassert>
#include <iostream>
#include <string>
int main()
{
    std::string s;
    std::cout << "1) Inicialmente: " << s.capacity() << '\n';
    const std::string::size_type new_cap{101u};
    s.reserve(new_cap);
    assert(s.capacity() >= new_cap);
    std::cout << "2) Después de reserve(" << new_cap << "): " << s.capacity() << '\n';
    // observando el factor de crecimiento de la capacidad
    auto cap{s.capacity()};
    for (int check{}; check != 4; ++check)
    {
        while (cap == s.capacity())
            s += '$';
        cap = s.capacity();
        std::cout << (3) + check << ") Capacidad: " << cap << '\n';
    }
//  s.reserve(); // obsoleto/eliminado en C++20/26, usar:
    s.shrink_to_fit();
    std::cout << "7) Después de shrink_to_fit: " << s.capacity() << '\n';
}

Salida posible: 

1) Inicialmente: 15
2) Después de reserve(101): 101
3) Capacidad: 202
4) Capacidad: 404
5) Capacidad: 808
6) Capacidad: 1616
7) Después de shrink_to_fit: 809

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 había garantía de seguridad de excepciones se añadió garantía de seguridad fuerte de excepciones

Véase también

devuelve el número de caracteres que pueden almacenarse en el almacenamiento actualmente asignado
(función miembro pública)
cambia el número de caracteres almacenados
(función miembro pública)