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 #![stable(feature = "rust1", since = "1.0.0")]
16 #[stable(feature = "rust1", since = "1.0.0")]
17 pub use core::ascii::{escape_default, EscapeDefault};
19 /// Extension methods for ASCII-subset only operations.
21 /// Be aware that operations on seemingly non-ASCII characters can sometimes
22 /// have unexpected results. Consider this example:
25 /// use std::ascii::AsciiExt;
27 /// assert_eq!(AsciiExt::to_ascii_uppercase("café"), "CAFÉ");
28 /// assert_eq!(AsciiExt::to_ascii_uppercase("café"), "CAFé");
31 /// In the first example, the lowercased string is represented `"cafe\u{301}"`
32 /// (the last character is an acute accent [combining character]). Unlike the
33 /// other characters in the string, the combining character will not get mapped
34 /// to an uppercase variant, resulting in `"CAFE\u{301}"`. In the second
35 /// example, the lowercased string is represented `"caf\u{e9}"` (the last
36 /// character is a single Unicode character representing an 'e' with an acute
37 /// accent). Since the last character is defined outside the scope of ASCII,
38 /// it will not get mapped to an uppercase variant, resulting in `"CAF\u{e9}"`.
40 /// [combining character]: https://en.wikipedia.org/wiki/Combining_character
41 #[stable(feature = "rust1", since = "1.0.0")]
42 #[deprecated(since = "1.26.0", note = "use inherent methods instead")]
44 /// Container type for copied ASCII characters.
45 #[stable(feature = "rust1", since = "1.0.0")]
48 /// Checks if the value is within the ASCII range.
52 /// This method is deprecated in favor of the identically-named
53 /// inherent methods on `u8`, `char`, `[u8]` and `str`.
54 #[stable(feature = "rust1", since = "1.0.0")]
55 fn is_ascii(&self) -> bool;
57 /// Makes a copy of the value in its ASCII upper case equivalent.
59 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
60 /// but non-ASCII letters are unchanged.
62 /// To uppercase the value in-place, use [`make_ascii_uppercase`].
64 /// To uppercase ASCII characters in addition to non-ASCII characters, use
65 /// [`str::to_uppercase`].
69 /// This method is deprecated in favor of the identically-named
70 /// inherent methods on `u8`, `char`, `[u8]` and `str`.
72 /// [`make_ascii_uppercase`]: AsciiExt::make_ascii_uppercase
73 #[stable(feature = "rust1", since = "1.0.0")]
75 fn to_ascii_uppercase(&self) -> Self::Owned;
77 /// Makes a copy of the value in its ASCII lower case equivalent.
79 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
80 /// but non-ASCII letters are unchanged.
82 /// To lowercase the value in-place, use [`make_ascii_lowercase`].
84 /// To lowercase ASCII characters in addition to non-ASCII characters, use
85 /// [`str::to_lowercase`].
89 /// This method is deprecated in favor of the identically-named
90 /// inherent methods on `u8`, `char`, `[u8]` and `str`.
92 /// [`make_ascii_lowercase`]: AsciiExt::make_ascii_lowercase
93 #[stable(feature = "rust1", since = "1.0.0")]
95 fn to_ascii_lowercase(&self) -> Self::Owned;
97 /// Checks that two values are an ASCII case-insensitive match.
99 /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`,
100 /// but without allocating and copying temporaries.
104 /// This method is deprecated in favor of the identically-named
105 /// inherent methods on `u8`, `char`, `[u8]` and `str`.
106 #[stable(feature = "rust1", since = "1.0.0")]
107 fn eq_ignore_ascii_case(&self, other: &Self) -> bool;
109 /// Converts this type to its ASCII upper case equivalent in-place.
111 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
112 /// but non-ASCII letters are unchanged.
114 /// To return a new uppercased value without modifying the existing one, use
115 /// [`to_ascii_uppercase`].
119 /// This method is deprecated in favor of the identically-named
120 /// inherent methods on `u8`, `char`, `[u8]` and `str`.
122 /// [`to_ascii_uppercase`]: AsciiExt::to_ascii_uppercase
123 #[stable(feature = "ascii", since = "1.9.0")]
124 fn make_ascii_uppercase(&mut self);
126 /// Converts this type to its ASCII lower case equivalent in-place.
128 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
129 /// but non-ASCII letters are unchanged.
131 /// To return a new lowercased value without modifying the existing one, use
132 /// [`to_ascii_lowercase`].
136 /// This method is deprecated in favor of the identically-named
137 /// inherent methods on `u8`, `char`, `[u8]` and `str`.
139 /// [`to_ascii_lowercase`]: AsciiExt::to_ascii_lowercase
140 #[stable(feature = "ascii", since = "1.9.0")]
141 fn make_ascii_lowercase(&mut self);
144 macro_rules! delegating_ascii_methods {
147 fn is_ascii(&self) -> bool {
152 fn to_ascii_uppercase(&self) -> Self::Owned {
153 self.to_ascii_uppercase()
157 fn to_ascii_lowercase(&self) -> Self::Owned {
158 self.to_ascii_lowercase()
162 fn eq_ignore_ascii_case(&self, o: &Self) -> bool {
163 self.eq_ignore_ascii_case(o)
167 fn make_ascii_uppercase(&mut self) {
168 self.make_ascii_uppercase();
172 fn make_ascii_lowercase(&mut self) {
173 self.make_ascii_lowercase();
178 #[stable(feature = "rust1", since = "1.0.0")]
180 impl AsciiExt for u8 {
183 delegating_ascii_methods!();
186 #[stable(feature = "rust1", since = "1.0.0")]
188 impl AsciiExt for char {
191 delegating_ascii_methods!();
194 #[stable(feature = "rust1", since = "1.0.0")]
196 impl AsciiExt for [u8] {
197 type Owned = Vec<u8>;
199 delegating_ascii_methods!();
202 #[stable(feature = "rust1", since = "1.0.0")]
204 impl AsciiExt for str {
207 delegating_ascii_methods!();