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 ) ;
(bis C++20)
constexpr void reserve ( size_type new_cap ) ;
(seit C++20)
void reserve ( ) ;
(2) (seit C++20)
(veraltet in C++20)
(entfernt in C++26)
1) Informiert ein std::basic_string -Objekt über eine geplante Größenänderung, damit es die Speicherzuweisung entsprechend verwalten kann.
  • Wenn new_cap größer als die aktuelle capacity() ist, wird neuer Speicher zugewiesen, und capacity() wird gleich oder größer als new_cap gemacht.
  • Wenn new_cap kleiner als die aktuelle capacity() ist, handelt es sich um eine nicht bindende Verkleinerungsanfrage.
  • Wenn new_cap kleiner als die aktuelle size() ist, handelt es sich um eine nicht bindende Shrink-to-Fit-Anfrage equivalent to shrink_to_fit() (since C++11) .
(until C++20)
  • Wenn new_cap kleiner oder gleich der aktuellen capacity() ist, gibt es keine Auswirkung.
(since C++20)
Wenn eine Kapazitätsänderung stattfindet, werden alle Iteratoren und Referenzen, einschließlich des Past-the-End-Iterators, ungültig.
2) Eine nicht verbindliche Anfrage zur Größenanpassung. Nach diesem Aufruf hat capacity() einen nicht spezifizierten Wert größer oder gleich size() .

Inhaltsverzeichnis

Parameter

new_cap - neue Kapazität des Strings

Rückgabewert

(keine)

Ausnahmen

Wirft std::length_error falls new_cap größer ist als max_size() .

Kann alle Ausnahmen werfen, die von std:: allocator_traits < Allocator > :: allocate ( ) geworfen werden, wie z.B. std::bad_alloc .

Wenn aus irgendeinem Grund eine Exception ausgelöst wird, hat diese Funktion keine Wirkung ( strong exception safety guarantee ).

Komplexität

Höchstens linear in der size() der Zeichenkette.

Beispiel

Diesen Code ausführen 
#include <cassert>
#include <iostream>
#include <string>
int main()
{
    std::string s;
    std::cout << "1) Anfänglich: " << s.capacity() << '\n';
    const std::string::size_type new_cap{101u};
    s.reserve(new_cap);
    assert(s.capacity() >= new_cap);
    std::cout << "2) Nach reserve(" << new_cap << "): " << s.capacity() << '\n';
    // Beobachtung des Kapazitätswachstumsfaktors
    auto cap{s.capacity()};
    for (int check{}; check != 4; ++check)
    {
        while (cap == s.capacity())
            s += '$';
        cap = s.capacity();
        std::cout << (3) + check << ") Kapazität: " << cap << '\n';
    }
//  s.reserve(); // In C++20/26 veraltet/entfernt, verwenden Sie:
    s.shrink_to_fit();
    std::cout << "7) Nach shrink_to_fit: " << s.capacity() << '\n';
}

Mögliche Ausgabe: 

1) Anfänglich: 15
2) Nach reserve(101): 101
3) Kapazität: 202
4) Kapazität: 404
5) Kapazität: 808
6) Kapazität: 1616
7) Nach shrink_to_fit: 809

Fehlerberichte

Die folgenden verhaltensändernden Fehlerberichte wurden rückwirkend auf zuvor veröffentlichte C++-Standards angewendet.

DR Angewendet auf Verhalten wie veröffentlicht Korrektes Verhalten
LWG 847 C++98 es gab keine Exception-Sicherheitsgarantie starke Exception-Sicherheitsgarantie hinzugefügt

Siehe auch

gibt die Anzahl der Zeichen zurück, die im aktuell allozierten Speicherplatz gespeichert werden können
(öffentliche Elementfunktion)
ändert die Anzahl der gespeicherten Zeichen
(öffentliche Elementfunktion)