Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Standard Library Modules

The std::char module

Reference for Rust std::char: from_u32, from_digit, decode_utf16, MAX, REPLACEMENT_CHARACTER and the iterator and error types behind char methods.

std::char is the module behind Rust's char type: a Unicode scalar value, that is, any code point from U+0000 to U+10FFFF except the surrogates U+D800 to U+DFFF. Most of the useful functionality is now available as associated functions and methods on char itself (char::from_u32, char::from_digit, c.to_digit(10), c.is_alphabetic()), and those are the spellings to prefer. The module still exists for the constants, the decode_utf16 function and the types that those methods return.

Those types matter in practice because case conversion and escaping return iterators, not single characters: one character can map to several ('รŸ' uppercases to "SS").

Rust
let c = char::from_u32(0x1F980);
let d = char::from_digit(7, 10);

Try it

Rust Building and inspecting chars

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Rust Case mapping, escapes and UTF-16

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Syntax

Item Description
char::from_u32(n: u32) -> Option<char> None for surrogates and values above 0x10FFFF.
char::from_digit(d: u32, radix: u32) -> Option<char> Digit to its lowercase character; panics if radix > 36.
c.to_digit(radix) -> Option<u32> Character to digit value; panics if radix > 36.
char::from(u8) Infallible. u32 goes through TryFrom<u32>, which returns CharTryFromError.
char::MAX, char::REPLACEMENT_CHARACTER '\u{10FFFF}' and '\u{FFFD}'. The module-level constants are the older spellings.
decode_utf16(iter) Iterator of Result<char, DecodeUtf16Error> over u16 values.
ToUppercase, ToLowercase Returned by to_uppercase / to_lowercase; implement Iterator and Display.
EscapeDefault, EscapeUnicode, EscapeDebug Returned by the escape_* methods.
ParseCharError, CharTryFromError, TryFromCharError Error types for str::parse::<char>, u32 to char, and char to u8.

Usage notes

  • A char is 4 bytes and always a valid scalar value; it is not a "UTF-8 byte" and not a user-perceived character. An emoji with a skin tone is several chars.
  • s.len() counts bytes, s.chars().count() counts scalar values, and neither counts grapheme clusters (that needs a crate).
  • Prefer methods over module functions. std::char::from_u32 and friends are the old spellings and may warn as deprecated in new code.
  • char as u32 always works; u32 as char does not compile. Only u8 as char is allowed, as a cast; use char::from_u32 for the rest.
  • Case mapping uses Unicode rules and is locale-independent; Turkish dotted/dotless i needs special handling.
  • is_alphabetic, is_numeric, is_whitespace follow Unicode; the is_ascii_* family is faster and ASCII only.
  • Sorting chars orders by code point, which is not alphabetical order in most languages.
  • from_digit returns lowercase letters for radix above 10; uppercase them yourself.