Skip to content

str::make_ascii_lowercase

str methods · Strings

Level: reference · for working programmers

One line: Lowercases A–Z in place, allocating nothing — needs a &mut str, and returns ().

pub const fn make_ascii_lowercase(&mut self)

Stable since 1.23.0. Usable in a const context.

This is the in-place counterpart of to_ascii_lowercase. It is only possible for ASCII: every ASCII letter is exactly one byte, so the swap never changes the length, and a &mut str cannot change its length.

That is also why there is no make_lowercase — the Unicode transformation can grow the string, which a &mut str cannot accommodate. For a Unicode in-place edit you must go through a String: s = s.to_lowercase();.

It returns (), so it does not chain. let x = s.make_ascii_lowercase(); binds the unit value and is a common slip.

Getting a &mut str usually means String::as_mut_str or a &mut String coercion.

Example

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

fn main() {
    let mut s = String::from("HELLO Wörld");
    s.make_ascii_lowercase();
    println!("{s:?}");                        // ö is untouched

    // In place: no allocation, and the original binding is changed.
    let mut header = String::from("Content-Type");
    header.make_ascii_lowercase();
    println!("{header:?}");

    // It returns (), so it does not chain.
    let mut t = String::from("ABC");
    let unit = t.make_ascii_lowercase();
    println!("{t:?} and the call returned {unit:?}");

    // A Unicode in-place edit has to go through String, because it can grow.
    let mut u = String::from("İSTANBUL");
    println!("{} bytes", u.len());
    u = u.to_lowercase();
    println!("{u:?}, {} bytes", u.len());

    // Only part of a string, via a mutable slice.
    let mut part = String::from("ABCDEF");
    part.as_mut_str()[..3].make_ascii_lowercase();
    println!("{part:?}");
}

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

"hello wörld"
"content-type"
"abc" and the call returned ()
9 bytes
"i\u{307}stanbul", 10 bytes
"abcDEF"

See also

str::make_ascii_lowercase in the standard library ↗

Po polsku

Dla polskiego tekstu cała treść tej metody siedzi w jej nazwie: ascii znaczy wyłącznie A–Z, więc "ŁÓDŹ".make_ascii_lowercase() daje "ŁÓdŹ" — zamienione jedno D, reszta nietknięta, bo Ł, Ó i Ź leżą poza ASCII. To nie przeoczenie biblioteki, tylko warunek pracy w miejscu (in place): litera ASCII zajmuje dokładnie jeden bajt, podmiana nie zmienia więc długości, a &mut str swojej długości zmienić nie umie. Dlatego make_lowercase nie istnieje w ogóle — pełne odwzorowanie Unicode potrafi wydłużyć łańcuch (w przykładzie powyżej İSTANBUL rośnie z 9 do 10 bajtów), a to wymaga przejścia przez String: s = s.to_lowercase();. Praktyczny wniosek: do polskich napisów bierz to_lowercase(), a make_ascii_lowercase() zostaw temu, do czego naprawdę służy — nagłówkom HTTP, kluczom protokołów i innym rzeczom z definicji zapisanym w ASCII; zwraca (), więc łańcuchować jej i tak się nie da.

Szukaj po polsku: zamiana na małe litery · polskie znaki diakrytyczne w Ruscie · wielkość liter Unicode · rust make_ascii_lowercase vs to_lowercase · rust &mut str in place