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 #[rustc_deprecated(since = "1.26.0", reason = "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 /// [`str::to_uppercase`]: ../primitive.str.html#method.to_uppercase
74 #[stable(feature = "rust1", since = "1.0.0")]
76 fn to_ascii_uppercase(&self) -> Self::Owned;
78 /// Makes a copy of the value in its ASCII lower case equivalent.
80 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
81 /// but non-ASCII letters are unchanged.
83 /// To lowercase the value in-place, use [`make_ascii_lowercase`].
85 /// To lowercase ASCII characters in addition to non-ASCII characters, use
86 /// [`str::to_lowercase`].
90 /// This method is deprecated in favor of the identically-named
91 /// inherent methods on `u8`, `char`, `[u8]` and `str`.
93 /// [`make_ascii_lowercase`]: AsciiExt::make_ascii_lowercase
94 /// [`str::to_lowercase`]: ../primitive.str.html#method.to_lowercase
95 #[stable(feature = "rust1", since = "1.0.0")]
97 fn to_ascii_lowercase(&self) -> Self::Owned;
99 /// Checks that two values are an ASCII case-insensitive match.
101 /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`,
102 /// but without allocating and copying temporaries.
106 /// This method is deprecated in favor of the identically-named
107 /// inherent methods on `u8`, `char`, `[u8]` and `str`.
108 #[stable(feature = "rust1", since = "1.0.0")]
109 fn eq_ignore_ascii_case(&self, other: &Self) -> bool;
111 /// Converts this type to its ASCII upper case equivalent in-place.
113 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
114 /// but non-ASCII letters are unchanged.
116 /// To return a new uppercased value without modifying the existing one, use
117 /// [`to_ascii_uppercase`].
121 /// This method is deprecated in favor of the identically-named
122 /// inherent methods on `u8`, `char`, `[u8]` and `str`.
124 /// [`to_ascii_uppercase`]: AsciiExt::to_ascii_uppercase
125 #[stable(feature = "ascii", since = "1.9.0")]
126 fn make_ascii_uppercase(&mut self);
128 /// Converts this type to its ASCII lower case equivalent in-place.
130 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
131 /// but non-ASCII letters are unchanged.
133 /// To return a new lowercased value without modifying the existing one, use
134 /// [`to_ascii_lowercase`].
138 /// This method is deprecated in favor of the identically-named
139 /// inherent methods on `u8`, `char`, `[u8]` and `str`.
141 /// [`to_ascii_lowercase`]: AsciiExt::to_ascii_lowercase
142 #[stable(feature = "ascii", since = "1.9.0")]
143 fn make_ascii_lowercase(&mut self);
146 macro_rules! delegating_ascii_methods {
149 fn is_ascii(&self) -> bool {
154 fn to_ascii_uppercase(&self) -> Self::Owned {
155 self.to_ascii_uppercase()
159 fn to_ascii_lowercase(&self) -> Self::Owned {
160 self.to_ascii_lowercase()
164 fn eq_ignore_ascii_case(&self, o: &Self) -> bool {
165 self.eq_ignore_ascii_case(o)
169 fn make_ascii_uppercase(&mut self) {
170 self.make_ascii_uppercase();
174 fn make_ascii_lowercase(&mut self) {
175 self.make_ascii_lowercase();
180 #[stable(feature = "rust1", since = "1.0.0")]
182 impl AsciiExt for u8 {
185 delegating_ascii_methods!();
188 #[stable(feature = "rust1", since = "1.0.0")]
190 impl AsciiExt for char {
193 delegating_ascii_methods!();
196 #[stable(feature = "rust1", since = "1.0.0")]
198 impl AsciiExt for [u8] {
199 type Owned = Vec<u8>;
201 delegating_ascii_methods!();
204 #[stable(feature = "rust1", since = "1.0.0")]
206 impl AsciiExt for str {
209 delegating_ascii_methods!();