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 ) ;
(jusqu'en C++20)
constexpr void reserve ( size_type new_cap ) ;
(depuis C++20)
void reserve ( ) ;
(2) (depuis C++20)
(obsolète en C++20)
(supprimé en C++26)
1) Informe un objet std::basic_string d'un changement planifié de taille, afin qu'il puisse gérer l'allocation de stockage de manière appropriée.
  • Si new_cap est supérieur à la capacité() actuelle, un nouveau stockage est alloué, et la capacité() devient égale ou supérieure à new_cap .
  • Si new_cap est inférieur à la capacité() actuelle, il s'agit d'une demande de réduction non contraignante.
  • Si new_cap est inférieur à la taille() actuelle, il s'agit d'une demande de réduction à la taille nécessaire non contraignante équivalente à shrink_to_fit() (depuis C++11) .
(jusqu'à C++20)
  • Si new_cap est inférieur ou égal à la capacité() actuelle, il n'y a aucun effet.
(depuis C++20)
Si un changement de capacité se produit, tous les itérateurs et références, y compris l'itérateur de fin, sont invalidés.
2) Une requête non-contraignante de réduction à la taille nécessaire. Après cet appel, capacity() a une valeur non spécifiée supérieure ou égale à size() .

Table des matières

Paramètres

new_cap - nouvelle capacité de la chaîne

Valeur de retour

(aucun)

Exceptions

Lance std::length_error si new_cap est supérieur à max_size() .

Peut lever toutes les exceptions levées par std:: allocator_traits < Allocator > :: allocate ( ) , telles que std::bad_alloc .

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 ).

Complexité

Au plus linéaire dans la size() de la chaîne.

Exemple

Exécuter ce code 
#include <cassert>
#include <iostream>
#include <string>
int main()
{
    std::string s;
    std::cout << "1) Initialement : " << s.capacity() << '\n';
    const std::string::size_type new_cap{101u};
    s.reserve(new_cap);
    assert(s.capacity() >= new_cap);
    std::cout << "2) Après reserve(" << new_cap << ") : " << s.capacity() << '\n';
    // observation du facteur de croissance de la capacité
    auto cap{s.capacity()};
    for (int check{}; check != 4; ++check)
    {
        while (cap == s.capacity())
            s += '$';
        cap = s.capacity();
        std::cout << (3) + check << ") Capacité : " << cap << '\n';
    }
//  s.reserve(); // déprécié/supprimé en C++20/26, utiliser :
    s.shrink_to_fit();
    std::cout << "7) Après shrink_to_fit : " << s.capacity() << '\n';
}

Sortie possible : 

1) Initialement : 15
2) Après reserve(101) : 101
3) Capacité : 202
4) Capacité : 404
5) Capacité : 808
6) Capacité : 1616
7) Après shrink_to_fit : 809

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 tel que publié Comportement corrigé
LWG 847 C++98 il n'y avait aucune garantie de sûreté des exceptions garantie de sûreté forte des exceptions ajoutée

Voir aussi

retourne le nombre de caractères pouvant être stockés dans la mémoire actuellement allouée
(fonction membre publique)
modifie le nombre de caractères stockés
(fonction membre publique)