ascii.rs - source
Description: Source of the Rust file `library/std/src/ascii.rs`.

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