summaryrefslogtreecommitdiffstats
path: root/library/std/src/ascii.rs
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-17 12:02:58 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-17 12:02:58 +0000
commit698f8c2f01ea549d77d7dc3338a12e04c11057b9 (patch)
tree173a775858bd501c378080a10dca74132f05bc50 /library/std/src/ascii.rs
parentInitial commit. (diff)
downloadrustc-698f8c2f01ea549d77d7dc3338a12e04c11057b9.tar.xz
rustc-698f8c2f01ea549d77d7dc3338a12e04c11057b9.zip
Adding upstream version 1.64.0+dfsg1.upstream/1.64.0+dfsg1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'library/std/src/ascii.rs')
-rw-r--r--library/std/src/ascii.rs208
1 files changed, 208 insertions, 0 deletions
diff --git a/library/std/src/ascii.rs b/library/std/src/ascii.rs
new file mode 100644
index 000000000..c29f01577
--- /dev/null
+++ b/library/std/src/ascii.rs
@@ -0,0 +1,208 @@
+//! 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.
+
+#![stable(feature = "rust1", since = "1.0.0")]
+
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use core::ascii::{escape_default, EscapeDefault};
+
+/// Extension methods for ASCII-subset only operations.
+///
+/// Be aware that operations on seemingly non-ASCII characters can sometimes
+/// have unexpected results. Consider this example:
+///
+/// ```
+/// use std::ascii::AsciiExt;
+///
+/// assert_eq!(AsciiExt::to_ascii_uppercase("café"), "CAFÉ");
+/// assert_eq!(AsciiExt::to_ascii_uppercase("café"), "CAFé");
+/// ```
+///
+/// In the first example, the lowercased string is represented `"cafe\u{301}"`
+/// (the last character is an acute accent [combining character]). Unlike the
+/// other characters in the string, the combining character will not get mapped
+/// to an uppercase variant, resulting in `"CAFE\u{301}"`. In the second
+/// example, the lowercased string is represented `"caf\u{e9}"` (the last
+/// character is a single Unicode character representing an 'e' with an acute
+/// accent). Since the last character is defined outside the scope of ASCII,
+/// it will not get mapped to an uppercase variant, resulting in `"CAF\u{e9}"`.
+///
+/// [combining character]: https://en.wikipedia.org/wiki/Combining_character
+#[stable(feature = "rust1", since = "1.0.0")]
+#[deprecated(since = "1.26.0", note = "use inherent methods instead")]
+pub trait AsciiExt {
+ /// Container type for copied ASCII characters.
+ #[stable(feature = "rust1", since = "1.0.0")]
+ type Owned;
+
+ /// Checks if the value is within the ASCII range.
+ ///
+ /// # Note
+ ///
+ /// This method is deprecated in favor of the identically-named
+ /// inherent methods on `u8`, `char`, `[u8]` and `str`.
+ #[stable(feature = "rust1", since = "1.0.0")]
+ 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 is deprecated in favor of the identically-named
+ /// inherent methods on `u8`, `char`, `[u8]` and `str`.
+ ///
+ /// [`make_ascii_uppercase`]: AsciiExt::make_ascii_uppercase
+ #[stable(feature = "rust1", since = "1.0.0")]
+ #[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 is deprecated in favor of the identically-named
+ /// inherent methods on `u8`, `char`, `[u8]` and `str`.
+ ///
+ /// [`make_ascii_lowercase`]: AsciiExt::make_ascii_lowercase
+ #[stable(feature = "rust1", since = "1.0.0")]
+ #[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 is deprecated in favor of the identically-named
+ /// inherent methods on `u8`, `char`, `[u8]` and `str`.
+ #[stable(feature = "rust1", since = "1.0.0")]
+ 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 is deprecated in favor of the identically-named
+ /// inherent methods on `u8`, `char`, `[u8]` and `str`.
+ ///
+ /// [`to_ascii_uppercase`]: AsciiExt::to_ascii_uppercase
+ #[stable(feature = "ascii", since = "1.9.0")]
+ 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 is deprecated in favor of the identically-named
+ /// inherent methods on `u8`, `char`, `[u8]` and `str`.
+ ///
+ /// [`to_ascii_lowercase`]: AsciiExt::to_ascii_lowercase
+ #[stable(feature = "ascii", since = "1.9.0")]
+ 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();
+ }
+ };
+}
+
+#[stable(feature = "rust1", since = "1.0.0")]
+#[allow(deprecated)]
+impl AsciiExt for u8 {
+ type Owned = u8;
+
+ delegating_ascii_methods!();
+}
+
+#[stable(feature = "rust1", since = "1.0.0")]
+#[allow(deprecated)]
+impl AsciiExt for char {
+ type Owned = char;
+
+ delegating_ascii_methods!();
+}
+
+#[stable(feature = "rust1", since = "1.0.0")]
+#[allow(deprecated)]
+impl AsciiExt for [u8] {
+ type Owned = Vec<u8>;
+
+ delegating_ascii_methods!();
+}
+
+#[stable(feature = "rust1", since = "1.0.0")]
+#[allow(deprecated)]
+impl AsciiExt for str {
+ type Owned = String;
+
+ delegating_ascii_methods!();
+}