1 | //! Operations on ASCII strings and characters. |
2 | //! |
3 | //! Most string operations in Rust act on UTF-8 strings. However, at times it |
4 | //! makes more sense to only consider the ASCII character set for a specific |
5 | //! operation. |
6 | //! |
7 | //! The [`AsciiExt`] trait provides methods that allow for character |
8 | //! operations that only act on the ASCII subset and leave non-ASCII characters |
9 | //! alone. |
10 | //! |
11 | //! The [`escape_default`] function provides an iterator over the bytes of an |
12 | //! escaped version of the character given. |
13 | |
14 | #![stable (feature = "rust1" , since = "1.0.0" )] |
15 | |
16 | #[stable (feature = "rust1" , since = "1.0.0" )] |
17 | pub use core::ascii::{escape_default, EscapeDefault}; |
18 | |
19 | #[unstable (feature = "ascii_char" , issue = "110998" )] |
20 | pub use core::ascii::Char; |
21 | |
22 | /// Extension methods for ASCII-subset only operations. |
23 | /// |
24 | /// Be aware that operations on seemingly non-ASCII characters can sometimes |
25 | /// have unexpected results. Consider this example: |
26 | /// |
27 | /// ``` |
28 | /// use std::ascii::AsciiExt; |
29 | /// |
30 | /// assert_eq!(AsciiExt::to_ascii_uppercase("café" ), "CAFÉ" ); |
31 | /// assert_eq!(AsciiExt::to_ascii_uppercase("café" ), "CAFé" ); |
32 | /// ``` |
33 | /// |
34 | /// In the first example, the lowercased string is represented `"cafe\u{301}"` |
35 | /// (the last character is an acute accent [combining character]). Unlike the |
36 | /// other characters in the string, the combining character will not get mapped |
37 | /// to an uppercase variant, resulting in `"CAFE\u{301}"`. In the second |
38 | /// example, the lowercased string is represented `"caf\u{e9}"` (the last |
39 | /// character is a single Unicode character representing an 'e' with an acute |
40 | /// accent). Since the last character is defined outside the scope of ASCII, |
41 | /// it will not get mapped to an uppercase variant, resulting in `"CAF\u{e9}"`. |
42 | /// |
43 | /// [combining character]: https://en.wikipedia.org/wiki/Combining_character |
44 | #[stable (feature = "rust1" , since = "1.0.0" )] |
45 | #[deprecated (since = "1.26.0" , note = "use inherent methods instead" )] |
46 | pub trait AsciiExt { |
47 | /// Container type for copied ASCII characters. |
48 | #[stable (feature = "rust1" , since = "1.0.0" )] |
49 | type Owned; |
50 | |
51 | /// Checks if the value is within the ASCII range. |
52 | /// |
53 | /// # Note |
54 | /// |
55 | /// This method is deprecated in favor of the identically-named |
56 | /// inherent methods on `u8`, `char`, `[u8]` and `str`. |
57 | #[stable (feature = "rust1" , since = "1.0.0" )] |
58 | fn is_ascii(&self) -> bool; |
59 | |
60 | /// Makes a copy of the value in its ASCII upper case equivalent. |
61 | /// |
62 | /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', |
63 | /// but non-ASCII letters are unchanged. |
64 | /// |
65 | /// To uppercase the value in-place, use [`make_ascii_uppercase`]. |
66 | /// |
67 | /// To uppercase ASCII characters in addition to non-ASCII characters, use |
68 | /// [`str::to_uppercase`]. |
69 | /// |
70 | /// # Note |
71 | /// |
72 | /// This method is deprecated in favor of the identically-named |
73 | /// inherent methods on `u8`, `char`, `[u8]` and `str`. |
74 | /// |
75 | /// [`make_ascii_uppercase`]: AsciiExt::make_ascii_uppercase |
76 | #[stable (feature = "rust1" , since = "1.0.0" )] |
77 | #[allow (deprecated)] |
78 | fn to_ascii_uppercase(&self) -> Self::Owned; |
79 | |
80 | /// Makes a copy of the value in its ASCII lower case equivalent. |
81 | /// |
82 | /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', |
83 | /// but non-ASCII letters are unchanged. |
84 | /// |
85 | /// To lowercase the value in-place, use [`make_ascii_lowercase`]. |
86 | /// |
87 | /// To lowercase ASCII characters in addition to non-ASCII characters, use |
88 | /// [`str::to_lowercase`]. |
89 | /// |
90 | /// # Note |
91 | /// |
92 | /// This method is deprecated in favor of the identically-named |
93 | /// inherent methods on `u8`, `char`, `[u8]` and `str`. |
94 | /// |
95 | /// [`make_ascii_lowercase`]: AsciiExt::make_ascii_lowercase |
96 | #[stable (feature = "rust1" , since = "1.0.0" )] |
97 | #[allow (deprecated)] |
98 | fn to_ascii_lowercase(&self) -> Self::Owned; |
99 | |
100 | /// Checks that two values are an ASCII case-insensitive match. |
101 | /// |
102 | /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`, |
103 | /// but without allocating and copying temporaries. |
104 | /// |
105 | /// # Note |
106 | /// |
107 | /// This method is deprecated in favor of the identically-named |
108 | /// inherent methods on `u8`, `char`, `[u8]` and `str`. |
109 | #[stable (feature = "rust1" , since = "1.0.0" )] |
110 | fn eq_ignore_ascii_case(&self, other: &Self) -> bool; |
111 | |
112 | /// Converts this type to its ASCII upper case equivalent in-place. |
113 | /// |
114 | /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', |
115 | /// but non-ASCII letters are unchanged. |
116 | /// |
117 | /// To return a new uppercased value without modifying the existing one, use |
118 | /// [`to_ascii_uppercase`]. |
119 | /// |
120 | /// # Note |
121 | /// |
122 | /// This method is deprecated in favor of the identically-named |
123 | /// inherent methods on `u8`, `char`, `[u8]` and `str`. |
124 | /// |
125 | /// [`to_ascii_uppercase`]: AsciiExt::to_ascii_uppercase |
126 | #[stable (feature = "ascii" , since = "1.9.0" )] |
127 | fn make_ascii_uppercase(&mut self); |
128 | |
129 | /// Converts this type to its ASCII lower case equivalent in-place. |
130 | /// |
131 | /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', |
132 | /// but non-ASCII letters are unchanged. |
133 | /// |
134 | /// To return a new lowercased value without modifying the existing one, use |
135 | /// [`to_ascii_lowercase`]. |
136 | /// |
137 | /// # Note |
138 | /// |
139 | /// This method is deprecated in favor of the identically-named |
140 | /// inherent methods on `u8`, `char`, `[u8]` and `str`. |
141 | /// |
142 | /// [`to_ascii_lowercase`]: AsciiExt::to_ascii_lowercase |
143 | #[stable (feature = "ascii" , since = "1.9.0" )] |
144 | fn make_ascii_lowercase(&mut self); |
145 | } |
146 | |
147 | macro_rules! delegating_ascii_methods { |
148 | () => { |
149 | #[inline] |
150 | fn is_ascii(&self) -> bool { |
151 | self.is_ascii() |
152 | } |
153 | |
154 | #[inline] |
155 | fn to_ascii_uppercase(&self) -> Self::Owned { |
156 | self.to_ascii_uppercase() |
157 | } |
158 | |
159 | #[inline] |
160 | fn to_ascii_lowercase(&self) -> Self::Owned { |
161 | self.to_ascii_lowercase() |
162 | } |
163 | |
164 | #[inline] |
165 | fn eq_ignore_ascii_case(&self, o: &Self) -> bool { |
166 | self.eq_ignore_ascii_case(o) |
167 | } |
168 | |
169 | #[inline] |
170 | fn make_ascii_uppercase(&mut self) { |
171 | self.make_ascii_uppercase(); |
172 | } |
173 | |
174 | #[inline] |
175 | fn make_ascii_lowercase(&mut self) { |
176 | self.make_ascii_lowercase(); |
177 | } |
178 | }; |
179 | } |
180 | |
181 | #[stable (feature = "rust1" , since = "1.0.0" )] |
182 | #[allow (deprecated)] |
183 | impl AsciiExt for u8 { |
184 | type Owned = u8; |
185 | |
186 | delegating_ascii_methods!(); |
187 | } |
188 | |
189 | #[stable (feature = "rust1" , since = "1.0.0" )] |
190 | #[allow (deprecated)] |
191 | impl AsciiExt for char { |
192 | type Owned = char; |
193 | |
194 | delegating_ascii_methods!(); |
195 | } |
196 | |
197 | #[stable (feature = "rust1" , since = "1.0.0" )] |
198 | #[allow (deprecated)] |
199 | impl AsciiExt for [u8] { |
200 | type Owned = Vec<u8>; |
201 | |
202 | delegating_ascii_methods!(); |
203 | } |
204 | |
205 | #[stable (feature = "rust1" , since = "1.0.0" )] |
206 | #[allow (deprecated)] |
207 | impl AsciiExt for str { |
208 | type Owned = String; |
209 | |
210 | delegating_ascii_methods!(); |
211 | } |
212 | |