`String::with_capacity` în Rust

String Rust 1.0

Creează un String gol cu loc rezervat pentru cel puțin n octeți; capacity() arată cât loc există.

Sintaxă

pub fn with_capacity(capacity: usize) -> String
pub fn capacity(&self) -> usize

Ce face `String::with_capacity`

Un String are o lungime (len, câți octeți de text are acum) și o capacitate (capacity, câți octeți încap fără o nouă alocare). Când adaugi text peste capacitate, Rust alocă un bloc mai mare și copiază textul acolo.

with_capacity(n) rezervă de la început loc pentru cel puțin n octeți. Este util când construiești un text mare în bucăți și știi aproximativ cât va avea. Textul pornește tot gol: capacitatea nu este lungime.

Cât crește capacitatea la o realocare este un detaliu al bibliotecii, nu o garanție: acum devine cel puțin dublul celei vechi sau, dacă textul adăugat cere mai mult, exact cât e nevoie (vezi primul exemplu: 10 devine 21). Sigur este doar că capacity() >= len().

Parametri

Parametru	Descriere
`capacity`	Numărul minim de octeți pentru care se rezervă loc. Diacriticele ocupă 2 octeți fiecare.

Ce returnează

with_capacity: un String gol. capacity: numărul de octeți rezervați (usize).

Exemple

Exemplul 1: Lungime și capacitate

fn main() {
    let mut s = String::with_capacity(10);
    println!("len = {}, capacity = {}", s.len(), s.capacity());

    s.push_str("Suceava");
    println!("len = {}, capacity = {}", s.len(), s.capacity());

    s.push_str(" și Botoșani");   // depășește 10 octeți: se realocă
    println!("len = {}, capacity = {}", s.len(), s.capacity());
}

Rezultat

len = 0, capacity = 10
len = 7, capacity = 10
len = 21, capacity = 21

Exemplul 2: Fără realocări într-o buclă

Rezervăm de la început 2 octeți pentru fiecare număr (cifra și separatorul). Capacitatea rămâne aceeași până la final.

fn main() {
    let n = 9;
    let mut s = String::with_capacity(n * 2);
    let inceput = s.capacity();

    for i in 1..=n {
        s.push_str(&i.to_string());
        s.push(';');
    }
    println!("{s}");
    println!("capacitate la început: {inceput}, la final: {}", s.capacity());
}