1 //! Operations on ASCII strings and characters.
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
7 //! The [`AsciiExt`] trait provides methods that allow for character
8 //! operations that only act on the ASCII subset and leave non-ASCII characters
11 //! The [`escape_default`] function provides an iterator over the bytes of an
12 //! escaped version of the character given.
14 //! [`AsciiExt`]: trait.AsciiExt.html
15 //! [`escape_default`]: fn.escape_default.html
17 #![stable(feature = "rust1", since = "1.0.0")]
19 #[stable(feature = "rust1", since = "1.0.0")]
20 pub use core::ascii::{EscapeDefault, escape_default};
22 /// Extension methods for ASCII-subset only operations.
24 /// Be aware that operations on seemingly non-ASCII characters can sometimes
25 /// have unexpected results. Consider this example:
28 /// use std::ascii::AsciiExt;
30 /// assert_eq!(AsciiExt::to_ascii_uppercase("café"), "CAFÉ");
31 /// assert_eq!(AsciiExt::to_ascii_uppercase("café"), "CAFé");
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}"`.
43 /// [combining character]: https://en.wikipedia.org/wiki/Combining_character
44 #[stable(feature = "rust1", since = "1.0.0")]
45 #[rustc_deprecated(since = "1.26.0", reason = "use inherent methods instead")]
47 /// Container type for copied ASCII characters.
48 #[stable(feature = "rust1", since = "1.0.0")]
51 /// Checks if the value is within the ASCII range.
55 /// This method will be 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;
60 /// Makes a copy of the value in its ASCII upper case equivalent.
62 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
63 /// but non-ASCII letters are unchanged.
65 /// To uppercase the value in-place, use [`make_ascii_uppercase`].
67 /// To uppercase ASCII characters in addition to non-ASCII characters, use
68 /// [`str::to_uppercase`].
72 /// This method will be deprecated in favor of the identically-named
73 /// inherent methods on `u8`, `char`, `[u8]` and `str`.
75 /// [`make_ascii_uppercase`]: #tymethod.make_ascii_uppercase
76 /// [`str::to_uppercase`]: ../primitive.str.html#method.to_uppercase
77 #[stable(feature = "rust1", since = "1.0.0")]
79 fn to_ascii_uppercase(&self) -> Self::Owned;
81 /// Makes a copy of the value in its ASCII lower case equivalent.
83 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
84 /// but non-ASCII letters are unchanged.
86 /// To lowercase the value in-place, use [`make_ascii_lowercase`].
88 /// To lowercase ASCII characters in addition to non-ASCII characters, use
89 /// [`str::to_lowercase`].
93 /// This method will be deprecated in favor of the identically-named
94 /// inherent methods on `u8`, `char`, `[u8]` and `str`.
96 /// [`make_ascii_lowercase`]: #tymethod.make_ascii_lowercase
97 /// [`str::to_lowercase`]: ../primitive.str.html#method.to_lowercase
98 #[stable(feature = "rust1", since = "1.0.0")]
100 fn to_ascii_lowercase(&self) -> Self::Owned;
102 /// Checks that two values are an ASCII case-insensitive match.
104 /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`,
105 /// but without allocating and copying temporaries.
109 /// This method will be deprecated in favor of the identically-named
110 /// inherent methods on `u8`, `char`, `[u8]` and `str`.
111 #[stable(feature = "rust1", since = "1.0.0")]
112 fn eq_ignore_ascii_case(&self, other: &Self) -> bool;
114 /// Converts this type to its ASCII upper case equivalent in-place.
116 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
117 /// but non-ASCII letters are unchanged.
119 /// To return a new uppercased value without modifying the existing one, use
120 /// [`to_ascii_uppercase`].
124 /// This method will be deprecated in favor of the identically-named
125 /// inherent methods on `u8`, `char`, `[u8]` and `str`.
127 /// [`to_ascii_uppercase`]: #tymethod.to_ascii_uppercase
128 #[stable(feature = "ascii", since = "1.9.0")]
129 fn make_ascii_uppercase(&mut self);
131 /// Converts this type to its ASCII lower case equivalent in-place.
133 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
134 /// but non-ASCII letters are unchanged.
136 /// To return a new lowercased value without modifying the existing one, use
137 /// [`to_ascii_lowercase`].
141 /// This method will be deprecated in favor of the identically-named
142 /// inherent methods on `u8`, `char`, `[u8]` and `str`.
144 /// [`to_ascii_lowercase`]: #tymethod.to_ascii_lowercase
145 #[stable(feature = "ascii", since = "1.9.0")]
146 fn make_ascii_lowercase(&mut self);
149 macro_rules! delegating_ascii_methods {
152 fn is_ascii(&self) -> bool { self.is_ascii() }
155 fn to_ascii_uppercase(&self) -> Self::Owned { self.to_ascii_uppercase() }
158 fn to_ascii_lowercase(&self) -> Self::Owned { self.to_ascii_lowercase() }
161 fn eq_ignore_ascii_case(&self, o: &Self) -> bool { self.eq_ignore_ascii_case(o) }
164 fn make_ascii_uppercase(&mut self) { self.make_ascii_uppercase(); }
167 fn make_ascii_lowercase(&mut self) { self.make_ascii_lowercase(); }
171 #[stable(feature = "rust1", since = "1.0.0")]
173 impl AsciiExt for u8 {
176 delegating_ascii_methods!();
179 #[stable(feature = "rust1", since = "1.0.0")]
181 impl AsciiExt for char {
184 delegating_ascii_methods!();
187 #[stable(feature = "rust1", since = "1.0.0")]
189 impl AsciiExt for [u8] {
190 type Owned = Vec<u8>;
192 delegating_ascii_methods!();
195 #[stable(feature = "rust1", since = "1.0.0")]
197 impl AsciiExt for str {
200 delegating_ascii_methods!();