feat: ascii::char, ascii::str and ascii::bytes for compile-time-checked items

src/ascii_char.rs

@@ -16,7 +16,10 @@ pub enum AsciiChar {
     #[allow(clippy::doc_markdown)]
     /// [Start of TeXt](http://en.wikipedia.org/wiki/Start_of_Text)
     #[doc(hidden)]
-    #[deprecated(since="1.2.0", note="Replaced with AsciiChar::STX which is the correct name for this variant.")]
+    #[deprecated(
+        since = "1.2.0",
+        note = "Replaced with AsciiChar::STX which is the correct name for this variant."
+    )]
     SOX = 2,
     /// [End of TeXt](http://en.wikipedia.org/wiki/End-of-Text_character)
     ETX = 3,
@@ -794,8 +797,8 @@ macro_rules! impl_into_partial_eq_ord {
     ($wider:ty, $to_wider:expr) => {
         impl From<AsciiChar> for $wider {
             #[inline]
-            fn from(a: AsciiChar) -> $wider {
-                $to_wider(a)
+            fn from(value: AsciiChar) -> $wider {
+                $to_wider(value)
             }
         }
         impl PartialEq<$wider> for AsciiChar {

src/lib.rs

@@ -80,3 +80,56 @@ pub use ascii_str::{Chars, CharsMut, CharsRef};
 #[cfg(feature = "alloc")]
 pub use ascii_string::{AsciiString, FromAsciiError, IntoAsciiString};
 pub use free_functions::{caret_decode, caret_encode};
+
+/// Create a compile-time checked [`AsciiChar`] from a `const char`.
+/// ```
+/// ascii::char!('a');
+/// ```
+/// ```compile_fail
+/// ascii::char!('\u{FFFD}');
+/// ```
+#[macro_export]
+macro_rules! char {
+    ($expr:expr) => {{
+        const MUST_BE_CONST_EVALUABLE: $crate::AsciiChar = { $crate::AsciiChar::new($expr) };
+        MUST_BE_CONST_EVALUABLE
+    }};
+}
+
+/// Create a compile-time checked [`AsciiStr`] from a `const str`.
+///
+/// ```
+/// ascii::str!("a");
+/// ```
+/// ```compile_fail
+/// ascii::str!("\u{FFFD}");
+/// ```
+#[macro_export]
+macro_rules! str {
+    ($expr:expr) => {{
+        const MUST_BE_CONST_EVALUABLE: &$crate::AsciiStr =
+            match $crate::AsciiStr::from_ascii_str($expr) {
+                Ok(it) => it,
+                Err(_) => panic!("string literal contained non-ascii bytes"),
+            };
+        MUST_BE_CONST_EVALUABLE
+    }};
+}
+/// Create a compile-time checked [`AsciiStr`] from a `const &[u8]`.
+/// ```
+/// ascii::bytes!(b"a");
+/// ```
+/// ```compile_fail
+/// ascii::bytes!(b"\xFF");
+/// ```
+#[macro_export]
+macro_rules! bytes {
+    ($expr:expr) => {{
+        const MUST_BE_CONST_EVALUABLE: &$crate::AsciiStr =
+            match $crate::AsciiStr::from_ascii_bytes($expr) {
+                Ok(it) => it,
+                Err(_) => panic!("string literal contained non-ascii bytes"),
+            };
+        MUST_BE_CONST_EVALUABLE
+    }};
+}