]>
Commit | Line | Data |
---|---|---|
54a0048b | 1 | //! Operations on ASCII strings and characters. |
cc61c64b XL |
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 | //! [`AsciiExt`]: trait.AsciiExt.html | |
15 | //! [`escape_default`]: fn.escape_default.html | |
1a4d82fc | 16 | |
85aaf69f | 17 | #![stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 18 | |
0531ce1d XL |
19 | #[stable(feature = "rust1", since = "1.0.0")] |
20 | pub use core::ascii::{EscapeDefault, escape_default}; | |
1a4d82fc | 21 | |
cc61c64b | 22 | /// Extension methods for ASCII-subset only operations. |
7453a54e SL |
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 | /// | |
abe05a73 XL |
30 | /// assert_eq!(AsciiExt::to_ascii_uppercase("café"), "CAFÉ"); |
31 | /// assert_eq!(AsciiExt::to_ascii_uppercase("café"), "CAFé"); | |
7453a54e SL |
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 | |
85aaf69f | 44 | #[stable(feature = "rust1", since = "1.0.0")] |
0531ce1d | 45 | #[rustc_deprecated(since = "1.26.0", reason = "use inherent methods instead")] |
85aaf69f | 46 | pub trait AsciiExt { |
c34b1796 | 47 | /// Container type for copied ASCII characters. |
85aaf69f SL |
48 | #[stable(feature = "rust1", since = "1.0.0")] |
49 | type Owned; | |
50 | ||
7453a54e | 51 | /// Checks if the value is within the ASCII range. |
c34b1796 | 52 | /// |
abe05a73 | 53 | /// # Note |
c34b1796 | 54 | /// |
abe05a73 XL |
55 | /// This method will be deprecated in favor of the identically-named |
56 | /// inherent methods on `u8`, `char`, `[u8]` and `str`. | |
85aaf69f | 57 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
58 | fn is_ascii(&self) -> bool; |
59 | ||
cc61c64b | 60 | /// Makes a copy of the value in its ASCII upper case equivalent. |
c34b1796 | 61 | /// |
1a4d82fc JJ |
62 | /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', |
63 | /// but non-ASCII letters are unchanged. | |
c34b1796 | 64 | /// |
cc61c64b | 65 | /// To uppercase the value in-place, use [`make_ascii_uppercase`]. |
32a655c1 SL |
66 | /// |
67 | /// To uppercase ASCII characters in addition to non-ASCII characters, use | |
68 | /// [`str::to_uppercase`]. | |
69 | /// | |
abe05a73 | 70 | /// # Note |
c34b1796 | 71 | /// |
abe05a73 XL |
72 | /// This method will be deprecated in favor of the identically-named |
73 | /// inherent methods on `u8`, `char`, `[u8]` and `str`. | |
32a655c1 SL |
74 | /// |
75 | /// [`make_ascii_uppercase`]: #tymethod.make_ascii_uppercase | |
76 | /// [`str::to_uppercase`]: ../primitive.str.html#method.to_uppercase | |
85aaf69f | 77 | #[stable(feature = "rust1", since = "1.0.0")] |
0531ce1d | 78 | #[allow(deprecated)] |
85aaf69f | 79 | fn to_ascii_uppercase(&self) -> Self::Owned; |
1a4d82fc | 80 | |
cc61c64b | 81 | /// Makes a copy of the value in its ASCII lower case equivalent. |
c34b1796 | 82 | /// |
1a4d82fc JJ |
83 | /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', |
84 | /// but non-ASCII letters are unchanged. | |
c34b1796 | 85 | /// |
cc61c64b | 86 | /// To lowercase the value in-place, use [`make_ascii_lowercase`]. |
32a655c1 SL |
87 | /// |
88 | /// To lowercase ASCII characters in addition to non-ASCII characters, use | |
89 | /// [`str::to_lowercase`]. | |
90 | /// | |
abe05a73 | 91 | /// # Note |
c34b1796 | 92 | /// |
abe05a73 XL |
93 | /// This method will be deprecated in favor of the identically-named |
94 | /// inherent methods on `u8`, `char`, `[u8]` and `str`. | |
32a655c1 SL |
95 | /// |
96 | /// [`make_ascii_lowercase`]: #tymethod.make_ascii_lowercase | |
97 | /// [`str::to_lowercase`]: ../primitive.str.html#method.to_lowercase | |
85aaf69f | 98 | #[stable(feature = "rust1", since = "1.0.0")] |
0531ce1d | 99 | #[allow(deprecated)] |
85aaf69f | 100 | fn to_ascii_lowercase(&self) -> Self::Owned; |
1a4d82fc | 101 | |
cc61c64b | 102 | /// Checks that two values are an ASCII case-insensitive match. |
c34b1796 | 103 | /// |
1a4d82fc | 104 | /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`, |
cc61c64b | 105 | /// but without allocating and copying temporaries. |
c34b1796 | 106 | /// |
abe05a73 | 107 | /// # Note |
c34b1796 | 108 | /// |
abe05a73 XL |
109 | /// This method will be deprecated in favor of the identically-named |
110 | /// inherent methods on `u8`, `char`, `[u8]` and `str`. | |
85aaf69f | 111 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 112 | fn eq_ignore_ascii_case(&self, other: &Self) -> bool; |
85aaf69f | 113 | |
9346a6ac | 114 | /// Converts this type to its ASCII upper case equivalent in-place. |
85aaf69f | 115 | /// |
32a655c1 SL |
116 | /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', |
117 | /// but non-ASCII letters are unchanged. | |
118 | /// | |
cc61c64b | 119 | /// To return a new uppercased value without modifying the existing one, use |
32a655c1 | 120 | /// [`to_ascii_uppercase`]. |
c34b1796 | 121 | /// |
abe05a73 | 122 | /// # Note |
c34b1796 | 123 | /// |
abe05a73 XL |
124 | /// This method will be deprecated in favor of the identically-named |
125 | /// inherent methods on `u8`, `char`, `[u8]` and `str`. | |
32a655c1 SL |
126 | /// |
127 | /// [`to_ascii_uppercase`]: #tymethod.to_ascii_uppercase | |
54a0048b | 128 | #[stable(feature = "ascii", since = "1.9.0")] |
85aaf69f SL |
129 | fn make_ascii_uppercase(&mut self); |
130 | ||
9346a6ac | 131 | /// Converts this type to its ASCII lower case equivalent in-place. |
85aaf69f | 132 | /// |
32a655c1 SL |
133 | /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', |
134 | /// but non-ASCII letters are unchanged. | |
135 | /// | |
cc61c64b | 136 | /// To return a new lowercased value without modifying the existing one, use |
32a655c1 | 137 | /// [`to_ascii_lowercase`]. |
c34b1796 | 138 | /// |
abe05a73 | 139 | /// # Note |
c34b1796 | 140 | /// |
abe05a73 XL |
141 | /// This method will be deprecated in favor of the identically-named |
142 | /// inherent methods on `u8`, `char`, `[u8]` and `str`. | |
32a655c1 SL |
143 | /// |
144 | /// [`to_ascii_lowercase`]: #tymethod.to_ascii_lowercase | |
54a0048b | 145 | #[stable(feature = "ascii", since = "1.9.0")] |
85aaf69f | 146 | fn make_ascii_lowercase(&mut self); |
1a4d82fc JJ |
147 | } |
148 | ||
ff7c6d11 XL |
149 | macro_rules! delegating_ascii_methods { |
150 | () => { | |
151 | #[inline] | |
152 | fn is_ascii(&self) -> bool { self.is_ascii() } | |
85aaf69f | 153 | |
ff7c6d11 XL |
154 | #[inline] |
155 | fn to_ascii_uppercase(&self) -> Self::Owned { self.to_ascii_uppercase() } | |
1a4d82fc | 156 | |
ff7c6d11 XL |
157 | #[inline] |
158 | fn to_ascii_lowercase(&self) -> Self::Owned { self.to_ascii_lowercase() } | |
1a4d82fc | 159 | |
ff7c6d11 XL |
160 | #[inline] |
161 | fn eq_ignore_ascii_case(&self, o: &Self) -> bool { self.eq_ignore_ascii_case(o) } | |
1a4d82fc | 162 | |
ff7c6d11 XL |
163 | #[inline] |
164 | fn make_ascii_uppercase(&mut self) { self.make_ascii_uppercase(); } | |
85aaf69f | 165 | |
ff7c6d11 XL |
166 | #[inline] |
167 | fn make_ascii_lowercase(&mut self) { self.make_ascii_lowercase(); } | |
85aaf69f | 168 | } |
ff7c6d11 XL |
169 | } |
170 | ||
ff7c6d11 | 171 | #[stable(feature = "rust1", since = "1.0.0")] |
0531ce1d | 172 | #[allow(deprecated)] |
ff7c6d11 XL |
173 | impl AsciiExt for u8 { |
174 | type Owned = u8; | |
175 | ||
176 | delegating_ascii_methods!(); | |
ff7c6d11 XL |
177 | } |
178 | ||
179 | #[stable(feature = "rust1", since = "1.0.0")] | |
0531ce1d | 180 | #[allow(deprecated)] |
ff7c6d11 XL |
181 | impl AsciiExt for char { |
182 | type Owned = char; | |
183 | ||
184 | delegating_ascii_methods!(); | |
ff7c6d11 XL |
185 | } |
186 | ||
187 | #[stable(feature = "rust1", since = "1.0.0")] | |
0531ce1d | 188 | #[allow(deprecated)] |
ff7c6d11 XL |
189 | impl AsciiExt for [u8] { |
190 | type Owned = Vec<u8>; | |
191 | ||
192 | delegating_ascii_methods!(); | |
1a4d82fc JJ |
193 | } |
194 | ||
85aaf69f | 195 | #[stable(feature = "rust1", since = "1.0.0")] |
0531ce1d | 196 | #[allow(deprecated)] |
ff7c6d11 XL |
197 | impl AsciiExt for str { |
198 | type Owned = String; | |
85aaf69f | 199 | |
ff7c6d11 | 200 | delegating_ascii_methods!(); |
abe05a73 | 201 | } |