char

char as a Unicode scalar value, distinct from bytes and grapheme clusters, plus classification and case mapping.

テーマページの本文は現在英語です。

A Rust char is a Unicode scalar value: a code point in 0..=0x10FFFF excluding the surrogate range 0xD800..=0xDFFF. It is 32 bits in memory, but it is not a byte and it is not a user-perceived grapheme cluster. The thumbs-up emoji is one char and four UTF-8 bytes. A composed e-acute is one char and two bytes; the decomposed form e plus combining acute is two chars and three bytes, even though it may look like one character. The standard library has no grapheme-cluster iterator; that would require a Unicode segmentation crate, which this reference does not use.

The str page already covers byte indexes, is_char_boundary, and why slicing mid-character panics. This page starts from the char type itself. Examples were compiled with rustc 1.90.0 and --edition=2024.

Examples were compiled with rustc 1.90.0 using --edition=2024 and run as a plain binary. See the Rust 1.90.0 documentation for the complete API.

Rust reference overview →

API index

APISummary
char::from_u32, char::len_utf8, str::len, str::charsBuild a char from a code point, and compare UTF-8 byte length with the number of scalar values. A char is not a grapheme cluster.
char::is_alphabetic, char::is_whitespace, char::is_ascii_digit, char::to_uppercase, char::to_lowercaseClassify a scalar and map case through an iterator. Uppercasing ß yields two characters, not a single char.

Scalars, bytes, and graphemes

String::len is a byte count. chars().count() is a count of Unicode scalar values. They differ for "👍" (4 and 1) and for the decomposed e-acute (3 and 2). char::len_utf8 of the composed e-acute is 2. from_u32 returns Some for U+1F44D, the thumbs-up scalar, and None for 0xD800, a surrogate that is not a scalar.

char::from_u32, char::len_utf8, str::len, str::chars

pub const fn from_u32(i: u32) -> Option<char>
pub const fn len_utf8(self) -> usize
pub const fn len(&self) -> usize
pub fn chars(&self) -> Chars<'_>

Build a char from a code point, and compare UTF-8 byte length with the number of scalar values. A char is not a grapheme cluster.

ParameterDescription
iA 32-bit code point. from_u32 returns None if i is a surrogate or is greater than 0x10FFFF.

Returns: from_u32 returns Option<char>. len_utf8 is 1 through 4. str::len is the byte length of the string. chars().count() is the number of scalar values.

  • The composed "é" in this source file is a single Unicode scalar. The decomposed form is written as e plus U+0301. The counts were measured with rustc 1.90.0.
  • UTF-8 slicing rules and is_char_boundary stay on the str page.
rust
fn main() {
    let thumbs = "👍";
    println!("{} {}", thumbs.len(), thumbs.chars().count());
    let composed = "é";
    let decomposed = "e\u{0301}";
    println!("{} {}", composed.len(), composed.chars().count());
    println!("{} {}", decomposed.len(), decomposed.chars().count());
    println!("{}", 'é'.len_utf8());
    println!("{:?}", char::from_u32(0x1F44D));
    println!("{:?}", char::from_u32(0xD800));
}

Expected output

4 1
2 1
3 2
2
Some('👍')
None

Related: str byte indexes and char boundaries

Official documentation →

Classification and case mapping

is_alphabetic, is_whitespace, and is_ascii_digit classify a single scalar. is_ascii_digit is false for e-acute even when is_alphabetic would be true. to_uppercase and to_lowercase return iterators, because a scalar can map to more than one scalar. On rustc 1.90.0, collecting the uppercase mapping of ß yields "SS". These mappings are Unicode default case mappings, not locale-specific APIs such as a Turkish dotted I.

char::is_alphabetic, char::is_whitespace, char::is_ascii_digit, char::to_uppercase, char::to_lowercase

pub fn is_alphabetic(self) -> bool
pub fn is_whitespace(self) -> bool
pub const fn is_ascii_digit(self) -> bool
pub fn to_uppercase(self) -> ToUppercase
pub fn to_lowercase(self) -> ToLowercase

Classify a scalar and map case through an iterator. Uppercasing ß yields two characters, not a single char.

ParameterDescription
selfThe Unicode scalar to classify or map. These methods do not take a locale argument.

Returns: The is_ methods return bool. to_uppercase and to_lowercase return iterators of char, which the example collects into a String.

  • The "SS" result for ß was measured with rustc 1.90.0. It illustrates a multi-character mapping; it is not a complete Unicode case-folding guide.
rust
fn main() {
    println!("{} {}", 'A'.is_alphabetic(), '3'.is_alphabetic());
    println!("{} {}", ' '.is_whitespace(), '\n'.is_whitespace());
    println!("{} {}", '9'.is_ascii_digit(), 'é'.is_ascii_digit());
    let upper: String = 'ß'.to_uppercase().collect();
    println!("{upper}");
    let lower: String = 'A'.to_lowercase().collect();
    println!("{lower}");
}

Expected output

true false
true true
true false
SS
a

Official documentation →