core: implement Add and AddAssign for ascii::Char

Implement Add and AddAsign for core::ascii::Char treating it as if it
was a 7-bit unsigned type, i.e. in debug builds overflow panics and in
release seven least significant bits of the result are taken.

The operators can be used to convert an integer into a digit or
a letter of an alphabet:

    use core::ascii::Char;

    assert_eq!(Char::Digit8, Char::Digit0 + 8);
    assert_eq!(Char::SmallI, Char::SmallA + 8);

Issue: #110998

Author: mina86

library/core/src/ascii/ascii_char.rs

@@ -5,6 +5,7 @@
 
 use crate::fmt::{self, Write};
 use crate::mem::transmute;
+use crate::ops::{Add, AddAssign};
 
 /// One of the 128 Unicode characters from U+0000 through U+007F,
 /// often known as the [ASCII] subset.
@@ -616,3 +617,71 @@ impl fmt::Debug for AsciiChar {
         f.write_char('\'')
     }
 }
+
+#[unstable(feature = "ascii_char", issue = "110998")]
+impl Add<u8> for AsciiChar {
+    type Output = AsciiChar;
+
+    /// Calculates sum of the ASCII value and given offset.
+    ///
+    /// In debug builds, panics if result is greater than largest ASCII value.
+    /// In release builds wraps the value (i.e. masks out the most significant
+    /// bit) so the output is a valid ASCII character.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(ascii_char, ascii_char_variants)]
+    /// use core::ascii::Char;
+    ///
+    /// assert_eq!(Char::Digit8, Char::Digit0 + 8);
+    /// ```
+    ///
+    /// ```should_panic
+    /// #![feature(ascii_char, ascii_char_variants)]
+    /// use core::ascii::Char;
+    ///
+    /// // This produces value which is not a valid ASCII character and thus
+    /// // panics in debug builds.
+    /// let _ = Char::Digit0 + 100;
+    /// ```
+    #[inline]
+    #[rustc_inherit_overflow_checks]
+    fn add(self, rhs: u8) -> Self::Output {
+        add_impl(self, rhs)
+    }
+}
+
+#[unstable(feature = "ascii_char", issue = "110998")]
+impl Add<AsciiChar> for u8 {
+    type Output = AsciiChar;
+
+    #[inline]
+    #[rustc_inherit_overflow_checks]
+    fn add(self, rhs: AsciiChar) -> Self::Output {
+        add_impl(rhs, self)
+    }
+}
+
+#[unstable(feature = "ascii_char", issue = "110998")]
+impl AddAssign<u8> for AsciiChar {
+    #[inline]
+    #[rustc_inherit_overflow_checks]
+    fn add_assign(&mut self, rhs: u8) {
+        *self = add_impl(*self, rhs)
+    }
+}
+
+forward_ref_binop! { impl Add, add for AsciiChar, u8 }
+forward_ref_binop! { impl Add, add for u8, AsciiChar }
+forward_ref_op_assign! { impl AddAssign, add_assign for AsciiChar, u8 }
+
+#[inline]
+#[rustc_inherit_overflow_checks]
+fn add_impl(chr: AsciiChar, rhs: u8) -> AsciiChar {
+    // Make sure we overflow if chr + rhs ≥ 128.  Since we inherit overflow
+    // checks, we’re wrap in release and panic in debug builds.
+    let sum = u8::from(chr) + 128 + rhs;
+    // SAFETY: `sum & 127` limits the sum to a valid ASCII value.
+    unsafe { AsciiChar::from_u8_unchecked(sum & 127) }
+}

library/core/tests/ascii_char.rs

@@ -0,0 +1,38 @@
+use core::ascii::Char;
+
+/// Tests addition of u8 values to ascii::Char;
+#[test]
+fn test_arithmetic_ok() {
+    assert_eq!(Char::Digit8, Char::Digit0 + 8);
+    assert_eq!(Char::Colon, Char::Digit0 + 10);
+    assert_eq!(Char::Digit8, 8 + Char::Digit0);
+    assert_eq!(Char::Colon, 10 + Char::Digit0);
+
+    let mut digit = Char::Digit0;
+    digit += 8;
+    assert_eq!(Char::Digit8, digit);
+}
+
+/// Tests addition wraps values when built in release mode.
+#[test]
+#[cfg_attr(debug_assertions, ignore = "works in release builds only")]
+fn test_arithmetic_wrapping() {
+    assert_eq!(Char::Digit0, Char::Digit8 + 120);
+    assert_eq!(Char::Digit0, Char::Digit8 + 248);
+}
+
+/// Tests addition panics in debug build when it produces an invalid ASCII char.
+#[test]
+#[cfg_attr(not(debug_assertions), ignore = "works in debug builds only")]
+#[should_panic]
+fn test_arithmetic_non_ascii() {
+    let _ = Char::Digit0 + 120;
+}
+
+/// Tests addition panics in debug build when it overflowing u8.
+#[test]
+#[cfg_attr(not(debug_assertions), ignore = "works in debug builds only")]
+#[should_panic]
+fn test_arithmetic_overflow() {
+    let _ = Char::Digit0 + 250;
+}

library/core/tests/lib.rs

@@ -124,6 +124,7 @@ mod alloc;
 mod any;
 mod array;
 mod ascii;
+mod ascii_char;
 mod asserting;
 mod async_iter;
 mod atomic;