Text of rust.docs.kernel.org › src › core › char › methods.rs.html as Styx crawled it on Nov 20, 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

methods.rs - source

Skip to main content core/char/ methods.rs 1 //! impl char {} 2 3 #![expect(clippy::manual_is_ascii_check, reason = "this module implements various is_ascii checks" )] 4 5 use super :: * ; 6 use crate ::panic::const_panic ; 7 use crate ::slice ; 8 use crate ::str::from_utf8_unchecked_mut ; 9 use crate ::ub_checks::assert_unsafe_precondition ; 10 use crate ::unicode::{ self , conversions }; 11 12 impl char { 13 /// The lowest valid code point a `char` can have, `'\0'`.

14 /// 15 /// Unlike integer types, `char` actually has a gap in the middle, 16 /// meaning that the range of possible `char`s is smaller than you 17 /// might expect. Ranges of `char` will automatically hop this gap 18 /// for you: 19 /// 20 /// ``` 21 /// let dist = u32::from(char::MAX) - u32::from(char::MIN); 22 /// let size = (char::MIN..=char::MAX).count() as u32; 23 /// assert!(size < dist); 24 /// ``` 25 /// 26 /// Despite this gap, the `MIN` and [`MAX`] values can be used as bounds for 27 /// all `char` values.

28 /// 29 /// [`MAX`]: char::MAX 30 /// 31 /// # Examples 32 /// 33 /// ``` 34 /// # fn something_which_returns_char() -> char { 'a' } 35 /// let c: char = something_which_returns_char(); 36 /// assert!(char::MIN <= c); 37 /// 38 /// let value_at_min = u32::from(char::MIN); 39 /// assert_eq!(char::from_u32(value_at_min), Some('\0')); 40 /// ``` 41 #[stable(feature = "char_min" , since = "1.83.0" )] 42 pub const MIN: char = '\0' ; 43 44 /// The highest valid code point a `char` can have, `'\u{10FFFF}'`.

45 /// 46 /// Unlike integer types, `char` actually has a gap in the middle, 47 /// meaning that the range of possible `char`s is smaller than you 48 /// might expect. Ranges of `char` will automatically hop this gap 49 /// for you: 50 /// 51 /// ``` 52 /// let dist = u32::from(char::MAX) - u32::from(char::MIN); 53 /// let size = (char::MIN..=char::MAX).count() as u32; 54 /// assert!(size < dist); 55 /// ``` 56 /// 57 /// Despite this gap, the [`MIN`] and `MAX` values can be used as bounds for 58 /// all `char` values.

59 /// 60 /// [`MIN`]: char::MIN 61 /// 62 /// # Examples 63 /// 64 /// ``` 65 /// # fn something_which_returns_char() -> char { 'a' } 66 /// let c: char = something_which_returns_char(); 67 /// assert!(c <= char::MAX); 68 /// 69 /// let value_at_max = u32::from(char::MAX); 70 /// assert_eq!(char::from_u32(value_at_max), Some('\u{10FFFF}')); 71 /// assert_eq!(char::from_u32(value_at_max + 1), None); 72 /// ``` 73 #[stable(feature = "assoc_char_consts" , since = "1.52.0" )] 74 pub const MAX: char = '\u{10FFFF}' ; 75 76 /// The maximum number of bytes required to [encode](char::encode_utf8) a `char` to 77 /// UTF-8 encoding.

78 #[stable(feature = "char_max_len_assoc" , since = "1.93.0" )] 79 pub const MAX_LEN_UTF8: usize = 4 ; 80 81 /// The maximum number of two-byte units required to [encode](char::encode_utf16) a `char` 82 /// to UTF-16 encoding. 83 #[stable(feature = "char_max_len_assoc" , since = "1.93.0" )] 84 pub const MAX_LEN_UTF16: usize = 2 ; 85 86 /// `U+FFFD REPLACEMENT CHARACTER` (�) is used in Unicode to represent a 87 /// decoding error.

88 /// 89 /// It can occur, for example, when giving ill-formed UTF-8 bytes to 90 /// [`String::from_utf8_lossy`](../std/string/struct.String.html#method.from_utf8_lossy). 91 #[stable(feature = "assoc_char_consts" , since = "1.52.0" )] 92 pub const REPLACEMENT_CHARACTER: char = '\u{FFFD}' ; 93 94 /// The version of [Unicode](https://www.unicode.org/) that the Unicode parts of 95 /// `char` and `str` methods are based on.

96 /// 97 /// New versions of Unicode are released regularly, and subsequently all methods 98 /// in the standard library depending on Unicode are updated. Therefore, the 99 /// behavior of some `char` and `str` methods, and the value of this constant, 100 /// change over time (within the boundaries of Unicode's [stability policies]). 101 /// This is *not* considered to be a breaking change. 102 /// 103 /// [stability policies]: https://www.unicode.org/policies/stability_policy.html 104 /// 105 /// The version numbering scheme is explained in 106 /// [Section 3.1 (Version Numbering)] of the Unicode Standard.

107 /// 108 /// [Section 3.1 (Version Numbering)]: https://www.unicode.org/versions/latest/core-spec/chapter-3/#G49512 109 #[stable(feature = "assoc_char_consts" , since = "1.52.0" )] 110 pub const UNICODE_VERSION: ( u8 , u8 , u8 ) = crate ::unicode:: UNICODE_VERSION ; 111 112 /// Creates an iterator over the native endian UTF-16 encoded code points in `iter`, 113 /// returning unpaired surrogates as `Err`s. 114 /// 115 /// # Examples 116 /// 117 /// Basic usage: 118 /// 119 /// ``` 120 /// // 𝄞mus<invalid>ic<invalid> 121 /// let v = [ 122 /// 0xD834, 0xDD1E, 0x006d, 0x0075, 0x0073, 0xDD1E, 0x0069, 0x0063, 0xD834, 123 /// ]; 124 /// 125 /// assert_eq!( 126 /// char::decode_utf16(v) 127 /// .map(|r| r.map_err(|e| e.unpaired_surrogate())) 128 /// .collect::<Vec<_>>(), 129 /// vec![ 130 /// Ok('𝄞'), 131 /// Ok('m'), Ok('u'), Ok('s'), 132 /// Err(0xDD1E), 133 /// Ok('i'), Ok('c'), 134 /// Err(0xD834) 135 /// ] 136 /// ); 137 /// ``` 138 /// 139 /// A lossy decoder can be obtained by replacing `Err` results with the replacement character: 140 /// 141 /// ``` 142 /// // 𝄞mus<invalid>ic<invalid> 143 /// let v = [ 144 /// 0xD834, 0xDD1E, 0x006d, 0x0075, 0x0073, 0xDD1E, 0x0069, 0x0063, 0xD834, 145 /// ]; 146 /// 147 /// assert_eq!( 148 /// char::decode_utf16(v) 149 /// .map(|r| r.unwrap_or(char::REPLACEMENT_CHARACTER)) 150 /// .collect::<String>(), 151 /// "𝄞mus�ic�" 152 /// ); 153 /// ``` 154 #[stable(feature = "assoc_char_funcs" , since = "1.52.0" )] 155 #[inline] 156 pub fn decode_utf16<I: IntoIterator <Item = u16 >>(iter: I) -> DecodeUtf16 <I::IntoIter> { 157 super ::decode:: decode_utf16 ( iter ) 158 } 159 160 /// Converts a `u32` to a `char`.

161 /// 162 /// Note that all `char`s are valid [`u32`]s, and can be cast to one with 163 /// [`as`](../std/keyword.as.html): 164 /// 165 /// ``` 166 /// let c = '💯'; 167 /// let i = c as u32; 168 /// 169 /// assert_eq!(128175, i); 170 /// ``` 171 /// 172 /// However, the reverse is not true: not all valid [`u32`]s are valid 173 /// `char`s. `from_u32()` will return `None` if the input is not a valid value 174 /// for a `char`.

175 /// 176 /// For an unsafe version of this function which ignores these checks, see 177 /// [`from_u32_unchecked`]. 178 /// 179 /// [`from_u32_unchecked`]: #method.from_u32_unchecked 180 /// 181 /// # Examples 182 /// 183 /// Basic usage: 184 /// 185 /// ``` 186 /// let c = char::from_u32(0x2764); 187 /// 188 /// assert_eq!(Some('❤'), c); 189 /// ``` 190 /// 191 /// Returning `None` when the input is not a valid `char`: 192 /// 193 /// ``` 194 /// let c = char::from_u32(0x110000); 195 /// 196 /// assert_eq!(None, c); 197 /// ``` 198 #[stable(feature = "assoc_char_funcs" , since = "1.52.0" )] 199 #[rustc_const_stable(feature = "const_char_convert" , since = "1.67.0" )] 200 #[must_use] 201 #[inline] 202 pub const fn from_u32(i: u32 ) -> Option < char > { 203 super ::convert:: from_u32 ( i ) 204 } 205 206 /// Converts a `u32` to a `char`, ignoring validity.

207 /// 208 /// Note that all `char`s are valid [`u32`]s, and can be cast to one with 209 /// `as`: 210 /// 211 /// ``` 212 /// let c = '💯'; 213 /// let i = c as u32; 214 /// 215 /// assert_eq!(128175, i); 216 /// ``` 217 /// 218 /// However, the reverse is not true: not all valid [`u32`]s are valid 219 /// `char`s. `from_u32_unchecked()` will ignore this, and blindly cast to 220 /// `char`, possibly creating an invalid one.

221 /// 222 /// # Safety 223 /// 224 /// This function is unsafe, as it may construct invalid `char` values. 225 /// 226 /// For a safe version of this function, see the [`from_u32`] function. 227 /// 228 /// [`from_u32`]: #method.from_u32 229 /// 230 /// # Examples 231 /// 232 /// Basic usage: 233 /// 234 /// ``` 235 /// let c = unsafe { char::from_u32_unchecked(0x2764) }; 236 /// 237 /// assert_eq!('❤', c); 238 /// ``` 239 #[stab

The rest of this page is on the live site.