str::eq_ignore_ascii_case

str methods · Strings

Level: reference · for working programmers

One line: Case-insensitive comparison over A–Z only, allocating nothing — the right way to compare two ASCII tokens.

pub const fn eq_ignore_ascii_case(&self, other: &str) -> bool

Stable since 1.23.0. Usable in a const context.

a.to_lowercase() == b.to_lowercase() allocates two Strings to answer a question that needs no memory at all. This compares byte by byte, folding only the 26 ASCII letters, and stops at the first difference.

The restriction is exactly the restriction of the other ascii methods: "É" and "é" are not equal here. For ASCII-defined data — HTTP header names, scheme names, hex digits, file extensions on ASCII paths — that is correct and fast. For human text it is wrong, and correct caseless matching needs Unicode case folding, which std does not provide.

const fn, so it can be used in a const assertion.

Example

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

fn main() {
    println!("{}", "HELLO".eq_ignore_ascii_case("hello"));
    println!("{}", "Content-Type".eq_ignore_ascii_case("content-type"));
    println!("{}", "abc".eq_ignore_ascii_case("abd"));

    // ASCII only: accented pairs are not equal.
    println!("{}", "É".eq_ignore_ascii_case("é"));
    println!("{}", "É".to_lowercase() == "é".to_lowercase());

    // No allocation, unlike the lowercase-both-sides idiom.
    let header = "ACCEPT-ENCODING";
    println!("{}", header.eq_ignore_ascii_case("accept-encoding"));

    // Matching a token against a table.
    let methods = ["GET", "POST", "PUT"];
    for input in ["get", "Post", "patch"] {
        let found = methods.iter().find(|m| m.eq_ignore_ascii_case(input));
        println!("{input:<6} -> {found:?}");
    }
}

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

true
true
false
false
true
true
get    -> Some("GET")
Post   -> Some("POST")
patch  -> None

See also

• str::to_ascii_lowercase — the allocating way to do the same normalization
• str::to_lowercase — the Unicode version, for human text
• str::is_ascii — checking the precondition
• str::contains — substring rather than equality

str::eq_ignore_ascii_case in the standard library ↗

Po polsku

Nazwę tej metody trzeba brać dosłownie: składa ona tylko dwadzieścia sześć liter ASCII, więc "Łódź".eq_ignore_ascii_case("łódź") da false — dokładnie tak jak "É" i "é" w przykładzie powyżej. To nie wada, tylko zakres: dla danych z definicji ASCII — nazw nagłówków HTTP, schematów URL, cyfr szesnastkowych — jest to odpowiedź poprawna i najszybsza z możliwych, bo porównanie idzie bajt po bajcie, urywa się na pierwszej różnicy i nie alokuje niczego, w przeciwieństwie do odruchowego a.to_lowercase() == b.to_lowercase(), które tworzy dwa String-i, żeby odpowiedzieć „tak” albo „nie”. Do tekstu pisanego przez ludzi użyj to_lowercase() po obu stronach — dla polszczyzny to wystarcza — pamiętając, że pełne składanie wielkości liter (Unicode case folding) to jednak coś innego niż zamiana na małe litery, a biblioteka standardowa go nie ma; dostarczają je crate'y unicase i caseless.

Szukaj po polsku: porównywanie bez wielkości liter · składanie wielkości liter · rust eq_ignore_ascii_case · rust unicode case folding crate