src/libstd/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 //! [`AsciiExt`]: trait.AsciiExt.html
  15 //! [`escape_default`]: fn.escape_default.html
  16
  17 #![stable(feature = "rust1", since = "1.0.0")]
  18
  19 #[stable(feature = "rust1", since = "1.0.0")]
  20 pub use core::ascii::{escape_default, EscapeDefault};
  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("café"), "CAFÉ");
  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 #[rustc_deprecated(since = "1.26.0", reason = "use inherent methods instead")]
  46 pub 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 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;
  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 will be deprecated in favor of the identically-named
  73     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
  74     ///
  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")]
  78     #[allow(deprecated)]
  79     fn to_ascii_uppercase(&self) -> Self::Owned;
  80
  81     /// Makes a copy of the value in its ASCII lower case equivalent.
  82     ///
  83     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
  84     /// but non-ASCII letters are unchanged.
  85     ///
  86     /// To lowercase the value in-place, use [`make_ascii_lowercase`].
  87     ///
  88     /// To lowercase ASCII characters in addition to non-ASCII characters, use
  89     /// [`str::to_lowercase`].
  90     ///
  91     /// # Note
  92     ///
  93     /// This method will be deprecated in favor of the identically-named
  94     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
  95     ///
  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")]
  99     #[allow(deprecated)]
 100     fn to_ascii_lowercase(&self) -> Self::Owned;
 101
 102     /// Checks that two values are an ASCII case-insensitive match.
 103     ///
 104     /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`,
 105     /// but without allocating and copying temporaries.
 106     ///
 107     /// # Note
 108     ///
 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;
 113
 114     /// Converts this type to its ASCII upper case equivalent in-place.
 115     ///
 116     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
 117     /// but non-ASCII letters are unchanged.
 118     ///
 119     /// To return a new uppercased value without modifying the existing one, use
 120     /// [`to_ascii_uppercase`].
 121     ///
 122     /// # Note
 123     ///
 124     /// This method will be deprecated in favor of the identically-named
 125     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 126     ///
 127     /// [`to_ascii_uppercase`]: #tymethod.to_ascii_uppercase
 128     #[stable(feature = "ascii", since = "1.9.0")]
 129     fn make_ascii_uppercase(&mut self);
 130
 131     /// Converts this type to its ASCII lower case equivalent in-place.
 132     ///
 133     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
 134     /// but non-ASCII letters are unchanged.
 135     ///
 136     /// To return a new lowercased value without modifying the existing one, use
 137     /// [`to_ascii_lowercase`].
 138     ///
 139     /// # Note
 140     ///
 141     /// This method will be deprecated in favor of the identically-named
 142     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 143     ///
 144     /// [`to_ascii_lowercase`]: #tymethod.to_ascii_lowercase
 145     #[stable(feature = "ascii", since = "1.9.0")]
 146     fn make_ascii_lowercase(&mut self);
 147 }
 148
 149 macro_rules! delegating_ascii_methods {
 150     () => {
 151         #[inline]
 152         fn is_ascii(&self) -> bool { self.is_ascii() }
 153
 154         #[inline]
 155         fn to_ascii_uppercase(&self) -> Self::Owned { self.to_ascii_uppercase() }
 156
 157         #[inline]
 158         fn to_ascii_lowercase(&self) -> Self::Owned { self.to_ascii_lowercase() }
 159
 160         #[inline]
 161         fn eq_ignore_ascii_case(&self, o: &Self) -> bool { self.eq_ignore_ascii_case(o) }
 162
 163         #[inline]
 164         fn make_ascii_uppercase(&mut self) { self.make_ascii_uppercase(); }
 165
 166         #[inline]
 167         fn make_ascii_lowercase(&mut self) { self.make_ascii_lowercase(); }
 168     }
 169 }
 170
 171 #[stable(feature = "rust1", since = "1.0.0")]
 172 #[allow(deprecated)]
 173 impl AsciiExt for u8 {
 174     type Owned = u8;
 175
 176     delegating_ascii_methods!();
 177 }
 178
 179 #[stable(feature = "rust1", since = "1.0.0")]
 180 #[allow(deprecated)]
 181 impl AsciiExt for char {
 182     type Owned = char;
 183
 184     delegating_ascii_methods!();
 185 }
 186
 187 #[stable(feature = "rust1", since = "1.0.0")]
 188 #[allow(deprecated)]
 189 impl AsciiExt for [u8] {
 190     type Owned = Vec<u8>;
 191
 192     delegating_ascii_methods!();
 193 }
 194
 195 #[stable(feature = "rust1", since = "1.0.0")]
 196 #[allow(deprecated)]
 197 impl AsciiExt for str {
 198     type Owned = String;
 199
 200     delegating_ascii_methods!();
 201 }