src/libstd/ascii.rs

   1 // Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! Operations on ASCII strings and characters.
  12 //!
  13 //! Most string operations in Rust act on UTF-8 strings. However, at times it
  14 //! makes more sense to only consider the ASCII character set for a specific
  15 //! operation.
  16 //!
  17 //! The [`AsciiExt`] trait provides methods that allow for character
  18 //! operations that only act on the ASCII subset and leave non-ASCII characters
  19 //! alone.
  20 //!
  21 //! The [`escape_default`] function provides an iterator over the bytes of an
  22 //! escaped version of the character given.
  23 //!
  24 //! [`AsciiExt`]: trait.AsciiExt.html
  25 //! [`escape_default`]: fn.escape_default.html
  26
  27 #![stable(feature = "rust1", since = "1.0.0")]
  28
  29 #[stable(feature = "rust1", since = "1.0.0")]
  30 pub use core::ascii::{EscapeDefault, escape_default};
  31
  32 /// Extension methods for ASCII-subset only operations.
  33 ///
  34 /// Be aware that operations on seemingly non-ASCII characters can sometimes
  35 /// have unexpected results. Consider this example:
  36 ///
  37 /// ```
  38 /// use std::ascii::AsciiExt;
  39 ///
  40 /// assert_eq!(AsciiExt::to_ascii_uppercase("café"), "CAFÉ");
  41 /// assert_eq!(AsciiExt::to_ascii_uppercase("café"), "CAFé");
  42 /// ```
  43 ///
  44 /// In the first example, the lowercased string is represented `"cafe\u{301}"`
  45 /// (the last character is an acute accent [combining character]). Unlike the
  46 /// other characters in the string, the combining character will not get mapped
  47 /// to an uppercase variant, resulting in `"CAFE\u{301}"`. In the second
  48 /// example, the lowercased string is represented `"caf\u{e9}"` (the last
  49 /// character is a single Unicode character representing an 'e' with an acute
  50 /// accent). Since the last character is defined outside the scope of ASCII,
  51 /// it will not get mapped to an uppercase variant, resulting in `"CAF\u{e9}"`.
  52 ///
  53 /// [combining character]: https://en.wikipedia.org/wiki/Combining_character
  54 #[stable(feature = "rust1", since = "1.0.0")]
  55 #[rustc_deprecated(since = "1.26.0", reason = "use inherent methods instead")]
  56 pub trait AsciiExt {
  57     /// Container type for copied ASCII characters.
  58     #[stable(feature = "rust1", since = "1.0.0")]
  59     type Owned;
  60
  61     /// Checks if the value is within the ASCII range.
  62     ///
  63     /// # Note
  64     ///
  65     /// This method will be deprecated in favor of the identically-named
  66     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
  67     #[stable(feature = "rust1", since = "1.0.0")]
  68     fn is_ascii(&self) -> bool;
  69
  70     /// Makes a copy of the value in its ASCII upper case equivalent.
  71     ///
  72     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
  73     /// but non-ASCII letters are unchanged.
  74     ///
  75     /// To uppercase the value in-place, use [`make_ascii_uppercase`].
  76     ///
  77     /// To uppercase ASCII characters in addition to non-ASCII characters, use
  78     /// [`str::to_uppercase`].
  79     ///
  80     /// # Note
  81     ///
  82     /// This method will be deprecated in favor of the identically-named
  83     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
  84     ///
  85     /// [`make_ascii_uppercase`]: #tymethod.make_ascii_uppercase
  86     /// [`str::to_uppercase`]: ../primitive.str.html#method.to_uppercase
  87     #[stable(feature = "rust1", since = "1.0.0")]
  88     #[allow(deprecated)]
  89     fn to_ascii_uppercase(&self) -> Self::Owned;
  90
  91     /// Makes a copy of the value in its ASCII lower case equivalent.
  92     ///
  93     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
  94     /// but non-ASCII letters are unchanged.
  95     ///
  96     /// To lowercase the value in-place, use [`make_ascii_lowercase`].
  97     ///
  98     /// To lowercase ASCII characters in addition to non-ASCII characters, use
  99     /// [`str::to_lowercase`].
 100     ///
 101     /// # Note
 102     ///
 103     /// This method will be deprecated in favor of the identically-named
 104     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 105     ///
 106     /// [`make_ascii_lowercase`]: #tymethod.make_ascii_lowercase
 107     /// [`str::to_lowercase`]: ../primitive.str.html#method.to_lowercase
 108     #[stable(feature = "rust1", since = "1.0.0")]
 109     #[allow(deprecated)]
 110     fn to_ascii_lowercase(&self) -> Self::Owned;
 111
 112     /// Checks that two values are an ASCII case-insensitive match.
 113     ///
 114     /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`,
 115     /// but without allocating and copying temporaries.
 116     ///
 117     /// # Note
 118     ///
 119     /// This method will be deprecated in favor of the identically-named
 120     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 121     #[stable(feature = "rust1", since = "1.0.0")]
 122     fn eq_ignore_ascii_case(&self, other: &Self) -> bool;
 123
 124     /// Converts this type to its ASCII upper case equivalent in-place.
 125     ///
 126     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
 127     /// but non-ASCII letters are unchanged.
 128     ///
 129     /// To return a new uppercased value without modifying the existing one, use
 130     /// [`to_ascii_uppercase`].
 131     ///
 132     /// # Note
 133     ///
 134     /// This method will be deprecated in favor of the identically-named
 135     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 136     ///
 137     /// [`to_ascii_uppercase`]: #tymethod.to_ascii_uppercase
 138     #[stable(feature = "ascii", since = "1.9.0")]
 139     fn make_ascii_uppercase(&mut self);
 140
 141     /// Converts this type to its ASCII lower case equivalent in-place.
 142     ///
 143     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
 144     /// but non-ASCII letters are unchanged.
 145     ///
 146     /// To return a new lowercased value without modifying the existing one, use
 147     /// [`to_ascii_lowercase`].
 148     ///
 149     /// # Note
 150     ///
 151     /// This method will be deprecated in favor of the identically-named
 152     /// inherent methods on `u8`, `char`, `[u8]` and `str`.
 153     ///
 154     /// [`to_ascii_lowercase`]: #tymethod.to_ascii_lowercase
 155     #[stable(feature = "ascii", since = "1.9.0")]
 156     fn make_ascii_lowercase(&mut self);
 157 }
 158
 159 macro_rules! delegating_ascii_methods {
 160     () => {
 161         #[inline]
 162         fn is_ascii(&self) -> bool { self.is_ascii() }
 163
 164         #[inline]
 165         fn to_ascii_uppercase(&self) -> Self::Owned { self.to_ascii_uppercase() }
 166
 167         #[inline]
 168         fn to_ascii_lowercase(&self) -> Self::Owned { self.to_ascii_lowercase() }
 169
 170         #[inline]
 171         fn eq_ignore_ascii_case(&self, o: &Self) -> bool { self.eq_ignore_ascii_case(o) }
 172
 173         #[inline]
 174         fn make_ascii_uppercase(&mut self) { self.make_ascii_uppercase(); }
 175
 176         #[inline]
 177         fn make_ascii_lowercase(&mut self) { self.make_ascii_lowercase(); }
 178     }
 179 }
 180
 181 #[stable(feature = "rust1", since = "1.0.0")]
 182 #[allow(deprecated)]
 183 impl AsciiExt for u8 {
 184     type Owned = u8;
 185
 186     delegating_ascii_methods!();
 187 }
 188
 189 #[stable(feature = "rust1", since = "1.0.0")]
 190 #[allow(deprecated)]
 191 impl AsciiExt for char {
 192     type Owned = char;
 193
 194     delegating_ascii_methods!();
 195 }
 196
 197 #[stable(feature = "rust1", since = "1.0.0")]
 198 #[allow(deprecated)]
 199 impl AsciiExt for [u8] {
 200     type Owned = Vec<u8>;
 201
 202     delegating_ascii_methods!();
 203 }
 204
 205 #[stable(feature = "rust1", since = "1.0.0")]
 206 #[allow(deprecated)]
 207 impl AsciiExt for str {
 208     type Owned = String;
 209
 210     delegating_ascii_methods!();
 211 }