library/std/src/ascii.rs

   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")]
  17 pub use core::ascii::{escape_default, EscapeDefault};
  18
  19 /// Extension methods for ASCII-subset only operations.
  20 ///
  21 /// Be aware that operations on seemingly non-ASCII characters can sometimes
  22 /// have unexpected results. Consider this example:
  23 ///
  24 /// ```
  25 /// use std::ascii::AsciiExt;
  26 ///
  27 /// assert_eq!(AsciiExt::to_ascii_uppercase("café"), "CAFÉ");
  28 /// assert_eq!(AsciiExt::to_ascii_uppercase("café"), "CAFé");
  29 /// ```
  30 ///
  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}"`.
  39 ///
  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")]
  43 pub trait AsciiExt {
  44     /// Container type for copied ASCII characters.
  45     #[stable(feature = "rust1", since = "1.0.0")]
  46     type Owned;
  47
  48     /// Checks if the value is within the ASCII range.
  49     ///
  50     /// # Note
  51     ///
  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;
  56
  57     /// Makes a copy of the value in its ASCII upper case equivalent.
  58     ///
  59     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
  60     /// but non-ASCII letters are unchanged.
  61     ///
  62     /// To uppercase the value in-place, use [`make_ascii_uppercase`].
  63     ///
  64     /// To uppercase ASCII characters in addition to non-ASCII characters, use
  65     /// [`str::to_uppercase`].
  66     ///
  67     /// # Note
  68     ///
  69     /// This method is deprecated in favor of the identically-named
  70     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
  71     ///
  72     /// [`make_ascii_uppercase`]: AsciiExt::make_ascii_uppercase
  73     #[stable(feature = "rust1", since = "1.0.0")]
  74     #[allow(deprecated)]
  75     fn to_ascii_uppercase(&self) -> Self::Owned;
  76
  77     /// Makes a copy of the value in its ASCII lower case equivalent.
  78     ///
  79     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
  80     /// but non-ASCII letters are unchanged.
  81     ///
  82     /// To lowercase the value in-place, use [`make_ascii_lowercase`].
  83     ///
  84     /// To lowercase ASCII characters in addition to non-ASCII characters, use
  85     /// [`str::to_lowercase`].
  86     ///
  87     /// # Note
  88     ///
  89     /// This method is deprecated in favor of the identically-named
  90     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
  91     ///
  92     /// [`make_ascii_lowercase`]: AsciiExt::make_ascii_lowercase
  93     #[stable(feature = "rust1", since = "1.0.0")]
  94     #[allow(deprecated)]
  95     fn to_ascii_lowercase(&self) -> Self::Owned;
  96
  97     /// Checks that two values are an ASCII case-insensitive match.
  98     ///
  99     /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`,
 100     /// but without allocating and copying temporaries.
 101     ///
 102     /// # Note
 103     ///
 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;
 108
 109     /// Converts this type to its ASCII upper case equivalent in-place.
 110     ///
 111     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
 112     /// but non-ASCII letters are unchanged.
 113     ///
 114     /// To return a new uppercased value without modifying the existing one, use
 115     /// [`to_ascii_uppercase`].
 116     ///
 117     /// # Note
 118     ///
 119     /// This method is deprecated in favor of the identically-named
 120     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 121     ///
 122     /// [`to_ascii_uppercase`]: AsciiExt::to_ascii_uppercase
 123     #[stable(feature = "ascii", since = "1.9.0")]
 124     fn make_ascii_uppercase(&mut self);
 125
 126     /// Converts this type to its ASCII lower case equivalent in-place.
 127     ///
 128     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
 129     /// but non-ASCII letters are unchanged.
 130     ///
 131     /// To return a new lowercased value without modifying the existing one, use
 132     /// [`to_ascii_lowercase`].
 133     ///
 134     /// # Note
 135     ///
 136     /// This method is deprecated in favor of the identically-named
 137     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 138     ///
 139     /// [`to_ascii_lowercase`]: AsciiExt::to_ascii_lowercase
 140     #[stable(feature = "ascii", since = "1.9.0")]
 141     fn make_ascii_lowercase(&mut self);
 142 }
 143
 144 macro_rules! delegating_ascii_methods {
 145     () => {
 146         #[inline]
 147         fn is_ascii(&self) -> bool {
 148             self.is_ascii()
 149         }
 150
 151         #[inline]
 152         fn to_ascii_uppercase(&self) -> Self::Owned {
 153             self.to_ascii_uppercase()
 154         }
 155
 156         #[inline]
 157         fn to_ascii_lowercase(&self) -> Self::Owned {
 158             self.to_ascii_lowercase()
 159         }
 160
 161         #[inline]
 162         fn eq_ignore_ascii_case(&self, o: &Self) -> bool {
 163             self.eq_ignore_ascii_case(o)
 164         }
 165
 166         #[inline]
 167         fn make_ascii_uppercase(&mut self) {
 168             self.make_ascii_uppercase();
 169         }
 170
 171         #[inline]
 172         fn make_ascii_lowercase(&mut self) {
 173             self.make_ascii_lowercase();
 174         }
 175     };
 176 }
 177
 178 #[stable(feature = "rust1", since = "1.0.0")]
 179 #[allow(deprecated)]
 180 impl AsciiExt for u8 {
 181     type Owned = u8;
 182
 183     delegating_ascii_methods!();
 184 }
 185
 186 #[stable(feature = "rust1", since = "1.0.0")]
 187 #[allow(deprecated)]
 188 impl AsciiExt for char {
 189     type Owned = char;
 190
 191     delegating_ascii_methods!();
 192 }
 193
 194 #[stable(feature = "rust1", since = "1.0.0")]
 195 #[allow(deprecated)]
 196 impl AsciiExt for [u8] {
 197     type Owned = Vec<u8>;
 198
 199     delegating_ascii_methods!();
 200 }
 201
 202 #[stable(feature = "rust1", since = "1.0.0")]
 203 #[allow(deprecated)]
 204 impl AsciiExt for str {
 205     type Owned = String;
 206
 207     delegating_ascii_methods!();
 208 }