| // Copyright (C) 2017-2019 Baidu, Inc. All Rights Reserved. |
| // |
| // Redistribution and use in source and binary forms, with or without |
| // modification, are permitted provided that the following conditions |
| // are met: |
| // |
| // * Redistributions of source code must retain the above copyright |
| // notice, this list of conditions and the following disclaimer. |
| // * Redistributions in binary form must reproduce the above copyright |
| // notice, this list of conditions and the following disclaimer in |
| // the documentation and/or other materials provided with the |
| // distribution. |
| // * Neither the name of Baidu, Inc., nor the names of its |
| // contributors may be used to endorse or promote products derived |
| // from this software without specific prior written permission. |
| // |
| // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
| // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
| // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
| // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| |
| //! Operations on ASCII strings and characters. |
| //! |
| //! Most string operations in Rust act on UTF-8 strings. However, at times it |
| //! makes more sense to only consider the ASCII character set for a specific |
| //! operation. |
| //! |
| //! The [`AsciiExt`] trait provides methods that allow for character |
| //! operations that only act on the ASCII subset and leave non-ASCII characters |
| //! alone. |
| //! |
| //! The [`escape_default`] function provides an iterator over the bytes of an |
| //! escaped version of the character given. |
| //! |
| //! [`AsciiExt`]: trait.AsciiExt.html |
| //! [`escape_default`]: fn.escape_default.html |
| |
| use alloc::vec::Vec; |
| use alloc::string::String; |
| |
| pub use core::ascii::{EscapeDefault, escape_default}; |
| |
| /// Extension methods for ASCII-subset only operations. |
| /// |
| /// Be aware that operations on seemingly non-ASCII characters can sometimes |
| /// have unexpected results. |
| /// |
| pub trait AsciiExt { |
| /// Container type for copied ASCII characters. |
| type Owned; |
| |
| /// Checks if the value is within the ASCII range. |
| /// |
| /// # Note |
| /// |
| /// This method will be deprecated in favor of the identically-named |
| /// inherent methods on `u8`, `char`, `[u8]` and `str`. |
| fn is_ascii(&self) -> bool; |
| |
| /// Makes a copy of the value in its ASCII upper case equivalent. |
| /// |
| /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', |
| /// but non-ASCII letters are unchanged. |
| /// |
| /// To uppercase the value in-place, use [`make_ascii_uppercase`]. |
| /// |
| /// To uppercase ASCII characters in addition to non-ASCII characters, use |
| /// [`str::to_uppercase`]. |
| /// |
| /// # Note |
| /// |
| /// This method will be deprecated in favor of the identically-named |
| /// inherent methods on `u8`, `char`, `[u8]` and `str`. |
| /// |
| #[allow(deprecated)] |
| fn to_ascii_uppercase(&self) -> Self::Owned; |
| |
| /// Makes a copy of the value in its ASCII lower case equivalent. |
| /// |
| /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', |
| /// but non-ASCII letters are unchanged. |
| /// |
| /// To lowercase the value in-place, use [`make_ascii_lowercase`]. |
| /// |
| /// To lowercase ASCII characters in addition to non-ASCII characters, use |
| /// [`str::to_lowercase`]. |
| /// |
| /// # Note |
| /// |
| /// This method will be deprecated in favor of the identically-named |
| /// inherent methods on `u8`, `char`, `[u8]` and `str`. |
| /// |
| #[allow(deprecated)] |
| fn to_ascii_lowercase(&self) -> Self::Owned; |
| |
| /// Checks that two values are an ASCII case-insensitive match. |
| /// |
| /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`, |
| /// but without allocating and copying temporaries. |
| /// |
| /// # Note |
| /// |
| /// This method will be deprecated in favor of the identically-named |
| /// inherent methods on `u8`, `char`, `[u8]` and `str`. |
| fn eq_ignore_ascii_case(&self, other: &Self) -> bool; |
| |
| /// Converts this type to its ASCII upper case equivalent in-place. |
| /// |
| /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', |
| /// but non-ASCII letters are unchanged. |
| /// |
| /// To return a new uppercased value without modifying the existing one, use |
| /// [`to_ascii_uppercase`]. |
| /// |
| /// # Note |
| /// |
| /// This method will be deprecated in favor of the identically-named |
| /// inherent methods on `u8`, `char`, `[u8]` and `str`. |
| /// |
| fn make_ascii_uppercase(&mut self); |
| |
| /// Converts this type to its ASCII lower case equivalent in-place. |
| /// |
| /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', |
| /// but non-ASCII letters are unchanged. |
| /// |
| /// To return a new lowercased value without modifying the existing one, use |
| /// [`to_ascii_lowercase`]. |
| /// |
| /// # Note |
| /// |
| /// This method will be deprecated in favor of the identically-named |
| /// inherent methods on `u8`, `char`, `[u8]` and `str`. |
| /// |
| fn make_ascii_lowercase(&mut self); |
| } |
| |
| macro_rules! delegating_ascii_methods { |
| () => { |
| #[inline] |
| fn is_ascii(&self) -> bool { self.is_ascii() } |
| |
| #[inline] |
| fn to_ascii_uppercase(&self) -> Self::Owned { self.to_ascii_uppercase() } |
| |
| #[inline] |
| fn to_ascii_lowercase(&self) -> Self::Owned { self.to_ascii_lowercase() } |
| |
| #[inline] |
| fn eq_ignore_ascii_case(&self, o: &Self) -> bool { self.eq_ignore_ascii_case(o) } |
| |
| #[inline] |
| fn make_ascii_uppercase(&mut self) { self.make_ascii_uppercase(); } |
| |
| #[inline] |
| fn make_ascii_lowercase(&mut self) { self.make_ascii_lowercase(); } |
| } |
| } |
| |
| #[allow(deprecated)] |
| impl AsciiExt for u8 { |
| type Owned = u8; |
| |
| delegating_ascii_methods!(); |
| } |
| |
| #[allow(deprecated)] |
| impl AsciiExt for char { |
| type Owned = char; |
| |
| delegating_ascii_methods!(); |
| } |
| |
| #[allow(deprecated)] |
| impl AsciiExt for [u8] { |
| type Owned = Vec<u8>; |
| |
| delegating_ascii_methods!(); |
| } |
| |
| #[allow(deprecated)] |
| impl AsciiExt for str { |
| type Owned = String; |
| |
| delegating_ascii_methods!(); |
| } |