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")]
17pub use core::ascii::{escape_default, EscapeDefault};
18
19#[unstable(feature = "ascii_char", issue = "110998")]
20pub 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")]
46pub 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
147macro_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)]
183impl 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)]
191impl 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)]
199impl 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)]
207impl AsciiExt for str {
208 type Owned = String;
209
210 delegating_ascii_methods!();
211}
212