Skip to content

String::reserve_exact

String methods · Strings

Level: reference · for working programmers

One line: reserve without the round-up — asks the allocator for exactly len() + additional.

pub fn reserve_exact(&mut self, additional: usize)

Stable since 1.0.0.

Still a headroom, not a total. The difference is only that it does not deliberately over-allocate.

"Exact" is a request, not a promise: the allocator may return a larger block anyway, and the capacity will reflect that. The guarantee is capacity() >= len() + additional; what changes is the intent.

Use it when you know the final size and will not push past it — reading a file of known length, or building a record with a fixed layout. Use plain reserve whenever more pushes may follow, because the round-up is what keeps them cheap. Repeated reserve_exact in a growth loop reallocates every time and is a genuine performance bug.

Example

string_reserve_exact.rs in full — pasted here by tools/run_examples.py from the file CI compiles and runs.

fn main() {
    let mut exact = String::from("ab");
    let mut rounded = String::from("ab");
    exact.reserve_exact(5);
    rounded.reserve(5);
    println!("reserve_exact {} / reserve {}", exact.capacity(), rounded.capacity());

    // Both guarantee at least len + additional.
    println!("{} {}", exact.capacity() >= 7, rounded.capacity() >= 7);

    // The right use: a size you know and will not exceed.
    let payload = "the quick brown fox";
    let mut buf = String::new();
    buf.reserve_exact(payload.len());
    buf.push_str(payload);
    println!("len {} capacity {}", buf.len(), buf.capacity());

    // The wrong use: reserving exactly, repeatedly, in a growth loop.
    let mut bad = String::new();
    let mut reallocs = 0;
    let mut last = bad.capacity();
    for _ in 0..6 {
        bad.reserve_exact(4);
        bad.push_str("abcd");
        if bad.capacity() != last { reallocs += 1; last = bad.capacity(); }
    }
    println!("{reallocs} capacity changes over 6 appends");
}

Verified output of string_reserve_exact.rs — regenerated by tools/run_examples.py, never hand-typed.

reserve_exact 7 / reserve 8
true true
len 19 capacity 19
6 capacity changes over 6 appends

See also

String::reserve_exact in the standard library ↗

Po polsku

Słowo exact w nazwie opisuje intencję, a nie obietnicę: metoda nie zaokrągla celowo w górę, ale alokator i tak może oddać większy blok, a gwarancja pozostaje identyczna jak przy reserve — capacity() >= len() + additional. Argument nadal jest zapasem, nie sumą; cała różnica sprowadza się do tego, że dla "ab" i piątki dostajesz reserve_exact 7 zamiast reserve 8. Po tę wersję sięgaj, gdy rozmiar końcowy jest znany i nie zamierzasz go przekroczyć — plik o znanej długości, rekord o stałym układzie; w przykładzie widać to jako len 19 capacity 19, bez ani jednego bajta zapasu. W pętli, która wciąż dokłada, wybieraj zwykłe reserve: końcówka przykładu pokazuje, czym kończy się reserve_exact powtarzane przy każdym dopisaniu — 6 capacity changes over 6 appends, czyli realokacja za każdym razem, i jest to realny błąd wydajnościowy, a nie drobiazg.

Szukaj po polsku: dokładna rezerwacja pojemności · realokacja w pętli · znany rozmiar bufora · rust reserve vs reserve_exact · rust String capacity growth