Text of rust.docs.kernel.org › next › core › primitive.char.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

char - Rust

Skip to main content char Primitive Type char 1.0.0 Expand description A character type. The char type represents a single character. More specifically, since ‘character’ isn’t a well-defined concept in Unicode, char is a ‘ Unicode scalar value ’. This documentation describes a number of methods and trait implementations on the char type. For technical reasons, there is additional, separate documentation in the std::char module as well. § Validity and Layout A char is a ‘ Unicode scalar value ’, which is any ‘ Unicode code point ’ other than a surrogate code point .

This has a fixed numerical definition: code points are in the range 0 to 0x10FFFF, inclusive. Surrogate code points, used by UTF-16, are in the range 0xD800 to 0xDFFF. No char may be constructed, whether as a literal or at runtime, that is not a Unicode scalar value. Violating this rule causes undefined behavior. ⓘ // Each of these is a compiler error [ '\u{D800}' , '\u{DFFF}' , '\u{110000}' ]; ⓘ // Panics; from_u32 returns None. char::from_u32( 0xDE01 ).unwrap(); // Undefined behavior let _ = unsafe { char::from_u32_unchecked( 0x110000 ) }; Unicode scalar values are also the exact set of values that may be encoded in UTF-8.

Because char values are Unicode scalar values and functions may assume incoming str values are valid UTF-8 , it is safe to store any char in a str or read any character from a str as a char . The gap in valid char values is understood by the compiler, so in the below example the two ranges are understood to cover the whole range of possible char values and there is no error for a non-exhaustive match . let c: char = 'a' ; match c { '\0' ..= '\u{D7FF}' => false , '\u{E000}' ..= '\u{10FFFF}' => true , }; All Unicode scalar values are valid char values, but not all of them represent a real character.

Many Unicode scalar values are not currently assigned to a character, but may be in the future (“reserved”); some will never be a character (“noncharacters”); and some may be given different meanings by different users (“private use”). char is guaranteed to have the same size, alignment, and function call ABI as u32 on all platforms. use std::alloc::Layout; assert_eq! (Layout::new::<char>(), Layout::new::<u32>()); § Representation char is always four bytes in size.

This is a different representation than a given character would have as part of a String . For example: let v = vec! [ 'h' , 'e' , 'l' , 'l' , 'o' ]; // five elements times four bytes for each element assert_eq! ( 20 , v.len() * size_of::<char>()); let s = String::from( "hello" ); // five elements times one byte per element assert_eq! ( 5 , s.len() * size_of::<u8>()); As always, remember that a human intuition for ‘character’ might not map to Unicode’s definitions.

For example, despite looking similar, the ‘é’ character is one Unicode code point while ‘é’ is two Unicode code points: let mut chars = "é" .chars(); // U+00e9: 'latin small letter e with acute' assert_eq! ( Some ( '\u{00e9}' ), chars.next()); assert_eq! ( None , chars.next()); let mut chars = "é" .chars(); // U+0065: 'latin small letter e' assert_eq! ( Some ( '\u{0065}' ), chars.next()); // U+0301: 'combining acute accent' assert_eq! ( Some ( '\u{0301}' ), chars.next()); assert_eq! ( None , chars.next()); This means that the contents of the first string above will fit into a char while the contents of the second string will not .

Trying to create a char literal with the contents of the second string gives an error: error: character literal may only contain one codepoint: 'é' let c = 'é'; ^^^ Another implication of the 4-byte fixed size of a char is that per- char processing can end up using a lot more memory: let s = String::from( "love: ❤️" ); let v: Vec<char> = s.chars().collect(); assert_eq! ( 12 , size_of_val( & s[..])); assert_eq! ( 32 , size_of_val( & v[..])); Implementations § Source § impl char 1.83.0 · Source pub const MIN : char = '\0' The lowest valid code point a char can have, '\0' .

Unlike integer types, char actually has a gap in the middle, meaning that the range of possible char s is smaller than you might expect. Ranges of char will automatically hop this gap for you: let dist = u32::from(char::MAX) - u32::from(char::MIN); let size = (char::MIN..=char::MAX).count() as u32; assert! (size < dist); Despite this gap, the MIN and MAX values can be used as bounds for all char values. § Examples let c: char = something_which_returns_char(); assert! (char::MIN <= c); let value_at_min = u32::from(char::MIN); assert_eq! (char::from_u32(value_at_min), Some ( '\0' )); 1.52.0 · Source pub const MAX : char = '\u{10FFFF}' The highest valid code point a char can have, '\u{10FFFF}' .

Unlike integer types, char actually has a gap in the middle, meaning that the range of possible char s is smaller than you might expect. Ranges of char will automatically hop this gap for you: let dist = u32::from(char::MAX) - u32::from(char::MIN); let size = (char::MIN..=char::MAX).count() as u32; assert! (size < dist); Despite this gap, the MIN and MAX values can be used as bounds for all char values. § Examples let c: char = something_which_returns_char(); assert! (c <= char::MAX); let value_at_max = u32::from(char::MAX); assert_eq! (char::from_u32(value_at_max), Some ( '\u{10FFFF}' )); assert_eq! (char::from_u32(value_at_max + 1 ), None ); 1.93.0 · Source pub const MAX_LEN_UTF8 : usize = 4 The maximum number of bytes required to encode a char to UTF-8 encoding.

1.93.0 · Source pub const MAX_LEN_UTF16 : usize = 2 The maximum number of two-byte units required to encode a char to UTF-16 encoding. 1.52.0 · Source pub const REPLACEMENT_CHARACTER : char = '\u{FFFD}' U+FFFD REPLACEMENT CHARACTER (�) is used in Unicode to represent a decoding error. It can occur, for example, when giving ill-formed UTF-8 bytes to String::from_utf8_lossy . 1.52.0 · Source pub const UNICODE_VERSION : ( u8 , u8 , u8 ) = crate::unicode::UNICODE_VERSION The version of Unicode that the Unicode parts of char and str methods are based on.

New versions of Unicode are released regularly, and subsequently all methods in the standard library depending on Unicode are updated. Therefore, the behavior of some char and str methods, and the value of this constant, change over time (within the boundaries of Unicode’s stability policies ). This is not considered to be a breaking change. The version numbering scheme is explained in Section 3.1 (Version Numbering) of the Unicode Standard.

1.52.0 · Source pub fn decode_utf16 <I: IntoIterator <Item = u16 >>( iter: I, ) -> DecodeUtf16 <I:: IntoIter > ⓘ Creates an iterator over the native endian UTF-16 encoded code points in iter , returning unpaired surrogates as Err s. § Examples Basic usage: // 𝄞mus<invalid>ic<invalid> let v = [ 0xD834 , 0xDD1E , 0x006d , 0x0075 , 0x0073 , 0xDD1E , 0x0069 , 0x0063 , 0xD834 , ]; assert_eq! ( char::decode_utf16(v) .map(|r| r.map_err(|e| e.unpaired_surrogate())) .collect::<Vec< _ >>(), vec! [ Ok ( '𝄞' ), Ok ( 'm' ), Ok ( 'u' ), Ok ( 's' ), Err ( 0xDD1E ), Ok ( 'i' ), Ok ( 'c' ), Err ( 0xD834 ) ] ); A lossy decoder can be obtained by replacing Err results with the replacement character: // 𝄞mus<invalid>ic<invalid> let v = [ 0xD834 , 0xDD1E , 0x006d , 0x0075 , 0x0073 , 0xDD1E , 0x0069 , 0x0063 , 0xD834 , ]; assert_eq! ( char::decode_utf16(v) .map(|r| r.unwrap_or(char::REPLACEMENT_CHARACTER)) .collect::<String>(), "𝄞mus�ic�" ); 1.52.0 (const: 1.67.0) · Source pub const fn from_u32 (i: u32 ) -> Option < char > Converts a u32 to a char .

Note that all char s are valid u32 s, and can be cast to one with as : let c = '💯' ; let i = c as u32; assert_eq! ( 128175 , i); However, the reverse is not true: not all valid u32 s are valid char s. from_u32() will return None if the input is not a valid value for a char . For an unsafe version of this function which ignores these checks, see from_u32_unchecked . § Examples Basic usage: let c = char:

The rest of this page is on the live site.