summaryrefslogtreecommitdiffstats
path: root/library/core/src/char
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/core/src/char
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/core/src/char')
-rw-r--r--library/core/src/char/convert.rs258
-rw-r--r--library/core/src/char/decode.rs123
-rw-r--r--library/core/src/char/methods.rs1741
-rw-r--r--library/core/src/char/mod.rs584
4 files changed, 2706 insertions, 0 deletions
diff --git a/library/core/src/char/convert.rs b/library/core/src/char/convert.rs
new file mode 100644
index 000000000..7c5f82f5e
--- /dev/null
+++ b/library/core/src/char/convert.rs
@@ -0,0 +1,258 @@
+//! Character conversions.
+
+use crate::char::TryFromCharError;
+use crate::convert::TryFrom;
+use crate::fmt;
+use crate::mem::transmute;
+use crate::str::FromStr;
+
+/// Converts a `u32` to a `char`. See [`char::from_u32`].
+#[must_use]
+#[inline]
+pub(super) const fn from_u32(i: u32) -> Option<char> {
+ // FIXME: once Result::ok is const fn, use it here
+ match char_try_from_u32(i) {
+ Ok(c) => Some(c),
+ Err(_) => None,
+ }
+}
+
+/// Converts a `u32` to a `char`, ignoring validity. See [`char::from_u32_unchecked`].
+#[rustc_const_unstable(feature = "const_char_convert", issue = "89259")]
+#[inline]
+#[must_use]
+pub(super) const unsafe fn from_u32_unchecked(i: u32) -> char {
+ // SAFETY: the caller must guarantee that `i` is a valid char value.
+ if cfg!(debug_assertions) { char::from_u32(i).unwrap() } else { unsafe { transmute(i) } }
+}
+
+#[stable(feature = "char_convert", since = "1.13.0")]
+#[rustc_const_unstable(feature = "const_convert", issue = "88674")]
+impl const From<char> for u32 {
+ /// Converts a [`char`] into a [`u32`].
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use std::mem;
+ ///
+ /// let c = 'c';
+ /// let u = u32::from(c);
+ /// assert!(4 == mem::size_of_val(&u))
+ /// ```
+ #[inline]
+ fn from(c: char) -> Self {
+ c as u32
+ }
+}
+
+#[stable(feature = "more_char_conversions", since = "1.51.0")]
+#[rustc_const_unstable(feature = "const_convert", issue = "88674")]
+impl const From<char> for u64 {
+ /// Converts a [`char`] into a [`u64`].
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use std::mem;
+ ///
+ /// let c = '👤';
+ /// let u = u64::from(c);
+ /// assert!(8 == mem::size_of_val(&u))
+ /// ```
+ #[inline]
+ fn from(c: char) -> Self {
+ // The char is casted to the value of the code point, then zero-extended to 64 bit.
+ // See [https://doc.rust-lang.org/reference/expressions/operator-expr.html#semantics]
+ c as u64
+ }
+}
+
+#[stable(feature = "more_char_conversions", since = "1.51.0")]
+#[rustc_const_unstable(feature = "const_convert", issue = "88674")]
+impl const From<char> for u128 {
+ /// Converts a [`char`] into a [`u128`].
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use std::mem;
+ ///
+ /// let c = '⚙';
+ /// let u = u128::from(c);
+ /// assert!(16 == mem::size_of_val(&u))
+ /// ```
+ #[inline]
+ fn from(c: char) -> Self {
+ // The char is casted to the value of the code point, then zero-extended to 128 bit.
+ // See [https://doc.rust-lang.org/reference/expressions/operator-expr.html#semantics]
+ c as u128
+ }
+}
+
+/// Map `char` with code point in U+0000..=U+00FF to byte in 0x00..=0xFF with same value, failing
+/// if the code point is greater than U+00FF.
+///
+/// See [`impl From<u8> for char`](char#impl-From<u8>-for-char) for details on the encoding.
+#[stable(feature = "u8_from_char", since = "1.59.0")]
+impl TryFrom<char> for u8 {
+ type Error = TryFromCharError;
+
+ #[inline]
+ fn try_from(c: char) -> Result<u8, Self::Error> {
+ u8::try_from(u32::from(c)).map_err(|_| TryFromCharError(()))
+ }
+}
+
+/// Maps a byte in 0x00..=0xFF to a `char` whose code point has the same value, in U+0000..=U+00FF.
+///
+/// Unicode is designed such that this effectively decodes bytes
+/// with the character encoding that IANA calls ISO-8859-1.
+/// This encoding is compatible with ASCII.
+///
+/// Note that this is different from ISO/IEC 8859-1 a.k.a. ISO 8859-1 (with one less hyphen),
+/// which leaves some "blanks", byte values that are not assigned to any character.
+/// ISO-8859-1 (the IANA one) assigns them to the C0 and C1 control codes.
+///
+/// Note that this is *also* different from Windows-1252 a.k.a. code page 1252,
+/// which is a superset ISO/IEC 8859-1 that assigns some (not all!) blanks
+/// to punctuation and various Latin characters.
+///
+/// To confuse things further, [on the Web](https://encoding.spec.whatwg.org/)
+/// `ascii`, `iso-8859-1`, and `windows-1252` are all aliases
+/// for a superset of Windows-1252 that fills the remaining blanks with corresponding
+/// C0 and C1 control codes.
+#[stable(feature = "char_convert", since = "1.13.0")]
+#[rustc_const_unstable(feature = "const_convert", issue = "88674")]
+impl const From<u8> for char {
+ /// Converts a [`u8`] into a [`char`].
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use std::mem;
+ ///
+ /// let u = 32 as u8;
+ /// let c = char::from(u);
+ /// assert!(4 == mem::size_of_val(&c))
+ /// ```
+ #[inline]
+ fn from(i: u8) -> Self {
+ i as char
+ }
+}
+
+/// An error which can be returned when parsing a char.
+///
+/// This `struct` is created when using the [`char::from_str`] method.
+#[stable(feature = "char_from_str", since = "1.20.0")]
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ParseCharError {
+ kind: CharErrorKind,
+}
+
+impl ParseCharError {
+ #[unstable(
+ feature = "char_error_internals",
+ reason = "this method should not be available publicly",
+ issue = "none"
+ )]
+ #[doc(hidden)]
+ pub fn __description(&self) -> &str {
+ match self.kind {
+ CharErrorKind::EmptyString => "cannot parse char from empty string",
+ CharErrorKind::TooManyChars => "too many characters in string",
+ }
+ }
+}
+
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+enum CharErrorKind {
+ EmptyString,
+ TooManyChars,
+}
+
+#[stable(feature = "char_from_str", since = "1.20.0")]
+impl fmt::Display for ParseCharError {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ self.__description().fmt(f)
+ }
+}
+
+#[stable(feature = "char_from_str", since = "1.20.0")]
+impl FromStr for char {
+ type Err = ParseCharError;
+
+ #[inline]
+ fn from_str(s: &str) -> Result<Self, Self::Err> {
+ let mut chars = s.chars();
+ match (chars.next(), chars.next()) {
+ (None, _) => Err(ParseCharError { kind: CharErrorKind::EmptyString }),
+ (Some(c), None) => Ok(c),
+ _ => Err(ParseCharError { kind: CharErrorKind::TooManyChars }),
+ }
+ }
+}
+
+#[inline]
+const fn char_try_from_u32(i: u32) -> Result<char, CharTryFromError> {
+ // This is an optimized version of the check
+ // (i > MAX as u32) || (i >= 0xD800 && i <= 0xDFFF),
+ // which can also be written as
+ // i >= 0x110000 || (i >= 0xD800 && i < 0xE000).
+ //
+ // The XOR with 0xD800 permutes the ranges such that 0xD800..0xE000 is
+ // mapped to 0x0000..0x0800, while keeping all the high bits outside 0xFFFF the same.
+ // In particular, numbers >= 0x110000 stay in this range.
+ //
+ // Subtracting 0x800 causes 0x0000..0x0800 to wrap, meaning that a single
+ // unsigned comparison against 0x110000 - 0x800 will detect both the wrapped
+ // surrogate range as well as the numbers originally larger than 0x110000.
+ //
+ if (i ^ 0xD800).wrapping_sub(0x800) >= 0x110000 - 0x800 {
+ Err(CharTryFromError(()))
+ } else {
+ // SAFETY: checked that it's a legal unicode value
+ Ok(unsafe { transmute(i) })
+ }
+}
+
+#[stable(feature = "try_from", since = "1.34.0")]
+impl TryFrom<u32> for char {
+ type Error = CharTryFromError;
+
+ #[inline]
+ fn try_from(i: u32) -> Result<Self, Self::Error> {
+ char_try_from_u32(i)
+ }
+}
+
+/// The error type returned when a conversion from [`prim@u32`] to [`prim@char`] fails.
+///
+/// This `struct` is created by the [`char::try_from<u32>`](char#impl-TryFrom<u32>-for-char) method.
+/// See its documentation for more.
+#[stable(feature = "try_from", since = "1.34.0")]
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+pub struct CharTryFromError(());
+
+#[stable(feature = "try_from", since = "1.34.0")]
+impl fmt::Display for CharTryFromError {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ "converted integer out of range for `char`".fmt(f)
+ }
+}
+
+/// Converts a digit in the given radix to a `char`. See [`char::from_digit`].
+#[inline]
+#[must_use]
+pub(super) const fn from_digit(num: u32, radix: u32) -> Option<char> {
+ if radix > 36 {
+ panic!("from_digit: radix is too high (maximum 36)");
+ }
+ if num < radix {
+ let num = num as u8;
+ if num < 10 { Some((b'0' + num) as char) } else { Some((b'a' + num - 10) as char) }
+ } else {
+ None
+ }
+}
diff --git a/library/core/src/char/decode.rs b/library/core/src/char/decode.rs
new file mode 100644
index 000000000..71297acd1
--- /dev/null
+++ b/library/core/src/char/decode.rs
@@ -0,0 +1,123 @@
+//! UTF-8 and UTF-16 decoding iterators
+
+use crate::fmt;
+
+use super::from_u32_unchecked;
+
+/// An iterator that decodes UTF-16 encoded code points from an iterator of `u16`s.
+///
+/// This `struct` is created by the [`decode_utf16`] method on [`char`]. See its
+/// documentation for more.
+///
+/// [`decode_utf16`]: char::decode_utf16
+#[stable(feature = "decode_utf16", since = "1.9.0")]
+#[derive(Clone, Debug)]
+pub struct DecodeUtf16<I>
+where
+ I: Iterator<Item = u16>,
+{
+ iter: I,
+ buf: Option<u16>,
+}
+
+/// An error that can be returned when decoding UTF-16 code points.
+///
+/// This `struct` is created when using the [`DecodeUtf16`] type.
+#[stable(feature = "decode_utf16", since = "1.9.0")]
+#[derive(Debug, Clone, Eq, PartialEq)]
+pub struct DecodeUtf16Error {
+ code: u16,
+}
+
+/// Creates an iterator over the UTF-16 encoded code points in `iter`,
+/// returning unpaired surrogates as `Err`s. See [`char::decode_utf16`].
+#[inline]
+pub(super) fn decode_utf16<I: IntoIterator<Item = u16>>(iter: I) -> DecodeUtf16<I::IntoIter> {
+ DecodeUtf16 { iter: iter.into_iter(), buf: None }
+}
+
+#[stable(feature = "decode_utf16", since = "1.9.0")]
+impl<I: Iterator<Item = u16>> Iterator for DecodeUtf16<I> {
+ type Item = Result<char, DecodeUtf16Error>;
+
+ fn next(&mut self) -> Option<Result<char, DecodeUtf16Error>> {
+ let u = match self.buf.take() {
+ Some(buf) => buf,
+ None => self.iter.next()?,
+ };
+
+ if !u.is_utf16_surrogate() {
+ // SAFETY: not a surrogate
+ Some(Ok(unsafe { from_u32_unchecked(u as u32) }))
+ } else if u >= 0xDC00 {
+ // a trailing surrogate
+ Some(Err(DecodeUtf16Error { code: u }))
+ } else {
+ let u2 = match self.iter.next() {
+ Some(u2) => u2,
+ // eof
+ None => return Some(Err(DecodeUtf16Error { code: u })),
+ };
+ if u2 < 0xDC00 || u2 > 0xDFFF {
+ // not a trailing surrogate so we're not a valid
+ // surrogate pair, so rewind to redecode u2 next time.
+ self.buf = Some(u2);
+ return Some(Err(DecodeUtf16Error { code: u }));
+ }
+
+ // all ok, so lets decode it.
+ let c = (((u - 0xD800) as u32) << 10 | (u2 - 0xDC00) as u32) + 0x1_0000;
+ // SAFETY: we checked that it's a legal unicode value
+ Some(Ok(unsafe { from_u32_unchecked(c) }))
+ }
+ }
+
+ #[inline]
+ fn size_hint(&self) -> (usize, Option<usize>) {
+ let (low, high) = self.iter.size_hint();
+
+ let (low_buf, high_buf) = match self.buf {
+ // buf is empty, no additional elements from it.
+ None => (0, 0),
+ // `u` is a non surrogate, so it's always an additional character.
+ Some(u) if !u.is_utf16_surrogate() => (1, 1),
+ // `u` is a leading surrogate (it can never be a trailing surrogate and
+ // it's a surrogate due to the previous branch) and `self.iter` is empty.
+ //
+ // `u` can't be paired, since the `self.iter` is empty,
+ // so it will always become an additional element (error).
+ Some(_u) if high == Some(0) => (1, 1),
+ // `u` is a leading surrogate and `iter` may be non-empty.
+ //
+ // `u` can either pair with a trailing surrogate, in which case no additional elements
+ // are produced, or it can become an error, in which case it's an additional character (error).
+ Some(_u) => (0, 1),
+ };
+
+ // `self.iter` could contain entirely valid surrogates (2 elements per
+ // char), or entirely non-surrogates (1 element per char).
+ //
+ // On odd lower bound, at least one element must stay unpaired
+ // (with other elements from `self.iter`), so we round up.
+ let low = low.div_ceil(2) + low_buf;
+ let high = high.and_then(|h| h.checked_add(high_buf));
+
+ (low, high)
+ }
+}
+
+impl DecodeUtf16Error {
+ /// Returns the unpaired surrogate which caused this error.
+ #[must_use]
+ #[stable(feature = "decode_utf16", since = "1.9.0")]
+ pub fn unpaired_surrogate(&self) -> u16 {
+ self.code
+ }
+}
+
+#[stable(feature = "decode_utf16", since = "1.9.0")]
+impl fmt::Display for DecodeUtf16Error {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ write!(f, "unpaired surrogate found: {:x}", self.code)
+ }
+}
diff --git a/library/core/src/char/methods.rs b/library/core/src/char/methods.rs
new file mode 100644
index 000000000..eae567cad
--- /dev/null
+++ b/library/core/src/char/methods.rs
@@ -0,0 +1,1741 @@
+//! impl char {}
+
+use crate::slice;
+use crate::str::from_utf8_unchecked_mut;
+use crate::unicode::printable::is_printable;
+use crate::unicode::{self, conversions};
+
+use super::*;
+
+impl char {
+ /// The highest valid code point a `char` can have, `'\u{10FFFF}'`.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// # fn something_which_returns_char() -> char { 'a' }
+ /// let c: char = something_which_returns_char();
+ /// assert!(c <= char::MAX);
+ ///
+ /// let value_at_max = char::MAX as u32;
+ /// assert_eq!(char::from_u32(value_at_max), Some('\u{10FFFF}'));
+ /// assert_eq!(char::from_u32(value_at_max + 1), None);
+ /// ```
+ #[stable(feature = "assoc_char_consts", since = "1.52.0")]
+ pub const MAX: char = '\u{10ffff}';
+
+ /// `U+FFFD REPLACEMENT CHARACTER` (�) is used in Unicode to represent a
+ /// decoding error.
+ ///
+ /// It can occur, for example, when giving ill-formed UTF-8 bytes to
+ /// [`String::from_utf8_lossy`](../std/string/struct.String.html#method.from_utf8_lossy).
+ #[stable(feature = "assoc_char_consts", since = "1.52.0")]
+ pub const REPLACEMENT_CHARACTER: char = '\u{FFFD}';
+
+ /// The version of [Unicode](https://www.unicode.org/) that the Unicode parts of
+ /// `char` and `str` methods are based on.
+ ///
+ /// New versions of Unicode are released regularly and subsequently all methods
+ /// in the standard library depending on Unicode are updated. Therefore the
+ /// behavior of some `char` and `str` methods and the value of this constant
+ /// changes over time. This is *not* considered to be a breaking change.
+ ///
+ /// The version numbering scheme is explained in
+ /// [Unicode 11.0 or later, Section 3.1 Versions of the Unicode Standard](https://www.unicode.org/versions/Unicode11.0.0/ch03.pdf#page=4).
+ #[stable(feature = "assoc_char_consts", since = "1.52.0")]
+ pub const UNICODE_VERSION: (u8, u8, u8) = crate::unicode::UNICODE_VERSION;
+
+ /// Creates an iterator over the UTF-16 encoded code points in `iter`,
+ /// returning unpaired surrogates as `Err`s.
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// use std::char::decode_utf16;
+ ///
+ /// // 𝄞mus<invalid>ic<invalid>
+ /// let v = [
+ /// 0xD834, 0xDD1E, 0x006d, 0x0075, 0x0073, 0xDD1E, 0x0069, 0x0063, 0xD834,
+ /// ];
+ ///
+ /// assert_eq!(
+ /// decode_utf16(v)
+ /// .map(|r| r.map_err(|e| e.unpaired_surrogate()))
+ /// .collect::<Vec<_>>(),
+ /// vec![
+ /// Ok('𝄞'),
+ /// Ok('m'), Ok('u'), Ok('s'),
+ /// Err(0xDD1E),
+ /// Ok('i'), Ok('c'),
+ /// Err(0xD834)
+ /// ]
+ /// );
+ /// ```
+ ///
+ /// A lossy decoder can be obtained by replacing `Err` results with the replacement character:
+ ///
+ /// ```
+ /// use std::char::{decode_utf16, REPLACEMENT_CHARACTER};
+ ///
+ /// // 𝄞mus<invalid>ic<invalid>
+ /// let v = [
+ /// 0xD834, 0xDD1E, 0x006d, 0x0075, 0x0073, 0xDD1E, 0x0069, 0x0063, 0xD834,
+ /// ];
+ ///
+ /// assert_eq!(
+ /// decode_utf16(v)
+ /// .map(|r| r.unwrap_or(REPLACEMENT_CHARACTER))
+ /// .collect::<String>(),
+ /// "𝄞mus�ic�"
+ /// );
+ /// ```
+ #[stable(feature = "assoc_char_funcs", since = "1.52.0")]
+ #[inline]
+ pub fn decode_utf16<I: IntoIterator<Item = u16>>(iter: I) -> DecodeUtf16<I::IntoIter> {
+ super::decode::decode_utf16(iter)
+ }
+
+ /// Converts a `u32` to a `char`.
+ ///
+ /// Note that all `char`s are valid [`u32`]s, and can be cast to one with
+ /// [`as`](../std/keyword.as.html):
+ ///
+ /// ```
+ /// let c = '💯';
+ /// let i = c as u32;
+ ///
+ /// assert_eq!(128175, i);
+ /// ```
+ ///
+ /// However, the reverse is not true: not all valid [`u32`]s are valid
+ /// `char`s. `from_u32()` will return `None` if the input is not a valid value
+ /// for a `char`.
+ ///
+ /// For an unsafe version of this function which ignores these checks, see
+ /// [`from_u32_unchecked`].
+ ///
+ /// [`from_u32_unchecked`]: #method.from_u32_unchecked
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// use std::char;
+ ///
+ /// let c = char::from_u32(0x2764);
+ ///
+ /// assert_eq!(Some('❤'), c);
+ /// ```
+ ///
+ /// Returning `None` when the input is not a valid `char`:
+ ///
+ /// ```
+ /// use std::char;
+ ///
+ /// let c = char::from_u32(0x110000);
+ ///
+ /// assert_eq!(None, c);
+ /// ```
+ #[stable(feature = "assoc_char_funcs", since = "1.52.0")]
+ #[rustc_const_unstable(feature = "const_char_convert", issue = "89259")]
+ #[must_use]
+ #[inline]
+ pub const fn from_u32(i: u32) -> Option<char> {
+ super::convert::from_u32(i)
+ }
+
+ /// Converts a `u32` to a `char`, ignoring validity.
+ ///
+ /// Note that all `char`s are valid [`u32`]s, and can be cast to one with
+ /// `as`:
+ ///
+ /// ```
+ /// let c = '💯';
+ /// let i = c as u32;
+ ///
+ /// assert_eq!(128175, i);
+ /// ```
+ ///
+ /// However, the reverse is not true: not all valid [`u32`]s are valid
+ /// `char`s. `from_u32_unchecked()` will ignore this, and blindly cast to
+ /// `char`, possibly creating an invalid one.
+ ///
+ /// # Safety
+ ///
+ /// This function is unsafe, as it may construct invalid `char` values.
+ ///
+ /// For a safe version of this function, see the [`from_u32`] function.
+ ///
+ /// [`from_u32`]: #method.from_u32
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// use std::char;
+ ///
+ /// let c = unsafe { char::from_u32_unchecked(0x2764) };
+ ///
+ /// assert_eq!('❤', c);
+ /// ```
+ #[stable(feature = "assoc_char_funcs", since = "1.52.0")]
+ #[rustc_const_unstable(feature = "const_char_convert", issue = "89259")]
+ #[must_use]
+ #[inline]
+ pub const unsafe fn from_u32_unchecked(i: u32) -> char {
+ // SAFETY: the safety contract must be upheld by the caller.
+ unsafe { super::convert::from_u32_unchecked(i) }
+ }
+
+ /// Converts a digit in the given radix to a `char`.
+ ///
+ /// A 'radix' here is sometimes also called a 'base'. A radix of two
+ /// indicates a binary number, a radix of ten, decimal, and a radix of
+ /// sixteen, hexadecimal, to give some common values. Arbitrary
+ /// radices are supported.
+ ///
+ /// `from_digit()` will return `None` if the input is not a digit in
+ /// the given radix.
+ ///
+ /// # Panics
+ ///
+ /// Panics if given a radix larger than 36.
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// use std::char;
+ ///
+ /// let c = char::from_digit(4, 10);
+ ///
+ /// assert_eq!(Some('4'), c);
+ ///
+ /// // Decimal 11 is a single digit in base 16
+ /// let c = char::from_digit(11, 16);
+ ///
+ /// assert_eq!(Some('b'), c);
+ /// ```
+ ///
+ /// Returning `None` when the input is not a digit:
+ ///
+ /// ```
+ /// use std::char;
+ ///
+ /// let c = char::from_digit(20, 10);
+ ///
+ /// assert_eq!(None, c);
+ /// ```
+ ///
+ /// Passing a large radix, causing a panic:
+ ///
+ /// ```should_panic
+ /// use std::char;
+ ///
+ /// // this panics
+ /// let _c = char::from_digit(1, 37);
+ /// ```
+ #[stable(feature = "assoc_char_funcs", since = "1.52.0")]
+ #[rustc_const_unstable(feature = "const_char_convert", issue = "89259")]
+ #[must_use]
+ #[inline]
+ pub const fn from_digit(num: u32, radix: u32) -> Option<char> {
+ super::convert::from_digit(num, radix)
+ }
+
+ /// Checks if a `char` is a digit in the given radix.
+ ///
+ /// A 'radix' here is sometimes also called a 'base'. A radix of two
+ /// indicates a binary number, a radix of ten, decimal, and a radix of
+ /// sixteen, hexadecimal, to give some common values. Arbitrary
+ /// radices are supported.
+ ///
+ /// Compared to [`is_numeric()`], this function only recognizes the characters
+ /// `0-9`, `a-z` and `A-Z`.
+ ///
+ /// 'Digit' is defined to be only the following characters:
+ ///
+ /// * `0-9`
+ /// * `a-z`
+ /// * `A-Z`
+ ///
+ /// For a more comprehensive understanding of 'digit', see [`is_numeric()`].
+ ///
+ /// [`is_numeric()`]: #method.is_numeric
+ ///
+ /// # Panics
+ ///
+ /// Panics if given a radix larger than 36.
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// assert!('1'.is_digit(10));
+ /// assert!('f'.is_digit(16));
+ /// assert!(!'f'.is_digit(10));
+ /// ```
+ ///
+ /// Passing a large radix, causing a panic:
+ ///
+ /// ```should_panic
+ /// // this panics
+ /// '1'.is_digit(37);
+ /// ```
+ #[stable(feature = "rust1", since = "1.0.0")]
+ #[inline]
+ pub fn is_digit(self, radix: u32) -> bool {
+ self.to_digit(radix).is_some()
+ }
+
+ /// Converts a `char` to a digit in the given radix.
+ ///
+ /// A 'radix' here is sometimes also called a 'base'. A radix of two
+ /// indicates a binary number, a radix of ten, decimal, and a radix of
+ /// sixteen, hexadecimal, to give some common values. Arbitrary
+ /// radices are supported.
+ ///
+ /// 'Digit' is defined to be only the following characters:
+ ///
+ /// * `0-9`
+ /// * `a-z`
+ /// * `A-Z`
+ ///
+ /// # Errors
+ ///
+ /// Returns `None` if the `char` does not refer to a digit in the given radix.
+ ///
+ /// # Panics
+ ///
+ /// Panics if given a radix larger than 36.
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// assert_eq!('1'.to_digit(10), Some(1));
+ /// assert_eq!('f'.to_digit(16), Some(15));
+ /// ```
+ ///
+ /// Passing a non-digit results in failure:
+ ///
+ /// ```
+ /// assert_eq!('f'.to_digit(10), None);
+ /// assert_eq!('z'.to_digit(16), None);
+ /// ```
+ ///
+ /// Passing a large radix, causing a panic:
+ ///
+ /// ```should_panic
+ /// // this panics
+ /// let _ = '1'.to_digit(37);
+ /// ```
+ #[stable(feature = "rust1", since = "1.0.0")]
+ #[rustc_const_unstable(feature = "const_char_convert", issue = "89259")]
+ #[must_use = "this returns the result of the operation, \
+ without modifying the original"]
+ #[inline]
+ pub const fn to_digit(self, radix: u32) -> Option<u32> {
+ // If not a digit, a number greater than radix will be created.
+ let mut digit = (self as u32).wrapping_sub('0' as u32);
+ if radix > 10 {
+ assert!(radix <= 36, "to_digit: radix is too high (maximum 36)");
+ if digit < 10 {
+ return Some(digit);
+ }
+ // Force the 6th bit to be set to ensure ascii is lower case.
+ digit = (self as u32 | 0b10_0000).wrapping_sub('a' as u32).saturating_add(10);
+ }
+ // FIXME: once then_some is const fn, use it here
+ if digit < radix { Some(digit) } else { None }
+ }
+
+ /// Returns an iterator that yields the hexadecimal Unicode escape of a
+ /// character as `char`s.
+ ///
+ /// This will escape characters with the Rust syntax of the form
+ /// `\u{NNNNNN}` where `NNNNNN` is a hexadecimal representation.
+ ///
+ /// # Examples
+ ///
+ /// As an iterator:
+ ///
+ /// ```
+ /// for c in '❤'.escape_unicode() {
+ /// print!("{c}");
+ /// }
+ /// println!();
+ /// ```
+ ///
+ /// Using `println!` directly:
+ ///
+ /// ```
+ /// println!("{}", '❤'.escape_unicode());
+ /// ```
+ ///
+ /// Both are equivalent to:
+ ///
+ /// ```
+ /// println!("\\u{{2764}}");
+ /// ```
+ ///
+ /// Using [`to_string`](../std/string/trait.ToString.html#tymethod.to_string):
+ ///
+ /// ```
+ /// assert_eq!('❤'.escape_unicode().to_string(), "\\u{2764}");
+ /// ```
+ #[must_use = "this returns the escaped char as an iterator, \
+ without modifying the original"]
+ #[stable(feature = "rust1", since = "1.0.0")]
+ #[inline]
+ pub fn escape_unicode(self) -> EscapeUnicode {
+ let c = self as u32;
+
+ // or-ing 1 ensures that for c==0 the code computes that one
+ // digit should be printed and (which is the same) avoids the
+ // (31 - 32) underflow
+ let msb = 31 - (c | 1).leading_zeros();
+
+ // the index of the most significant hex digit
+ let ms_hex_digit = msb / 4;
+ EscapeUnicode {
+ c: self,
+ state: EscapeUnicodeState::Backslash,
+ hex_digit_idx: ms_hex_digit as usize,
+ }
+ }
+
+ /// An extended version of `escape_debug` that optionally permits escaping
+ /// Extended Grapheme codepoints, single quotes, and double quotes. This
+ /// allows us to format characters like nonspacing marks better when they're
+ /// at the start of a string, and allows escaping single quotes in
+ /// characters, and double quotes in strings.
+ #[inline]
+ pub(crate) fn escape_debug_ext(self, args: EscapeDebugExtArgs) -> EscapeDebug {
+ let init_state = match self {
+ '\0' => EscapeDefaultState::Backslash('0'),
+ '\t' => EscapeDefaultState::Backslash('t'),
+ '\r' => EscapeDefaultState::Backslash('r'),
+ '\n' => EscapeDefaultState::Backslash('n'),
+ '\\' => EscapeDefaultState::Backslash(self),
+ '"' if args.escape_double_quote => EscapeDefaultState::Backslash(self),
+ '\'' if args.escape_single_quote => EscapeDefaultState::Backslash(self),
+ _ if args.escape_grapheme_extended && self.is_grapheme_extended() => {
+ EscapeDefaultState::Unicode(self.escape_unicode())
+ }
+ _ if is_printable(self) => EscapeDefaultState::Char(self),
+ _ => EscapeDefaultState::Unicode(self.escape_unicode()),
+ };
+ EscapeDebug(EscapeDefault { state: init_state })
+ }
+
+ /// Returns an iterator that yields the literal escape code of a character
+ /// as `char`s.
+ ///
+ /// This will escape the characters similar to the [`Debug`](core::fmt::Debug) implementations
+ /// of `str` or `char`.
+ ///
+ /// # Examples
+ ///
+ /// As an iterator:
+ ///
+ /// ```
+ /// for c in '\n'.escape_debug() {
+ /// print!("{c}");
+ /// }
+ /// println!();
+ /// ```
+ ///
+ /// Using `println!` directly:
+ ///
+ /// ```
+ /// println!("{}", '\n'.escape_debug());
+ /// ```
+ ///
+ /// Both are equivalent to:
+ ///
+ /// ```
+ /// println!("\\n");
+ /// ```
+ ///
+ /// Using [`to_string`](../std/string/trait.ToString.html#tymethod.to_string):
+ ///
+ /// ```
+ /// assert_eq!('\n'.escape_debug().to_string(), "\\n");
+ /// ```
+ #[must_use = "this returns the escaped char as an iterator, \
+ without modifying the original"]
+ #[stable(feature = "char_escape_debug", since = "1.20.0")]
+ #[inline]
+ pub fn escape_debug(self) -> EscapeDebug {
+ self.escape_debug_ext(EscapeDebugExtArgs::ESCAPE_ALL)
+ }
+
+ /// Returns an iterator that yields the literal escape code of a character
+ /// as `char`s.
+ ///
+ /// The default is chosen with a bias toward producing literals that are
+ /// legal in a variety of languages, including C++11 and similar C-family
+ /// languages. The exact rules are:
+ ///
+ /// * Tab is escaped as `\t`.
+ /// * Carriage return is escaped as `\r`.
+ /// * Line feed is escaped as `\n`.
+ /// * Single quote is escaped as `\'`.
+ /// * Double quote is escaped as `\"`.
+ /// * Backslash is escaped as `\\`.
+ /// * Any character in the 'printable ASCII' range `0x20` .. `0x7e`
+ /// inclusive is not escaped.
+ /// * All other characters are given hexadecimal Unicode escapes; see
+ /// [`escape_unicode`].
+ ///
+ /// [`escape_unicode`]: #method.escape_unicode
+ ///
+ /// # Examples
+ ///
+ /// As an iterator:
+ ///
+ /// ```
+ /// for c in '"'.escape_default() {
+ /// print!("{c}");
+ /// }
+ /// println!();
+ /// ```
+ ///
+ /// Using `println!` directly:
+ ///
+ /// ```
+ /// println!("{}", '"'.escape_default());
+ /// ```
+ ///
+ /// Both are equivalent to:
+ ///
+ /// ```
+ /// println!("\\\"");
+ /// ```
+ ///
+ /// Using [`to_string`](../std/string/trait.ToString.html#tymethod.to_string):
+ ///
+ /// ```
+ /// assert_eq!('"'.escape_default().to_string(), "\\\"");
+ /// ```
+ #[must_use = "this returns the escaped char as an iterator, \
+ without modifying the original"]
+ #[stable(feature = "rust1", since = "1.0.0")]
+ #[inline]
+ pub fn escape_default(self) -> EscapeDefault {
+ let init_state = match self {
+ '\t' => EscapeDefaultState::Backslash('t'),
+ '\r' => EscapeDefaultState::Backslash('r'),
+ '\n' => EscapeDefaultState::Backslash('n'),
+ '\\' | '\'' | '"' => EscapeDefaultState::Backslash(self),
+ '\x20'..='\x7e' => EscapeDefaultState::Char(self),
+ _ => EscapeDefaultState::Unicode(self.escape_unicode()),
+ };
+ EscapeDefault { state: init_state }
+ }
+
+ /// Returns the number of bytes this `char` would need if encoded in UTF-8.
+ ///
+ /// That number of bytes is always between 1 and 4, inclusive.
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// let len = 'A'.len_utf8();
+ /// assert_eq!(len, 1);
+ ///
+ /// let len = 'ß'.len_utf8();
+ /// assert_eq!(len, 2);
+ ///
+ /// let len = 'ℝ'.len_utf8();
+ /// assert_eq!(len, 3);
+ ///
+ /// let len = '💣'.len_utf8();
+ /// assert_eq!(len, 4);
+ /// ```
+ ///
+ /// The `&str` type guarantees that its contents are UTF-8, and so we can compare the length it
+ /// would take if each code point was represented as a `char` vs in the `&str` itself:
+ ///
+ /// ```
+ /// // as chars
+ /// let eastern = '東';
+ /// let capital = '京';
+ ///
+ /// // both can be represented as three bytes
+ /// assert_eq!(3, eastern.len_utf8());
+ /// assert_eq!(3, capital.len_utf8());
+ ///
+ /// // as a &str, these two are encoded in UTF-8
+ /// let tokyo = "東京";
+ ///
+ /// let len = eastern.len_utf8() + capital.len_utf8();
+ ///
+ /// // we can see that they take six bytes total...
+ /// assert_eq!(6, tokyo.len());
+ ///
+ /// // ... just like the &str
+ /// assert_eq!(len, tokyo.len());
+ /// ```
+ #[stable(feature = "rust1", since = "1.0.0")]
+ #[rustc_const_stable(feature = "const_char_len_utf", since = "1.52.0")]
+ #[inline]
+ pub const fn len_utf8(self) -> usize {
+ len_utf8(self as u32)
+ }
+
+ /// Returns the number of 16-bit code units this `char` would need if
+ /// encoded in UTF-16.
+ ///
+ /// See the documentation for [`len_utf8()`] for more explanation of this
+ /// concept. This function is a mirror, but for UTF-16 instead of UTF-8.
+ ///
+ /// [`len_utf8()`]: #method.len_utf8
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// let n = 'ß'.len_utf16();
+ /// assert_eq!(n, 1);
+ ///
+ /// let len = '💣'.len_utf16();
+ /// assert_eq!(len, 2);
+ /// ```
+ #[stable(feature = "rust1", since = "1.0.0")]
+ #[rustc_const_stable(feature = "const_char_len_utf", since = "1.52.0")]
+ #[inline]
+ pub const fn len_utf16(self) -> usize {
+ let ch = self as u32;
+ if (ch & 0xFFFF) == ch { 1 } else { 2 }
+ }
+
+ /// Encodes this character as UTF-8 into the provided byte buffer,
+ /// and then returns the subslice of the buffer that contains the encoded character.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the buffer is not large enough.
+ /// A buffer of length four is large enough to encode any `char`.
+ ///
+ /// # Examples
+ ///
+ /// In both of these examples, 'ß' takes two bytes to encode.
+ ///
+ /// ```
+ /// let mut b = [0; 2];
+ ///
+ /// let result = 'ß'.encode_utf8(&mut b);
+ ///
+ /// assert_eq!(result, "ß");
+ ///
+ /// assert_eq!(result.len(), 2);
+ /// ```
+ ///
+ /// A buffer that's too small:
+ ///
+ /// ```should_panic
+ /// let mut b = [0; 1];
+ ///
+ /// // this panics
+ /// 'ß'.encode_utf8(&mut b);
+ /// ```
+ #[stable(feature = "unicode_encode_char", since = "1.15.0")]
+ #[inline]
+ pub fn encode_utf8(self, dst: &mut [u8]) -> &mut str {
+ // SAFETY: `char` is not a surrogate, so this is valid UTF-8.
+ unsafe { from_utf8_unchecked_mut(encode_utf8_raw(self as u32, dst)) }
+ }
+
+ /// Encodes this character as UTF-16 into the provided `u16` buffer,
+ /// and then returns the subslice of the buffer that contains the encoded character.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the buffer is not large enough.
+ /// A buffer of length 2 is large enough to encode any `char`.
+ ///
+ /// # Examples
+ ///
+ /// In both of these examples, '𝕊' takes two `u16`s to encode.
+ ///
+ /// ```
+ /// let mut b = [0; 2];
+ ///
+ /// let result = '𝕊'.encode_utf16(&mut b);
+ ///
+ /// assert_eq!(result.len(), 2);
+ /// ```
+ ///
+ /// A buffer that's too small:
+ ///
+ /// ```should_panic
+ /// let mut b = [0; 1];
+ ///
+ /// // this panics
+ /// '𝕊'.encode_utf16(&mut b);
+ /// ```
+ #[stable(feature = "unicode_encode_char", since = "1.15.0")]
+ #[inline]
+ pub fn encode_utf16(self, dst: &mut [u16]) -> &mut [u16] {
+ encode_utf16_raw(self as u32, dst)
+ }
+
+ /// Returns `true` if this `char` has the `Alphabetic` property.
+ ///
+ /// `Alphabetic` is described in Chapter 4 (Character Properties) of the [Unicode Standard] and
+ /// specified in the [Unicode Character Database][ucd] [`DerivedCoreProperties.txt`].
+ ///
+ /// [Unicode Standard]: https://www.unicode.org/versions/latest/
+ /// [ucd]: https://www.unicode.org/reports/tr44/
+ /// [`DerivedCoreProperties.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/DerivedCoreProperties.txt
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// assert!('a'.is_alphabetic());
+ /// assert!('京'.is_alphabetic());
+ ///
+ /// let c = '💝';
+ /// // love is many things, but it is not alphabetic
+ /// assert!(!c.is_alphabetic());
+ /// ```
+ #[must_use]
+ #[stable(feature = "rust1", since = "1.0.0")]
+ #[inline]
+ pub fn is_alphabetic(self) -> bool {
+ match self {
+ 'a'..='z' | 'A'..='Z' => true,
+ c => c > '\x7f' && unicode::Alphabetic(c),
+ }
+ }
+
+ /// Returns `true` if this `char` has the `Lowercase` property.
+ ///
+ /// `Lowercase` is described in Chapter 4 (Character Properties) of the [Unicode Standard] and
+ /// specified in the [Unicode Character Database][ucd] [`DerivedCoreProperties.txt`].
+ ///
+ /// [Unicode Standard]: https://www.unicode.org/versions/latest/
+ /// [ucd]: https://www.unicode.org/reports/tr44/
+ /// [`DerivedCoreProperties.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/DerivedCoreProperties.txt
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// assert!('a'.is_lowercase());
+ /// assert!('δ'.is_lowercase());
+ /// assert!(!'A'.is_lowercase());
+ /// assert!(!'Δ'.is_lowercase());
+ ///
+ /// // The various Chinese scripts and punctuation do not have case, and so:
+ /// assert!(!'中'.is_lowercase());
+ /// assert!(!' '.is_lowercase());
+ /// ```
+ #[must_use]
+ #[stable(feature = "rust1", since = "1.0.0")]
+ #[inline]
+ pub fn is_lowercase(self) -> bool {
+ match self {
+ 'a'..='z' => true,
+ c => c > '\x7f' && unicode::Lowercase(c),
+ }
+ }
+
+ /// Returns `true` if this `char` has the `Uppercase` property.
+ ///
+ /// `Uppercase` is described in Chapter 4 (Character Properties) of the [Unicode Standard] and
+ /// specified in the [Unicode Character Database][ucd] [`DerivedCoreProperties.txt`].
+ ///
+ /// [Unicode Standard]: https://www.unicode.org/versions/latest/
+ /// [ucd]: https://www.unicode.org/reports/tr44/
+ /// [`DerivedCoreProperties.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/DerivedCoreProperties.txt
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// assert!(!'a'.is_uppercase());
+ /// assert!(!'δ'.is_uppercase());
+ /// assert!('A'.is_uppercase());
+ /// assert!('Δ'.is_uppercase());
+ ///
+ /// // The various Chinese scripts and punctuation do not have case, and so:
+ /// assert!(!'中'.is_uppercase());
+ /// assert!(!' '.is_uppercase());
+ /// ```
+ #[must_use]
+ #[stable(feature = "rust1", since = "1.0.0")]
+ #[inline]
+ pub fn is_uppercase(self) -> bool {
+ match self {
+ 'A'..='Z' => true,
+ c => c > '\x7f' && unicode::Uppercase(c),
+ }
+ }
+
+ /// Returns `true` if this `char` has the `White_Space` property.
+ ///
+ /// `White_Space` is specified in the [Unicode Character Database][ucd] [`PropList.txt`].
+ ///
+ /// [ucd]: https://www.unicode.org/reports/tr44/
+ /// [`PropList.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/PropList.txt
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// assert!(' '.is_whitespace());
+ ///
+ /// // line break
+ /// assert!('\n'.is_whitespace());
+ ///
+ /// // a non-breaking space
+ /// assert!('\u{A0}'.is_whitespace());
+ ///
+ /// assert!(!'越'.is_whitespace());
+ /// ```
+ #[must_use]
+ #[stable(feature = "rust1", since = "1.0.0")]
+ #[inline]
+ pub fn is_whitespace(self) -> bool {
+ match self {
+ ' ' | '\x09'..='\x0d' => true,
+ c => c > '\x7f' && unicode::White_Space(c),
+ }
+ }
+
+ /// Returns `true` if this `char` satisfies either [`is_alphabetic()`] or [`is_numeric()`].
+ ///
+ /// [`is_alphabetic()`]: #method.is_alphabetic
+ /// [`is_numeric()`]: #method.is_numeric
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// assert!('٣'.is_alphanumeric());
+ /// assert!('7'.is_alphanumeric());
+ /// assert!('৬'.is_alphanumeric());
+ /// assert!('¾'.is_alphanumeric());
+ /// assert!('①'.is_alphanumeric());
+ /// assert!('K'.is_alphanumeric());
+ /// assert!('و'.is_alphanumeric());
+ /// assert!('藏'.is_alphanumeric());
+ /// ```
+ #[must_use]
+ #[stable(feature = "rust1", since = "1.0.0")]
+ #[inline]
+ pub fn is_alphanumeric(self) -> bool {
+ self.is_alphabetic() || self.is_numeric()
+ }
+
+ /// Returns `true` if this `char` has the general category for control codes.
+ ///
+ /// Control codes (code points with the general category of `Cc`) are described in Chapter 4
+ /// (Character Properties) of the [Unicode Standard] and specified in the [Unicode Character
+ /// Database][ucd] [`UnicodeData.txt`].
+ ///
+ /// [Unicode Standard]: https://www.unicode.org/versions/latest/
+ /// [ucd]: https://www.unicode.org/reports/tr44/
+ /// [`UnicodeData.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// // U+009C, STRING TERMINATOR
+ /// assert!('œ'.is_control());
+ /// assert!(!'q'.is_control());
+ /// ```
+ #[must_use]
+ #[stable(feature = "rust1", since = "1.0.0")]
+ #[inline]
+ pub fn is_control(self) -> bool {
+ unicode::Cc(self)
+ }
+
+ /// Returns `true` if this `char` has the `Grapheme_Extend` property.
+ ///
+ /// `Grapheme_Extend` is described in [Unicode Standard Annex #29 (Unicode Text
+ /// Segmentation)][uax29] and specified in the [Unicode Character Database][ucd]
+ /// [`DerivedCoreProperties.txt`].
+ ///
+ /// [uax29]: https://www.unicode.org/reports/tr29/
+ /// [ucd]: https://www.unicode.org/reports/tr44/
+ /// [`DerivedCoreProperties.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/DerivedCoreProperties.txt
+ #[must_use]
+ #[inline]
+ pub(crate) fn is_grapheme_extended(self) -> bool {
+ unicode::Grapheme_Extend(self)
+ }
+
+ /// Returns `true` if this `char` has one of the general categories for numbers.
+ ///
+ /// The general categories for numbers (`Nd` for decimal digits, `Nl` for letter-like numeric
+ /// characters, and `No` for other numeric characters) are specified in the [Unicode Character
+ /// Database][ucd] [`UnicodeData.txt`]. Note that this means ideographic numbers like '三'
+ /// are considered alphabetic, not numeric. Please consider to use `is_ascii_digit` or `is_digit`.
+ ///
+ /// This method doesn't cover everything that could be considered a number, e.g. ideographic numbers like '三'.
+ /// If you want everything including characters with overlapping purposes then you might want to use
+ /// a unicode or language-processing library that exposes the appropriate character properties instead
+ /// of looking at the unicode categories.
+ ///
+ /// If you want to parse ASCII decimal digits (0-9) or ASCII base-N, use
+ /// `is_ascii_digit` or `is_digit` instead.
+ ///
+ /// [Unicode Standard]: https://www.unicode.org/versions/latest/
+ /// [ucd]: https://www.unicode.org/reports/tr44/
+ /// [`UnicodeData.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// assert!('٣'.is_numeric());
+ /// assert!('7'.is_numeric());
+ /// assert!('৬'.is_numeric());
+ /// assert!('¾'.is_numeric());
+ /// assert!('①'.is_numeric());
+ /// assert!(!'K'.is_numeric());
+ /// assert!(!'و'.is_numeric());
+ /// assert!(!'藏'.is_numeric());
+ /// assert!(!'三'.is_numeric());
+ /// ```
+ #[must_use]
+ #[stable(feature = "rust1", since = "1.0.0")]
+ #[inline]
+ pub fn is_numeric(self) -> bool {
+ match self {
+ '0'..='9' => true,
+ c => c > '\x7f' && unicode::N(c),
+ }
+ }
+
+ /// Returns an iterator that yields the lowercase mapping of this `char` as one or more
+ /// `char`s.
+ ///
+ /// If this `char` does not have a lowercase mapping, the iterator yields the same `char`.
+ ///
+ /// If this `char` has a one-to-one lowercase mapping given by the [Unicode Character
+ /// Database][ucd] [`UnicodeData.txt`], the iterator yields that `char`.
+ ///
+ /// [ucd]: https://www.unicode.org/reports/tr44/
+ /// [`UnicodeData.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt
+ ///
+ /// If this `char` requires special considerations (e.g. multiple `char`s) the iterator yields
+ /// the `char`(s) given by [`SpecialCasing.txt`].
+ ///
+ /// [`SpecialCasing.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/SpecialCasing.txt
+ ///
+ /// This operation performs an unconditional mapping without tailoring. That is, the conversion
+ /// is independent of context and language.
+ ///
+ /// In the [Unicode Standard], Chapter 4 (Character Properties) discusses case mapping in
+ /// general and Chapter 3 (Conformance) discusses the default algorithm for case conversion.
+ ///
+ /// [Unicode Standard]: https://www.unicode.org/versions/latest/
+ ///
+ /// # Examples
+ ///
+ /// As an iterator:
+ ///
+ /// ```
+ /// for c in 'İ'.to_lowercase() {
+ /// print!("{c}");
+ /// }
+ /// println!();
+ /// ```
+ ///
+ /// Using `println!` directly:
+ ///
+ /// ```
+ /// println!("{}", 'İ'.to_lowercase());
+ /// ```
+ ///
+ /// Both are equivalent to:
+ ///
+ /// ```
+ /// println!("i\u{307}");
+ /// ```
+ ///
+ /// Using [`to_string`](../std/string/trait.ToString.html#tymethod.to_string):
+ ///
+ /// ```
+ /// assert_eq!('C'.to_lowercase().to_string(), "c");
+ ///
+ /// // Sometimes the result is more than one character:
+ /// assert_eq!('İ'.to_lowercase().to_string(), "i\u{307}");
+ ///
+ /// // Characters that do not have both uppercase and lowercase
+ /// // convert into themselves.
+ /// assert_eq!('山'.to_lowercase().to_string(), "山");
+ /// ```
+ #[must_use = "this returns the lowercase character as a new iterator, \
+ without modifying the original"]
+ #[stable(feature = "rust1", since = "1.0.0")]
+ #[inline]
+ pub fn to_lowercase(self) -> ToLowercase {
+ ToLowercase(CaseMappingIter::new(conversions::to_lower(self)))
+ }
+
+ /// Returns an iterator that yields the uppercase mapping of this `char` as one or more
+ /// `char`s.
+ ///
+ /// If this `char` does not have an uppercase mapping, the iterator yields the same `char`.
+ ///
+ /// If this `char` has a one-to-one uppercase mapping given by the [Unicode Character
+ /// Database][ucd] [`UnicodeData.txt`], the iterator yields that `char`.
+ ///
+ /// [ucd]: https://www.unicode.org/reports/tr44/
+ /// [`UnicodeData.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt
+ ///
+ /// If this `char` requires special considerations (e.g. multiple `char`s) the iterator yields
+ /// the `char`(s) given by [`SpecialCasing.txt`].
+ ///
+ /// [`SpecialCasing.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/SpecialCasing.txt
+ ///
+ /// This operation performs an unconditional mapping without tailoring. That is, the conversion
+ /// is independent of context and language.
+ ///
+ /// In the [Unicode Standard], Chapter 4 (Character Properties) discusses case mapping in
+ /// general and Chapter 3 (Conformance) discusses the default algorithm for case conversion.
+ ///
+ /// [Unicode Standard]: https://www.unicode.org/versions/latest/
+ ///
+ /// # Examples
+ ///
+ /// As an iterator:
+ ///
+ /// ```
+ /// for c in 'ß'.to_uppercase() {
+ /// print!("{c}");
+ /// }
+ /// println!();
+ /// ```
+ ///
+ /// Using `println!` directly:
+ ///
+ /// ```
+ /// println!("{}", 'ß'.to_uppercase());
+ /// ```
+ ///
+ /// Both are equivalent to:
+ ///
+ /// ```
+ /// println!("SS");
+ /// ```
+ ///
+ /// Using [`to_string`](../std/string/trait.ToString.html#tymethod.to_string):
+ ///
+ /// ```
+ /// assert_eq!('c'.to_uppercase().to_string(), "C");
+ ///
+ /// // Sometimes the result is more than one character:
+ /// assert_eq!('ß'.to_uppercase().to_string(), "SS");
+ ///
+ /// // Characters that do not have both uppercase and lowercase
+ /// // convert into themselves.
+ /// assert_eq!('山'.to_uppercase().to_string(), "山");
+ /// ```
+ ///
+ /// # Note on locale
+ ///
+ /// In Turkish, the equivalent of 'i' in Latin has five forms instead of two:
+ ///
+ /// * 'Dotless': I / ı, sometimes written ï
+ /// * 'Dotted': İ / i
+ ///
+ /// Note that the lowercase dotted 'i' is the same as the Latin. Therefore:
+ ///
+ /// ```
+ /// let upper_i = 'i'.to_uppercase().to_string();
+ /// ```
+ ///
+ /// The value of `upper_i` here relies on the language of the text: if we're
+ /// in `en-US`, it should be `"I"`, but if we're in `tr_TR`, it should
+ /// be `"İ"`. `to_uppercase()` does not take this into account, and so:
+ ///
+ /// ```
+ /// let upper_i = 'i'.to_uppercase().to_string();
+ ///
+ /// assert_eq!(upper_i, "I");
+ /// ```
+ ///
+ /// holds across languages.
+ #[must_use = "this returns the uppercase character as a new iterator, \
+ without modifying the original"]
+ #[stable(feature = "rust1", since = "1.0.0")]
+ #[inline]
+ pub fn to_uppercase(self) -> ToUppercase {
+ ToUppercase(CaseMappingIter::new(conversions::to_upper(self)))
+ }
+
+ /// Checks if the value is within the ASCII range.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let ascii = 'a';
+ /// let non_ascii = '❤';
+ ///
+ /// assert!(ascii.is_ascii());
+ /// assert!(!non_ascii.is_ascii());
+ /// ```
+ #[must_use]
+ #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
+ #[rustc_const_stable(feature = "const_char_is_ascii", since = "1.32.0")]
+ #[inline]
+ pub const fn is_ascii(&self) -> bool {
+ *self as u32 <= 0x7F
+ }
+
+ /// 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
+ /// [`to_uppercase()`].
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let ascii = 'a';
+ /// let non_ascii = '❤';
+ ///
+ /// assert_eq!('A', ascii.to_ascii_uppercase());
+ /// assert_eq!('❤', non_ascii.to_ascii_uppercase());
+ /// ```
+ ///
+ /// [`make_ascii_uppercase()`]: #method.make_ascii_uppercase
+ /// [`to_uppercase()`]: #method.to_uppercase
+ #[must_use = "to uppercase the value in-place, use `make_ascii_uppercase()`"]
+ #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
+ #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
+ #[inline]
+ pub const fn to_ascii_uppercase(&self) -> char {
+ if self.is_ascii_lowercase() {
+ (*self as u8).ascii_change_case_unchecked() as char
+ } else {
+ *self
+ }
+ }
+
+ /// 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
+ /// [`to_lowercase()`].
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let ascii = 'A';
+ /// let non_ascii = '❤';
+ ///
+ /// assert_eq!('a', ascii.to_ascii_lowercase());
+ /// assert_eq!('❤', non_ascii.to_ascii_lowercase());
+ /// ```
+ ///
+ /// [`make_ascii_lowercase()`]: #method.make_ascii_lowercase
+ /// [`to_lowercase()`]: #method.to_lowercase
+ #[must_use = "to lowercase the value in-place, use `make_ascii_lowercase()`"]
+ #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
+ #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
+ #[inline]
+ pub const fn to_ascii_lowercase(&self) -> char {
+ if self.is_ascii_uppercase() {
+ (*self as u8).ascii_change_case_unchecked() as char
+ } else {
+ *self
+ }
+ }
+
+ /// Checks that two values are an ASCII case-insensitive match.
+ ///
+ /// Equivalent to <code>[to_ascii_lowercase]\(a) == [to_ascii_lowercase]\(b)</code>.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let upper_a = 'A';
+ /// let lower_a = 'a';
+ /// let lower_z = 'z';
+ ///
+ /// assert!(upper_a.eq_ignore_ascii_case(&lower_a));
+ /// assert!(upper_a.eq_ignore_ascii_case(&upper_a));
+ /// assert!(!upper_a.eq_ignore_ascii_case(&lower_z));
+ /// ```
+ ///
+ /// [to_ascii_lowercase]: #method.to_ascii_lowercase
+ #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
+ #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
+ #[inline]
+ pub const fn eq_ignore_ascii_case(&self, other: &char) -> bool {
+ self.to_ascii_lowercase() == other.to_ascii_lowercase()
+ }
+
+ /// 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()`].
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let mut ascii = 'a';
+ ///
+ /// ascii.make_ascii_uppercase();
+ ///
+ /// assert_eq!('A', ascii);
+ /// ```
+ ///
+ /// [`to_ascii_uppercase()`]: #method.to_ascii_uppercase
+ #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
+ #[inline]
+ pub fn make_ascii_uppercase(&mut self) {
+ *self = self.to_ascii_uppercase();
+ }
+
+ /// 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()`].
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let mut ascii = 'A';
+ ///
+ /// ascii.make_ascii_lowercase();
+ ///
+ /// assert_eq!('a', ascii);
+ /// ```
+ ///
+ /// [`to_ascii_lowercase()`]: #method.to_ascii_lowercase
+ #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
+ #[inline]
+ pub fn make_ascii_lowercase(&mut self) {
+ *self = self.to_ascii_lowercase();
+ }
+
+ /// Checks if the value is an ASCII alphabetic character:
+ ///
+ /// - U+0041 'A' ..= U+005A 'Z', or
+ /// - U+0061 'a' ..= U+007A 'z'.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let uppercase_a = 'A';
+ /// let uppercase_g = 'G';
+ /// let a = 'a';
+ /// let g = 'g';
+ /// let zero = '0';
+ /// let percent = '%';
+ /// let space = ' ';
+ /// let lf = '\n';
+ /// let esc = '\x1b';
+ ///
+ /// assert!(uppercase_a.is_ascii_alphabetic());
+ /// assert!(uppercase_g.is_ascii_alphabetic());
+ /// assert!(a.is_ascii_alphabetic());
+ /// assert!(g.is_ascii_alphabetic());
+ /// assert!(!zero.is_ascii_alphabetic());
+ /// assert!(!percent.is_ascii_alphabetic());
+ /// assert!(!space.is_ascii_alphabetic());
+ /// assert!(!lf.is_ascii_alphabetic());
+ /// assert!(!esc.is_ascii_alphabetic());
+ /// ```
+ #[must_use]
+ #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
+ #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
+ #[inline]
+ pub const fn is_ascii_alphabetic(&self) -> bool {
+ matches!(*self, 'A'..='Z' | 'a'..='z')
+ }
+
+ /// Checks if the value is an ASCII uppercase character:
+ /// U+0041 'A' ..= U+005A 'Z'.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let uppercase_a = 'A';
+ /// let uppercase_g = 'G';
+ /// let a = 'a';
+ /// let g = 'g';
+ /// let zero = '0';
+ /// let percent = '%';
+ /// let space = ' ';
+ /// let lf = '\n';
+ /// let esc = '\x1b';
+ ///
+ /// assert!(uppercase_a.is_ascii_uppercase());
+ /// assert!(uppercase_g.is_ascii_uppercase());
+ /// assert!(!a.is_ascii_uppercase());
+ /// assert!(!g.is_ascii_uppercase());
+ /// assert!(!zero.is_ascii_uppercase());
+ /// assert!(!percent.is_ascii_uppercase());
+ /// assert!(!space.is_ascii_uppercase());
+ /// assert!(!lf.is_ascii_uppercase());
+ /// assert!(!esc.is_ascii_uppercase());
+ /// ```
+ #[must_use]
+ #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
+ #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
+ #[inline]
+ pub const fn is_ascii_uppercase(&self) -> bool {
+ matches!(*self, 'A'..='Z')
+ }
+
+ /// Checks if the value is an ASCII lowercase character:
+ /// U+0061 'a' ..= U+007A 'z'.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let uppercase_a = 'A';
+ /// let uppercase_g = 'G';
+ /// let a = 'a';
+ /// let g = 'g';
+ /// let zero = '0';
+ /// let percent = '%';
+ /// let space = ' ';
+ /// let lf = '\n';
+ /// let esc = '\x1b';
+ ///
+ /// assert!(!uppercase_a.is_ascii_lowercase());
+ /// assert!(!uppercase_g.is_ascii_lowercase());
+ /// assert!(a.is_ascii_lowercase());
+ /// assert!(g.is_ascii_lowercase());
+ /// assert!(!zero.is_ascii_lowercase());
+ /// assert!(!percent.is_ascii_lowercase());
+ /// assert!(!space.is_ascii_lowercase());
+ /// assert!(!lf.is_ascii_lowercase());
+ /// assert!(!esc.is_ascii_lowercase());
+ /// ```
+ #[must_use]
+ #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
+ #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
+ #[inline]
+ pub const fn is_ascii_lowercase(&self) -> bool {
+ matches!(*self, 'a'..='z')
+ }
+
+ /// Checks if the value is an ASCII alphanumeric character:
+ ///
+ /// - U+0041 'A' ..= U+005A 'Z', or
+ /// - U+0061 'a' ..= U+007A 'z', or
+ /// - U+0030 '0' ..= U+0039 '9'.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let uppercase_a = 'A';
+ /// let uppercase_g = 'G';
+ /// let a = 'a';
+ /// let g = 'g';
+ /// let zero = '0';
+ /// let percent = '%';
+ /// let space = ' ';
+ /// let lf = '\n';
+ /// let esc = '\x1b';
+ ///
+ /// assert!(uppercase_a.is_ascii_alphanumeric());
+ /// assert!(uppercase_g.is_ascii_alphanumeric());
+ /// assert!(a.is_ascii_alphanumeric());
+ /// assert!(g.is_ascii_alphanumeric());
+ /// assert!(zero.is_ascii_alphanumeric());
+ /// assert!(!percent.is_ascii_alphanumeric());
+ /// assert!(!space.is_ascii_alphanumeric());
+ /// assert!(!lf.is_ascii_alphanumeric());
+ /// assert!(!esc.is_ascii_alphanumeric());
+ /// ```
+ #[must_use]
+ #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
+ #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
+ #[inline]
+ pub const fn is_ascii_alphanumeric(&self) -> bool {
+ matches!(*self, '0'..='9' | 'A'..='Z' | 'a'..='z')
+ }
+
+ /// Checks if the value is an ASCII decimal digit:
+ /// U+0030 '0' ..= U+0039 '9'.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let uppercase_a = 'A';
+ /// let uppercase_g = 'G';
+ /// let a = 'a';
+ /// let g = 'g';
+ /// let zero = '0';
+ /// let percent = '%';
+ /// let space = ' ';
+ /// let lf = '\n';
+ /// let esc = '\x1b';
+ ///
+ /// assert!(!uppercase_a.is_ascii_digit());
+ /// assert!(!uppercase_g.is_ascii_digit());
+ /// assert!(!a.is_ascii_digit());
+ /// assert!(!g.is_ascii_digit());
+ /// assert!(zero.is_ascii_digit());
+ /// assert!(!percent.is_ascii_digit());
+ /// assert!(!space.is_ascii_digit());
+ /// assert!(!lf.is_ascii_digit());
+ /// assert!(!esc.is_ascii_digit());
+ /// ```
+ #[must_use]
+ #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
+ #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
+ #[inline]
+ pub const fn is_ascii_digit(&self) -> bool {
+ matches!(*self, '0'..='9')
+ }
+
+ /// Checks if the value is an ASCII hexadecimal digit:
+ ///
+ /// - U+0030 '0' ..= U+0039 '9', or
+ /// - U+0041 'A' ..= U+0046 'F', or
+ /// - U+0061 'a' ..= U+0066 'f'.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let uppercase_a = 'A';
+ /// let uppercase_g = 'G';
+ /// let a = 'a';
+ /// let g = 'g';
+ /// let zero = '0';
+ /// let percent = '%';
+ /// let space = ' ';
+ /// let lf = '\n';
+ /// let esc = '\x1b';
+ ///
+ /// assert!(uppercase_a.is_ascii_hexdigit());
+ /// assert!(!uppercase_g.is_ascii_hexdigit());
+ /// assert!(a.is_ascii_hexdigit());
+ /// assert!(!g.is_ascii_hexdigit());
+ /// assert!(zero.is_ascii_hexdigit());
+ /// assert!(!percent.is_ascii_hexdigit());
+ /// assert!(!space.is_ascii_hexdigit());
+ /// assert!(!lf.is_ascii_hexdigit());
+ /// assert!(!esc.is_ascii_hexdigit());
+ /// ```
+ #[must_use]
+ #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
+ #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
+ #[inline]
+ pub const fn is_ascii_hexdigit(&self) -> bool {
+ matches!(*self, '0'..='9' | 'A'..='F' | 'a'..='f')
+ }
+
+ /// Checks if the value is an ASCII punctuation character:
+ ///
+ /// - U+0021 ..= U+002F `! " # $ % & ' ( ) * + , - . /`, or
+ /// - U+003A ..= U+0040 `: ; < = > ? @`, or
+ /// - U+005B ..= U+0060 ``[ \ ] ^ _ ` ``, or
+ /// - U+007B ..= U+007E `{ | } ~`
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let uppercase_a = 'A';
+ /// let uppercase_g = 'G';
+ /// let a = 'a';
+ /// let g = 'g';
+ /// let zero = '0';
+ /// let percent = '%';
+ /// let space = ' ';
+ /// let lf = '\n';
+ /// let esc = '\x1b';
+ ///
+ /// assert!(!uppercase_a.is_ascii_punctuation());
+ /// assert!(!uppercase_g.is_ascii_punctuation());
+ /// assert!(!a.is_ascii_punctuation());
+ /// assert!(!g.is_ascii_punctuation());
+ /// assert!(!zero.is_ascii_punctuation());
+ /// assert!(percent.is_ascii_punctuation());
+ /// assert!(!space.is_ascii_punctuation());
+ /// assert!(!lf.is_ascii_punctuation());
+ /// assert!(!esc.is_ascii_punctuation());
+ /// ```
+ #[must_use]
+ #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
+ #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
+ #[inline]
+ pub const fn is_ascii_punctuation(&self) -> bool {
+ matches!(*self, '!'..='/' | ':'..='@' | '['..='`' | '{'..='~')
+ }
+
+ /// Checks if the value is an ASCII graphic character:
+ /// U+0021 '!' ..= U+007E '~'.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let uppercase_a = 'A';
+ /// let uppercase_g = 'G';
+ /// let a = 'a';
+ /// let g = 'g';
+ /// let zero = '0';
+ /// let percent = '%';
+ /// let space = ' ';
+ /// let lf = '\n';
+ /// let esc = '\x1b';
+ ///
+ /// assert!(uppercase_a.is_ascii_graphic());
+ /// assert!(uppercase_g.is_ascii_graphic());
+ /// assert!(a.is_ascii_graphic());
+ /// assert!(g.is_ascii_graphic());
+ /// assert!(zero.is_ascii_graphic());
+ /// assert!(percent.is_ascii_graphic());
+ /// assert!(!space.is_ascii_graphic());
+ /// assert!(!lf.is_ascii_graphic());
+ /// assert!(!esc.is_ascii_graphic());
+ /// ```
+ #[must_use]
+ #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
+ #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
+ #[inline]
+ pub const fn is_ascii_graphic(&self) -> bool {
+ matches!(*self, '!'..='~')
+ }
+
+ /// Checks if the value is an ASCII whitespace character:
+ /// U+0020 SPACE, U+0009 HORIZONTAL TAB, U+000A LINE FEED,
+ /// U+000C FORM FEED, or U+000D CARRIAGE RETURN.
+ ///
+ /// Rust uses the WhatWG Infra Standard's [definition of ASCII
+ /// whitespace][infra-aw]. There are several other definitions in
+ /// wide use. For instance, [the POSIX locale][pct] includes
+ /// U+000B VERTICAL TAB as well as all the above characters,
+ /// but—from the very same specification—[the default rule for
+ /// "field splitting" in the Bourne shell][bfs] considers *only*
+ /// SPACE, HORIZONTAL TAB, and LINE FEED as whitespace.
+ ///
+ /// If you are writing a program that will process an existing
+ /// file format, check what that format's definition of whitespace is
+ /// before using this function.
+ ///
+ /// [infra-aw]: https://infra.spec.whatwg.org/#ascii-whitespace
+ /// [pct]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html#tag_07_03_01
+ /// [bfs]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_05
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let uppercase_a = 'A';
+ /// let uppercase_g = 'G';
+ /// let a = 'a';
+ /// let g = 'g';
+ /// let zero = '0';
+ /// let percent = '%';
+ /// let space = ' ';
+ /// let lf = '\n';
+ /// let esc = '\x1b';
+ ///
+ /// assert!(!uppercase_a.is_ascii_whitespace());
+ /// assert!(!uppercase_g.is_ascii_whitespace());
+ /// assert!(!a.is_ascii_whitespace());
+ /// assert!(!g.is_ascii_whitespace());
+ /// assert!(!zero.is_ascii_whitespace());
+ /// assert!(!percent.is_ascii_whitespace());
+ /// assert!(space.is_ascii_whitespace());
+ /// assert!(lf.is_ascii_whitespace());
+ /// assert!(!esc.is_ascii_whitespace());
+ /// ```
+ #[must_use]
+ #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
+ #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
+ #[inline]
+ pub const fn is_ascii_whitespace(&self) -> bool {
+ matches!(*self, '\t' | '\n' | '\x0C' | '\r' | ' ')
+ }
+
+ /// Checks if the value is an ASCII control character:
+ /// U+0000 NUL ..= U+001F UNIT SEPARATOR, or U+007F DELETE.
+ /// Note that most ASCII whitespace characters are control
+ /// characters, but SPACE is not.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let uppercase_a = 'A';
+ /// let uppercase_g = 'G';
+ /// let a = 'a';
+ /// let g = 'g';
+ /// let zero = '0';
+ /// let percent = '%';
+ /// let space = ' ';
+ /// let lf = '\n';
+ /// let esc = '\x1b';
+ ///
+ /// assert!(!uppercase_a.is_ascii_control());
+ /// assert!(!uppercase_g.is_ascii_control());
+ /// assert!(!a.is_ascii_control());
+ /// assert!(!g.is_ascii_control());
+ /// assert!(!zero.is_ascii_control());
+ /// assert!(!percent.is_ascii_control());
+ /// assert!(!space.is_ascii_control());
+ /// assert!(lf.is_ascii_control());
+ /// assert!(esc.is_ascii_control());
+ /// ```
+ #[must_use]
+ #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
+ #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
+ #[inline]
+ pub const fn is_ascii_control(&self) -> bool {
+ matches!(*self, '\0'..='\x1F' | '\x7F')
+ }
+}
+
+pub(crate) struct EscapeDebugExtArgs {
+ /// Escape Extended Grapheme codepoints?
+ pub(crate) escape_grapheme_extended: bool,
+
+ /// Escape single quotes?
+ pub(crate) escape_single_quote: bool,
+
+ /// Escape double quotes?
+ pub(crate) escape_double_quote: bool,
+}
+
+impl EscapeDebugExtArgs {
+ pub(crate) const ESCAPE_ALL: Self = Self {
+ escape_grapheme_extended: true,
+ escape_single_quote: true,
+ escape_double_quote: true,
+ };
+}
+
+#[inline]
+const fn len_utf8(code: u32) -> usize {
+ if code < MAX_ONE_B {
+ 1
+ } else if code < MAX_TWO_B {
+ 2
+ } else if code < MAX_THREE_B {
+ 3
+ } else {
+ 4
+ }
+}
+
+/// Encodes a raw u32 value as UTF-8 into the provided byte buffer,
+/// and then returns the subslice of the buffer that contains the encoded character.
+///
+/// Unlike `char::encode_utf8`, this method also handles codepoints in the surrogate range.
+/// (Creating a `char` in the surrogate range is UB.)
+/// The result is valid [generalized UTF-8] but not valid UTF-8.
+///
+/// [generalized UTF-8]: https://simonsapin.github.io/wtf-8/#generalized-utf8
+///
+/// # Panics
+///
+/// Panics if the buffer is not large enough.
+/// A buffer of length four is large enough to encode any `char`.
+#[unstable(feature = "char_internals", reason = "exposed only for libstd", issue = "none")]
+#[doc(hidden)]
+#[inline]
+pub fn encode_utf8_raw(code: u32, dst: &mut [u8]) -> &mut [u8] {
+ let len = len_utf8(code);
+ match (len, &mut dst[..]) {
+ (1, [a, ..]) => {
+ *a = code as u8;
+ }
+ (2, [a, b, ..]) => {
+ *a = (code >> 6 & 0x1F) as u8 | TAG_TWO_B;
+ *b = (code & 0x3F) as u8 | TAG_CONT;
+ }
+ (3, [a, b, c, ..]) => {
+ *a = (code >> 12 & 0x0F) as u8 | TAG_THREE_B;
+ *b = (code >> 6 & 0x3F) as u8 | TAG_CONT;
+ *c = (code & 0x3F) as u8 | TAG_CONT;
+ }
+ (4, [a, b, c, d, ..]) => {
+ *a = (code >> 18 & 0x07) as u8 | TAG_FOUR_B;
+ *b = (code >> 12 & 0x3F) as u8 | TAG_CONT;
+ *c = (code >> 6 & 0x3F) as u8 | TAG_CONT;
+ *d = (code & 0x3F) as u8 | TAG_CONT;
+ }
+ _ => panic!(
+ "encode_utf8: need {} bytes to encode U+{:X}, but the buffer has {}",
+ len,
+ code,
+ dst.len(),
+ ),
+ };
+ &mut dst[..len]
+}
+
+/// Encodes a raw u32 value as UTF-16 into the provided `u16` buffer,
+/// and then returns the subslice of the buffer that contains the encoded character.
+///
+/// Unlike `char::encode_utf16`, this method also handles codepoints in the surrogate range.
+/// (Creating a `char` in the surrogate range is UB.)
+///
+/// # Panics
+///
+/// Panics if the buffer is not large enough.
+/// A buffer of length 2 is large enough to encode any `char`.
+#[unstable(feature = "char_internals", reason = "exposed only for libstd", issue = "none")]
+#[doc(hidden)]
+#[inline]
+pub fn encode_utf16_raw(mut code: u32, dst: &mut [u16]) -> &mut [u16] {
+ // SAFETY: each arm checks whether there are enough bits to write into
+ unsafe {
+ if (code & 0xFFFF) == code && !dst.is_empty() {
+ // The BMP falls through
+ *dst.get_unchecked_mut(0) = code as u16;
+ slice::from_raw_parts_mut(dst.as_mut_ptr(), 1)
+ } else if dst.len() >= 2 {
+ // Supplementary planes break into surrogates.
+ code -= 0x1_0000;
+ *dst.get_unchecked_mut(0) = 0xD800 | ((code >> 10) as u16);
+ *dst.get_unchecked_mut(1) = 0xDC00 | ((code as u16) & 0x3FF);
+ slice::from_raw_parts_mut(dst.as_mut_ptr(), 2)
+ } else {
+ panic!(
+ "encode_utf16: need {} units to encode U+{:X}, but the buffer has {}",
+ from_u32_unchecked(code).len_utf16(),
+ code,
+ dst.len(),
+ )
+ }
+ }
+}
diff --git a/library/core/src/char/mod.rs b/library/core/src/char/mod.rs
new file mode 100644
index 000000000..0df23e7bb
--- /dev/null
+++ b/library/core/src/char/mod.rs
@@ -0,0 +1,584 @@
+//! A character type.
+//!
+//! The `char` type represents a single character. More specifically, since
+//! 'character' isn't a well-defined concept in Unicode, `char` is a '[Unicode
+//! scalar value]', which is similar to, but not the same as, a '[Unicode code
+//! point]'.
+//!
+//! [Unicode scalar value]: https://www.unicode.org/glossary/#unicode_scalar_value
+//! [Unicode code point]: https://www.unicode.org/glossary/#code_point
+//!
+//! This module exists for technical reasons, the primary documentation for
+//! `char` is directly on [the `char` primitive type][char] itself.
+//!
+//! This module is the home of the iterator implementations for the iterators
+//! implemented on `char`, as well as some useful constants and conversion
+//! functions that convert various types to `char`.
+
+#![allow(non_snake_case)]
+#![stable(feature = "core_char", since = "1.2.0")]
+
+mod convert;
+mod decode;
+mod methods;
+
+// stable re-exports
+#[stable(feature = "try_from", since = "1.34.0")]
+pub use self::convert::CharTryFromError;
+#[stable(feature = "char_from_str", since = "1.20.0")]
+pub use self::convert::ParseCharError;
+#[stable(feature = "decode_utf16", since = "1.9.0")]
+pub use self::decode::{DecodeUtf16, DecodeUtf16Error};
+
+// perma-unstable re-exports
+#[unstable(feature = "char_internals", reason = "exposed only for libstd", issue = "none")]
+pub use self::methods::encode_utf16_raw;
+#[unstable(feature = "char_internals", reason = "exposed only for libstd", issue = "none")]
+pub use self::methods::encode_utf8_raw;
+
+use crate::fmt::{self, Write};
+use crate::iter::FusedIterator;
+
+pub(crate) use self::methods::EscapeDebugExtArgs;
+
+// UTF-8 ranges and tags for encoding characters
+const TAG_CONT: u8 = 0b1000_0000;
+const TAG_TWO_B: u8 = 0b1100_0000;
+const TAG_THREE_B: u8 = 0b1110_0000;
+const TAG_FOUR_B: u8 = 0b1111_0000;
+const MAX_ONE_B: u32 = 0x80;
+const MAX_TWO_B: u32 = 0x800;
+const MAX_THREE_B: u32 = 0x10000;
+
+/*
+ Lu Uppercase_Letter an uppercase letter
+ Ll Lowercase_Letter a lowercase letter
+ Lt Titlecase_Letter a digraphic character, with first part uppercase
+ Lm Modifier_Letter a modifier letter
+ Lo Other_Letter other letters, including syllables and ideographs
+ Mn Nonspacing_Mark a nonspacing combining mark (zero advance width)
+ Mc Spacing_Mark a spacing combining mark (positive advance width)
+ Me Enclosing_Mark an enclosing combining mark
+ Nd Decimal_Number a decimal digit
+ Nl Letter_Number a letterlike numeric character
+ No Other_Number a numeric character of other type
+ Pc Connector_Punctuation a connecting punctuation mark, like a tie
+ Pd Dash_Punctuation a dash or hyphen punctuation mark
+ Ps Open_Punctuation an opening punctuation mark (of a pair)
+ Pe Close_Punctuation a closing punctuation mark (of a pair)
+ Pi Initial_Punctuation an initial quotation mark
+ Pf Final_Punctuation a final quotation mark
+ Po Other_Punctuation a punctuation mark of other type
+ Sm Math_Symbol a symbol of primarily mathematical use
+ Sc Currency_Symbol a currency sign
+ Sk Modifier_Symbol a non-letterlike modifier symbol
+ So Other_Symbol a symbol of other type
+ Zs Space_Separator a space character (of various non-zero widths)
+ Zl Line_Separator U+2028 LINE SEPARATOR only
+ Zp Paragraph_Separator U+2029 PARAGRAPH SEPARATOR only
+ Cc Control a C0 or C1 control code
+ Cf Format a format control character
+ Cs Surrogate a surrogate code point
+ Co Private_Use a private-use character
+ Cn Unassigned a reserved unassigned code point or a noncharacter
+*/
+
+/// The highest valid code point a `char` can have, `'\u{10FFFF}'`. Use [`char::MAX`] instead.
+#[stable(feature = "rust1", since = "1.0.0")]
+pub const MAX: char = char::MAX;
+
+/// `U+FFFD REPLACEMENT CHARACTER` (�) is used in Unicode to represent a
+/// decoding error. Use [`char::REPLACEMENT_CHARACTER`] instead.
+#[stable(feature = "decode_utf16", since = "1.9.0")]
+pub const REPLACEMENT_CHARACTER: char = char::REPLACEMENT_CHARACTER;
+
+/// The version of [Unicode](https://www.unicode.org/) that the Unicode parts of
+/// `char` and `str` methods are based on. Use [`char::UNICODE_VERSION`] instead.
+#[stable(feature = "unicode_version", since = "1.45.0")]
+pub const UNICODE_VERSION: (u8, u8, u8) = char::UNICODE_VERSION;
+
+/// Creates an iterator over the UTF-16 encoded code points in `iter`, returning
+/// unpaired surrogates as `Err`s. Use [`char::decode_utf16`] instead.
+#[stable(feature = "decode_utf16", since = "1.9.0")]
+#[inline]
+pub fn decode_utf16<I: IntoIterator<Item = u16>>(iter: I) -> DecodeUtf16<I::IntoIter> {
+ self::decode::decode_utf16(iter)
+}
+
+/// Converts a `u32` to a `char`. Use [`char::from_u32`] instead.
+#[stable(feature = "rust1", since = "1.0.0")]
+#[rustc_const_unstable(feature = "const_char_convert", issue = "89259")]
+#[must_use]
+#[inline]
+pub const fn from_u32(i: u32) -> Option<char> {
+ self::convert::from_u32(i)
+}
+
+/// Converts a `u32` to a `char`, ignoring validity. Use [`char::from_u32_unchecked`].
+/// instead.
+#[stable(feature = "char_from_unchecked", since = "1.5.0")]
+#[rustc_const_unstable(feature = "const_char_convert", issue = "89259")]
+#[must_use]
+#[inline]
+pub const unsafe fn from_u32_unchecked(i: u32) -> char {
+ // SAFETY: the safety contract must be upheld by the caller.
+ unsafe { self::convert::from_u32_unchecked(i) }
+}
+
+/// Converts a digit in the given radix to a `char`. Use [`char::from_digit`] instead.
+#[stable(feature = "rust1", since = "1.0.0")]
+#[rustc_const_unstable(feature = "const_char_convert", issue = "89259")]
+#[must_use]
+#[inline]
+pub const fn from_digit(num: u32, radix: u32) -> Option<char> {
+ self::convert::from_digit(num, radix)
+}
+
+/// Returns an iterator that yields the hexadecimal Unicode escape of a
+/// character, as `char`s.
+///
+/// This `struct` is created by the [`escape_unicode`] method on [`char`]. See
+/// its documentation for more.
+///
+/// [`escape_unicode`]: char::escape_unicode
+#[derive(Clone, Debug)]
+#[stable(feature = "rust1", since = "1.0.0")]
+pub struct EscapeUnicode {
+ c: char,
+ state: EscapeUnicodeState,
+
+ // The index of the next hex digit to be printed (0 if none),
+ // i.e., the number of remaining hex digits to be printed;
+ // increasing from the least significant digit: 0x543210
+ hex_digit_idx: usize,
+}
+
+// The enum values are ordered so that their representation is the
+// same as the remaining length (besides the hexadecimal digits). This
+// likely makes `len()` a single load from memory) and inline-worth.
+#[derive(Clone, Debug)]
+enum EscapeUnicodeState {
+ Done,
+ RightBrace,
+ Value,
+ LeftBrace,
+ Type,
+ Backslash,
+}
+
+#[stable(feature = "rust1", since = "1.0.0")]
+impl Iterator for EscapeUnicode {
+ type Item = char;
+
+ fn next(&mut self) -> Option<char> {
+ match self.state {
+ EscapeUnicodeState::Backslash => {
+ self.state = EscapeUnicodeState::Type;
+ Some('\\')
+ }
+ EscapeUnicodeState::Type => {
+ self.state = EscapeUnicodeState::LeftBrace;
+ Some('u')
+ }
+ EscapeUnicodeState::LeftBrace => {
+ self.state = EscapeUnicodeState::Value;
+ Some('{')
+ }
+ EscapeUnicodeState::Value => {
+ let hex_digit = ((self.c as u32) >> (self.hex_digit_idx * 4)) & 0xf;
+ let c = from_digit(hex_digit, 16).unwrap();
+ if self.hex_digit_idx == 0 {
+ self.state = EscapeUnicodeState::RightBrace;
+ } else {
+ self.hex_digit_idx -= 1;
+ }
+ Some(c)
+ }
+ EscapeUnicodeState::RightBrace => {
+ self.state = EscapeUnicodeState::Done;
+ Some('}')
+ }
+ EscapeUnicodeState::Done => None,
+ }
+ }
+
+ #[inline]
+ fn size_hint(&self) -> (usize, Option<usize>) {
+ let n = self.len();
+ (n, Some(n))
+ }
+
+ #[inline]
+ fn count(self) -> usize {
+ self.len()
+ }
+
+ fn last(self) -> Option<char> {
+ match self.state {
+ EscapeUnicodeState::Done => None,
+
+ EscapeUnicodeState::RightBrace
+ | EscapeUnicodeState::Value
+ | EscapeUnicodeState::LeftBrace
+ | EscapeUnicodeState::Type
+ | EscapeUnicodeState::Backslash => Some('}'),
+ }
+ }
+}
+
+#[stable(feature = "exact_size_escape", since = "1.11.0")]
+impl ExactSizeIterator for EscapeUnicode {
+ #[inline]
+ fn len(&self) -> usize {
+ // The match is a single memory access with no branching
+ self.hex_digit_idx
+ + match self.state {
+ EscapeUnicodeState::Done => 0,
+ EscapeUnicodeState::RightBrace => 1,
+ EscapeUnicodeState::Value => 2,
+ EscapeUnicodeState::LeftBrace => 3,
+ EscapeUnicodeState::Type => 4,
+ EscapeUnicodeState::Backslash => 5,
+ }
+ }
+}
+
+#[stable(feature = "fused", since = "1.26.0")]
+impl FusedIterator for EscapeUnicode {}
+
+#[stable(feature = "char_struct_display", since = "1.16.0")]
+impl fmt::Display for EscapeUnicode {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ for c in self.clone() {
+ f.write_char(c)?;
+ }
+ Ok(())
+ }
+}
+
+/// An iterator that yields the literal escape code of a `char`.
+///
+/// This `struct` is created by the [`escape_default`] method on [`char`]. See
+/// its documentation for more.
+///
+/// [`escape_default`]: char::escape_default
+#[derive(Clone, Debug)]
+#[stable(feature = "rust1", since = "1.0.0")]
+pub struct EscapeDefault {
+ state: EscapeDefaultState,
+}
+
+#[derive(Clone, Debug)]
+enum EscapeDefaultState {
+ Done,
+ Char(char),
+ Backslash(char),
+ Unicode(EscapeUnicode),
+}
+
+#[stable(feature = "rust1", since = "1.0.0")]
+impl Iterator for EscapeDefault {
+ type Item = char;
+
+ fn next(&mut self) -> Option<char> {
+ match self.state {
+ EscapeDefaultState::Backslash(c) => {
+ self.state = EscapeDefaultState::Char(c);
+ Some('\\')
+ }
+ EscapeDefaultState::Char(c) => {
+ self.state = EscapeDefaultState::Done;
+ Some(c)
+ }
+ EscapeDefaultState::Done => None,
+ EscapeDefaultState::Unicode(ref mut iter) => iter.next(),
+ }
+ }
+
+ #[inline]
+ fn size_hint(&self) -> (usize, Option<usize>) {
+ let n = self.len();
+ (n, Some(n))
+ }
+
+ #[inline]
+ fn count(self) -> usize {
+ self.len()
+ }
+
+ fn nth(&mut self, n: usize) -> Option<char> {
+ match self.state {
+ EscapeDefaultState::Backslash(c) if n == 0 => {
+ self.state = EscapeDefaultState::Char(c);
+ Some('\\')
+ }
+ EscapeDefaultState::Backslash(c) if n == 1 => {
+ self.state = EscapeDefaultState::Done;
+ Some(c)
+ }
+ EscapeDefaultState::Backslash(_) => {
+ self.state = EscapeDefaultState::Done;
+ None
+ }
+ EscapeDefaultState::Char(c) => {
+ self.state = EscapeDefaultState::Done;
+
+ if n == 0 { Some(c) } else { None }
+ }
+ EscapeDefaultState::Done => None,
+ EscapeDefaultState::Unicode(ref mut i) => i.nth(n),
+ }
+ }
+
+ fn last(self) -> Option<char> {
+ match self.state {
+ EscapeDefaultState::Unicode(iter) => iter.last(),
+ EscapeDefaultState::Done => None,
+ EscapeDefaultState::Backslash(c) | EscapeDefaultState::Char(c) => Some(c),
+ }
+ }
+}
+
+#[stable(feature = "exact_size_escape", since = "1.11.0")]
+impl ExactSizeIterator for EscapeDefault {
+ fn len(&self) -> usize {
+ match self.state {
+ EscapeDefaultState::Done => 0,
+ EscapeDefaultState::Char(_) => 1,
+ EscapeDefaultState::Backslash(_) => 2,
+ EscapeDefaultState::Unicode(ref iter) => iter.len(),
+ }
+ }
+}
+
+#[stable(feature = "fused", since = "1.26.0")]
+impl FusedIterator for EscapeDefault {}
+
+#[stable(feature = "char_struct_display", since = "1.16.0")]
+impl fmt::Display for EscapeDefault {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ for c in self.clone() {
+ f.write_char(c)?;
+ }
+ Ok(())
+ }
+}
+
+/// An iterator that yields the literal escape code of a `char`.
+///
+/// This `struct` is created by the [`escape_debug`] method on [`char`]. See its
+/// documentation for more.
+///
+/// [`escape_debug`]: char::escape_debug
+#[stable(feature = "char_escape_debug", since = "1.20.0")]
+#[derive(Clone, Debug)]
+pub struct EscapeDebug(EscapeDefault);
+
+#[stable(feature = "char_escape_debug", since = "1.20.0")]
+impl Iterator for EscapeDebug {
+ type Item = char;
+ fn next(&mut self) -> Option<char> {
+ self.0.next()
+ }
+ fn size_hint(&self) -> (usize, Option<usize>) {
+ self.0.size_hint()
+ }
+}
+
+#[stable(feature = "char_escape_debug", since = "1.20.0")]
+impl ExactSizeIterator for EscapeDebug {}
+
+#[stable(feature = "fused", since = "1.26.0")]
+impl FusedIterator for EscapeDebug {}
+
+#[stable(feature = "char_escape_debug", since = "1.20.0")]
+impl fmt::Display for EscapeDebug {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ fmt::Display::fmt(&self.0, f)
+ }
+}
+
+/// Returns an iterator that yields the lowercase equivalent of a `char`.
+///
+/// This `struct` is created by the [`to_lowercase`] method on [`char`]. See
+/// its documentation for more.
+///
+/// [`to_lowercase`]: char::to_lowercase
+#[stable(feature = "rust1", since = "1.0.0")]
+#[derive(Debug, Clone)]
+pub struct ToLowercase(CaseMappingIter);
+
+#[stable(feature = "rust1", since = "1.0.0")]
+impl Iterator for ToLowercase {
+ type Item = char;
+ fn next(&mut self) -> Option<char> {
+ self.0.next()
+ }
+ fn size_hint(&self) -> (usize, Option<usize>) {
+ self.0.size_hint()
+ }
+}
+
+#[stable(feature = "case_mapping_double_ended", since = "1.59.0")]
+impl DoubleEndedIterator for ToLowercase {
+ fn next_back(&mut self) -> Option<char> {
+ self.0.next_back()
+ }
+}
+
+#[stable(feature = "fused", since = "1.26.0")]
+impl FusedIterator for ToLowercase {}
+
+#[stable(feature = "exact_size_case_mapping_iter", since = "1.35.0")]
+impl ExactSizeIterator for ToLowercase {}
+
+/// Returns an iterator that yields the uppercase equivalent of a `char`.
+///
+/// This `struct` is created by the [`to_uppercase`] method on [`char`]. See
+/// its documentation for more.
+///
+/// [`to_uppercase`]: char::to_uppercase
+#[stable(feature = "rust1", since = "1.0.0")]
+#[derive(Debug, Clone)]
+pub struct ToUppercase(CaseMappingIter);
+
+#[stable(feature = "rust1", since = "1.0.0")]
+impl Iterator for ToUppercase {
+ type Item = char;
+ fn next(&mut self) -> Option<char> {
+ self.0.next()
+ }
+ fn size_hint(&self) -> (usize, Option<usize>) {
+ self.0.size_hint()
+ }
+}
+
+#[stable(feature = "case_mapping_double_ended", since = "1.59.0")]
+impl DoubleEndedIterator for ToUppercase {
+ fn next_back(&mut self) -> Option<char> {
+ self.0.next_back()
+ }
+}
+
+#[stable(feature = "fused", since = "1.26.0")]
+impl FusedIterator for ToUppercase {}
+
+#[stable(feature = "exact_size_case_mapping_iter", since = "1.35.0")]
+impl ExactSizeIterator for ToUppercase {}
+
+#[derive(Debug, Clone)]
+enum CaseMappingIter {
+ Three(char, char, char),
+ Two(char, char),
+ One(char),
+ Zero,
+}
+
+impl CaseMappingIter {
+ fn new(chars: [char; 3]) -> CaseMappingIter {
+ if chars[2] == '\0' {
+ if chars[1] == '\0' {
+ CaseMappingIter::One(chars[0]) // Including if chars[0] == '\0'
+ } else {
+ CaseMappingIter::Two(chars[0], chars[1])
+ }
+ } else {
+ CaseMappingIter::Three(chars[0], chars[1], chars[2])
+ }
+ }
+}
+
+impl Iterator for CaseMappingIter {
+ type Item = char;
+ fn next(&mut self) -> Option<char> {
+ match *self {
+ CaseMappingIter::Three(a, b, c) => {
+ *self = CaseMappingIter::Two(b, c);
+ Some(a)
+ }
+ CaseMappingIter::Two(b, c) => {
+ *self = CaseMappingIter::One(c);
+ Some(b)
+ }
+ CaseMappingIter::One(c) => {
+ *self = CaseMappingIter::Zero;
+ Some(c)
+ }
+ CaseMappingIter::Zero => None,
+ }
+ }
+
+ fn size_hint(&self) -> (usize, Option<usize>) {
+ let size = match self {
+ CaseMappingIter::Three(..) => 3,
+ CaseMappingIter::Two(..) => 2,
+ CaseMappingIter::One(_) => 1,
+ CaseMappingIter::Zero => 0,
+ };
+ (size, Some(size))
+ }
+}
+
+impl DoubleEndedIterator for CaseMappingIter {
+ fn next_back(&mut self) -> Option<char> {
+ match *self {
+ CaseMappingIter::Three(a, b, c) => {
+ *self = CaseMappingIter::Two(a, b);
+ Some(c)
+ }
+ CaseMappingIter::Two(b, c) => {
+ *self = CaseMappingIter::One(b);
+ Some(c)
+ }
+ CaseMappingIter::One(c) => {
+ *self = CaseMappingIter::Zero;
+ Some(c)
+ }
+ CaseMappingIter::Zero => None,
+ }
+ }
+}
+
+impl fmt::Display for CaseMappingIter {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ match *self {
+ CaseMappingIter::Three(a, b, c) => {
+ f.write_char(a)?;
+ f.write_char(b)?;
+ f.write_char(c)
+ }
+ CaseMappingIter::Two(b, c) => {
+ f.write_char(b)?;
+ f.write_char(c)
+ }
+ CaseMappingIter::One(c) => f.write_char(c),
+ CaseMappingIter::Zero => Ok(()),
+ }
+ }
+}
+
+#[stable(feature = "char_struct_display", since = "1.16.0")]
+impl fmt::Display for ToLowercase {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ fmt::Display::fmt(&self.0, f)
+ }
+}
+
+#[stable(feature = "char_struct_display", since = "1.16.0")]
+impl fmt::Display for ToUppercase {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ fmt::Display::fmt(&self.0, f)
+ }
+}
+
+/// The error type returned when a checked char conversion fails.
+#[stable(feature = "u8_from_char", since = "1.59.0")]
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+pub struct TryFromCharError(pub(crate) ());
+
+#[stable(feature = "u8_from_char", since = "1.59.0")]
+impl fmt::Display for TryFromCharError {
+ fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
+ "unicode code point out of range".fmt(fmt)
+ }
+}
generated by cgit v1.2.3 (git 2.39.1) at 2024-07-25 18:57:39 +0000