mod.rs - source
Skip to main content core/char/ mod.rs 1 //! Utilities for the `char` primitive type. 2 //! 3 //! *[See also the `char` primitive type](primitive@char).* 4 //! 5 //! The `char` type represents a single character. More specifically, since 6 //! 'character' isn't a well-defined concept in Unicode, `char` is a '[Unicode 7 //! scalar value]', which is similar to, but not the same as, a '[Unicode code 8 //! point]'. 9 //! 10 //! [Unicode scalar value]: https://www.unicode.org/glossary/#unicode_scalar_value 11 //! [Unicode code point]: https://www.unicode.org/glossary/#code_point 12 //!
13 //! This module exists for technical reasons, the primary documentation for 14 //! `char` is directly on [the `char` primitive type][char] itself. 15 //! 16 //! This module is the home of the iterator implementations for the iterators 17 //! implemented on `char`, as well as some useful constants and conversion 18 //! functions that convert various types to `char`. 19 20 #![allow(non_snake_case)] 21 #![stable(feature = "rust1" , since = "1.0.0" )] 22 23 mod convert ; 24 mod decode ; 25 mod methods ; 26 27 // stable re-exports 28 #[rustfmt::skip] 29 #[stable(feature = "try_from" , since = "1.34.0" )] 30 pub use self ::convert::CharTryFromError ; 31 #[stable(feature = "char_from_str" , since = "1.20.0" )] 32 pub use self ::convert::ParseCharError ; 33 #[stable(feature = "decode_utf16" , since = "1.9.0" )] 34 pub use self ::decode::{ DecodeUtf16 , DecodeUtf16Error }; 35 36 // perma-unstable re-exports 37 #[rustfmt::skip] 38 #[unstable(feature = "char_internals" , reason = "exposed only for libstd" , issue = "none" )] 39 pub use self ::methods::encode_utf16_raw ; // perma-unstable 40 #[unstable(feature = "char_internals" , reason = "exposed only for libstd" , issue = "none" )] 41 pub use self ::methods::{ encode_utf8_raw , encode_utf8_raw_unchecked }; // perma-unstable 42 43 #[rustfmt::skip] 44 use crate ::ascii ; 45 pub ( crate ) use self ::methods::EscapeDebugExtArgs ; 46 use crate ::error::Error ; 47 use crate ::escape::{ AlwaysEscaped , EscapeIterInner , MaybeEscaped }; 48 use crate ::fmt::{ self , Write }; 49 use crate ::iter::{ FusedIterator , TrustedLen , TrustedRandomAccess , TrustedRandomAccessNoCoerce }; 50 use crate ::num::NonZero ; 51 52 // UTF-8 ranges and tags for encoding characters 53 const TAG_CONT: u8 = 0b1000_0000 ; 54 const TAG_TWO_B: u8 = 0b1100_0000 ; 55 const TAG_THREE_B: u8 = 0b1110_0000 ; 56 const TAG_FOUR_B: u8 = 0b1111_0000 ; 57 const MAX_ONE_B: u32 = 0x80 ; 58 const MAX_TWO_B: u32 = 0x800 ; 59 const MAX_THREE_B: u32 = 0x10000 ; 60 61 /* 62 Lu Uppercase_Letter an uppercase letter 63 Ll Lowercase_Letter a lowercase letter 64 Lt Titlecase_Letter a digraphic character, with first part uppercase 65 Lm Modifier_Letter a modifier letter 66 Lo Other_Letter other letters, including syllables and ideographs 67 Mn Nonspacing_Mark a nonspacing combining mark (zero advance width) 68 Mc Spacing_Mark a spacing combining mark (positive advance width) 69 Me Enclosing_Mark an enclosing combining mark 70 Nd Decimal_Number a decimal digit 71 Nl Letter_Number a letterlike numeric character 72 No Other_Number a numeric character of other type 73 Pc Connector_Punctuation a connecting punctuation mark, like a tie 74 Pd Dash_Punctuation a dash or hyphen punctuation mark 75 Ps Open_Punctuation an opening punctuation mark (of a pair) 76 Pe Close_Punctuation a closing punctuation mark (of a pair) 77 Pi Initial_Punctuation an initial quotation mark 78 Pf Final_Punctuation a final quotation mark 79 Po Other_Punctuation a punctuation mark of other type 80 Sm Math_Symbol a symbol of primarily mathematical use 81 Sc Currency_Symbol a currency sign 82 Sk Modifier_Symbol a non-letterlike modifier symbol 83 So Other_Symbol a symbol of other type 84 Zs Space_Separator a space character (of various non-zero widths) 85 Zl Line_Separator U+2028 LINE SEPARATOR only 86 Zp Paragraph_Separator U+2029 PARAGRAPH SEPARATOR only 87 Cc Control a C0 or C1 control code 88 Cf Format a format control character 89 Cs Surrogate a surrogate code point 90 Co Private_Use a private-use character 91 Cn Unassigned a reserved unassigned code point or a noncharacter 92 */ 93 94 /// The highest valid code point a `char` can have, `'\u{10FFFF}'`.
Use [`char::MAX`] instead. 95 #[stable(feature = "rust1" , since = "1.0.0" )] 96 #[deprecated(since = "TBD" , note = "replaced by the `MAX` associated constant on `char`" )] 97 pub const MAX : char = char :: MAX ; 98 99 /// `U+FFFD REPLACEMENT CHARACTER` (�) is used in Unicode to represent a 100 /// decoding error. Use [`char::REPLACEMENT_CHARACTER`] instead. 101 #[stable(feature = "decode_utf16" , since = "1.9.0" )] 102 #[deprecated( 103 since = "TBD" , 104 note = "replaced by the `REPLACEMENT_CHARACTER` associated constant on `char`" 105 )] 106 pub const REPLACEMENT_CHARACTER : char = char :: REPLACEMENT_CHARACTER ; 107 108 /// The version of [Unicode](https://www.unicode.org/) that the Unicode parts of 109 /// `char` and `str` methods are based on.
Use [`char::UNICODE_VERSION`] instead. 110 #[stable(feature = "unicode_version" , since = "1.45.0" )] 111 #[deprecated( 112 since = "TBD" , 113 note = "replaced by the `UNICODE_VERSION` associated constant on `char`" 114 )] 115 pub const UNICODE_VERSION : ( u8 , u8 , u8 ) = char :: UNICODE_VERSION ; 116 117 /// Creates an iterator over the UTF-16 encoded code points in `iter`, returning 118 /// unpaired surrogates as `Err`s.
Use [`char::decode_utf16`] instead. 119 #[stable(feature = "decode_utf16" , since = "1.9.0" )] 120 #[deprecated(since = "TBD" , note = "replaced by the `decode_utf16` method on `char`" )] 121 #[inline] 122 pub fn decode_utf16 <I: IntoIterator <Item = u16 >>(iter: I) -> DecodeUtf16 <I::IntoIter> { 123 self ::decode:: decode_utf16 ( iter ) 124 } 125 126 /// Converts a `u32` to a `char`. Use [`char::from_u32`] instead. 127 #[stable(feature = "rust1" , since = "1.0.0" )] 128 #[rustc_const_stable(feature = "const_char_convert" , since = "1.67.0" )] 129 #[deprecated(since = "TBD" , note = "replaced by the `from_u32` method on `char`" )] 130 #[must_use] 131 #[inline] 132 pub const fn from_u32 (i: u32 ) -> Option < char > { 133 self ::convert:: from_u32 ( i ) 134 } 135 136 /// Converts a `u32` to a `char`, ignoring validity.
Use [`char::from_u32_unchecked`] 137 /// instead. 138 #[stable(feature = "char_from_unchecked" , since = "1.5.0" )] 139 #[rustc_const_stable(feature = "const_char_from_u32_unchecked" , since = "1.81.0" )] 140 #[deprecated(since = "TBD" , note = "replaced by the `from_u32_unchecked` method on `char`" )] 141 #[must_use] 142 #[inline] 143 pub const unsafe fn from_u32_unchecked (i: u32 ) -> char { 144 // SAFETY: the safety contract must be upheld by the caller.
145 unsafe { self ::convert:: from_u32_unchecked ( i ) } 146 } 147 148 /// Converts a digit in the given radix to a `char`. Use [`char::from_digit`] instead. 149 #[stable(feature = "rust1" , since = "1.0.0" )] 150 #[rustc_const_stable(feature = "const_char_convert" , since = "1.67.0" )] 151 #[deprecated(since = "TBD" , note = "replaced by the `from_digit` method on `char`" )] 152 #[must_use] 153 #[inline] 154 pub const fn from_digit (num: u32 , radix: u32 ) -> Option < char > { 155 self ::convert:: from_digit ( num , radix ) 156 } 157 158 /// Returns an iterator that yields the hexadecimal Unicode escape of a 159 /// character, as `char`s.
160 /// 161 /// This `struct` is created by the [`escape_unicode`] method on [`char`]. See 162 /// its documentation for more. 163 /// 164 /// [`escape_unicode`]: char::escape_unicode 165 #[derive( Clone , Debug )] 166 #[stable(feature = "rust1" , since = "1.0.0" )] 167 pub struct EscapeUnicode ( EscapeIterInner < 10 , AlwaysEscaped >); 168 169 impl EscapeUnicode { 170 #[inline] 171 const fn new(c: char ) -> Self { 172 Self ( EscapeIterInner :: unicode ( c )) 173 } 174 } 175 176 #[stable(feature = "rust1" , since = "1.0.0" )] 177 impl Iterator for EscapeUnicode { 178 type Item = char ; 179 180 #[
The rest of this page is on the live site.