New API which does not expose unreachable

The old API exposes `unreachable` in both unescape_unicode and unescape_mixed.
These are conceptually one function, but because their return types are incompatible,
they could not be unified.

The new API takes this insight further to separate unescape_unicode into separate functions,
such that byte functions can return bytes instead of chars.

Author: hkBst

CHANGELOG.md

@@ -1,3 +1,10 @@
+# 0.0.4
+
+- Add `check_raw_str`, `check_raw_byte_str`, `check_raw_c_str`,
+- Add `unescape_str`, `unescape_byte_str`, `unescape_c_str`,
+- Add `unescape_for_errors`,
+- Remove: `unescape_unicode` and `unescape_mixed`
+
 # 0.0.3
 
 - Extend `rustc-dep-of-std` feature to include `libcore`

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "rustc-literal-escaper"
-version = "0.0.3"
+version = "0.0.4"
 edition = "2021"
 description = "Provides code to unescape string literals"
 license = "Apache-2.0 OR MIT"

Cargo.toml

@@ -23,9 +23,7 @@ fn bench_skip_ascii_whitespace(b: &mut test::Bencher) {
         // skip_ascii_whitespace(&mut input.chars(), 0, &mut |range, res| {
         //     output.push((range, res))
         // });
-        unescape_unicode(&input, Mode::Str, &mut |range, res| {
-            output.push((range, res))
-        });
+        unescape_str(&input, |range, res| output.push((range, res)));
         assert_eq!(
             output,
             [((0..LEN + 2), Err(EscapeError::MultipleSkippedLinesWarning))]
@@ -37,117 +35,122 @@ fn bench_skip_ascii_whitespace(b: &mut test::Bencher) {
 // Check raw
 //
 
-fn bench_check_raw(b: &mut test::Bencher, c: char, mode: Mode) {
-    let input: String = test::black_box(repeat_n(c, LEN).collect());
-    assert_eq!(input.len(), LEN * c.len_utf8());
-    b.iter(|| {
-        let mut output = vec![];
-        unescape_unicode(&input, mode, &mut |range, res| output.push((range, res)));
-        assert_eq!(output.len(), LEN);
-        assert_eq!(output[0], ((0..c.len_utf8()), Ok(c)));
-    });
+macro_rules! fn_bench_check_raw {
+    ($name:ident, $unit:ty, $check_raw:ident) => {
+        fn $name(b: &mut test::Bencher, s: &str, expected: $unit) {
+            let input: String = test::black_box(repeat_n(s, LEN).collect());
+            assert_eq!(input.len(), LEN * s.len());
+            b.iter(|| {
+                let mut output = vec![];
+
+                $check_raw(&input, |range, res| output.push((range, res)));
+                assert_eq!(output.len(), LEN);
+                assert_eq!(output[0], ((0..s.len()), Ok(expected)));
+            });
+        }
+    };
 }
 
+fn_bench_check_raw!(bench_check_raw_str, char, check_raw_str);
+fn_bench_check_raw!(bench_check_raw_byte_str, u8, check_raw_byte_str);
+fn_bench_check_raw!(bench_check_raw_c_str, char, check_raw_c_str);
+
 // raw str
 
 #[bench]
 fn bench_check_raw_str_ascii(b: &mut test::Bencher) {
-    bench_check_raw(b, 'a', Mode::RawStr);
+    bench_check_raw_str(b, "a", 'a');
 }
 
 #[bench]
 fn bench_check_raw_str_unicode(b: &mut test::Bencher) {
-    bench_check_raw(b, '🦀', Mode::RawStr);
+    bench_check_raw_str(b, "🦀", '🦀');
 }
 
 // raw byte str
 
 #[bench]
-fn bench_check_raw_byte_str(b: &mut test::Bencher) {
-    bench_check_raw(b, 'a', Mode::RawByteStr);
+fn bench_check_raw_byte_str_ascii(b: &mut test::Bencher) {
+    bench_check_raw_byte_str(b, "a", b'a');
 }
 
 // raw C str
 
 #[bench]
 fn bench_check_raw_c_str_ascii(b: &mut test::Bencher) {
-    bench_check_raw(b, 'a', Mode::RawCStr);
+    bench_check_raw_c_str(b, "a", 'a');
 }
 
 #[bench]
 fn bench_check_raw_c_str_unicode(b: &mut test::Bencher) {
-    bench_check_raw(b, '🦀', Mode::RawCStr);
+    bench_check_raw_c_str(b, "🦀", '🦀');
 }
 
 //
 // Unescape
 //
 
-fn bench_unescape(b: &mut test::Bencher, s: &str, mode: Mode, expected: char) {
-    let input: String = test::black_box(repeat_n(s, LEN).collect());
-    assert_eq!(input.len(), LEN * s.len());
-    b.iter(|| {
-        let mut output = vec![];
-        unescape_unicode(&input, mode, &mut |range, res| output.push((range, res)));
-        assert_eq!(output.len(), LEN);
-        assert_eq!(output[0], ((0..s.len()), Ok(expected)));
-    });
+macro_rules! fn_bench_unescape {
+    ($name:ident, $unit:ty, $unescape:ident) => {
+        fn $name(b: &mut test::Bencher, s: &str, expected: $unit) {
+            let input: String = test::black_box(repeat_n(s, LEN).collect());
+            assert_eq!(input.len(), LEN * s.len());
+            b.iter(|| {
+                let mut output = vec![];
+
+                $unescape(&input, |range, res| output.push((range, res)));
+                assert_eq!(output.len(), LEN);
+                assert_eq!(output[0], ((0..s.len()), Ok(expected)));
+            });
+        }
+    };
 }
 
+fn_bench_unescape!(bench_unescape_str, char, unescape_str);
+fn_bench_unescape!(bench_unescape_byte_str, u8, unescape_byte_str);
+fn_bench_unescape!(bench_unescape_c_str, MixedUnit, unescape_c_str);
+
 // str
 
 #[bench]
 fn bench_unescape_str_trivial(b: &mut test::Bencher) {
-    bench_unescape(b, r"a", Mode::Str, 'a');
+    bench_unescape_str(b, r"a", 'a');
 }
 
 #[bench]
 fn bench_unescape_str_ascii(b: &mut test::Bencher) {
-    bench_unescape(b, r"\n", Mode::Str, '\n');
+    bench_unescape_str(b, r"\n", '\n');
 }
 
 #[bench]
 fn bench_unescape_str_hex(b: &mut test::Bencher) {
-    bench_unescape(b, r"\x22", Mode::Str, '"');
+    bench_unescape_str(b, r"\x22", '"');
 }
 
 #[bench]
 fn bench_unescape_str_unicode(b: &mut test::Bencher) {
-    bench_unescape(b, r"\u{1f980}", Mode::Str, '🦀');
+    bench_unescape_str(b, r"\u{1f980}", '🦀');
 }
 
 // byte str
 
 #[bench]
 fn bench_unescape_byte_str_trivial(b: &mut test::Bencher) {
-    bench_unescape(b, r"a", Mode::ByteStr, 'a');
+    bench_unescape_byte_str(b, r"a", b'a');
 }
 
 #[bench]
 fn bench_unescape_byte_str_ascii(b: &mut test::Bencher) {
-    bench_unescape(b, r"\n", Mode::ByteStr, b'\n' as char);
+    bench_unescape_byte_str(b, r"\n", b'\n');
 }
 
 #[bench]
 fn bench_unescape_byte_str_hex(b: &mut test::Bencher) {
-    bench_unescape(b, r"\xff", Mode::ByteStr, b'\xff' as char);
+    bench_unescape_byte_str(b, r"\xff", b'\xff');
 }
 
 // C str
 
-fn bench_unescape_c_str(b: &mut test::Bencher, s: &str, expected: MixedUnit) {
-    let input: String = test::black_box(repeat_n(s, LEN).collect());
-    assert_eq!(input.len(), LEN * s.len());
-    b.iter(|| {
-        let mut output = vec![];
-        unescape_mixed(&input, Mode::CStr, &mut |range, res| {
-            output.push((range, res))
-        });
-        assert_eq!(output.len(), LEN);
-        assert_eq!(output[0], ((0..s.len()), Ok(expected)));
-    });
-}
-
 #[bench]
 fn bench_unescape_c_str_trivial(b: &mut test::Bencher) {
     bench_unescape_c_str(b, r"a", MixedUnit::Char('a'));

benches/benches.rs

@@ -80,12 +80,106 @@ impl EscapeError {
     }
 }
 
+/// Takes the contents of a literal (without quotes)
+/// and produces a sequence of errors,
+/// which are returned by invoking `error_callback`.
+pub fn unescape_for_errors(
+    src: &str,
+    mode: Mode,
+    mut error_callback: impl FnMut(Range<usize>, EscapeError),
+) {
+    match mode {
+        Char => {
+            let mut chars = src.chars();
+            if let Err(e) = unescape_char_or_byte(&mut chars, Mode::Char) {
+                error_callback(0..(src.len() - chars.as_str().len()), e);
+            }
+        }
+        Byte => {
+            let mut chars = src.chars();
+            if let Err(e) = unescape_char_or_byte(&mut chars, Mode::Byte) {
+                error_callback(0..(src.len() - chars.as_str().len()), e);
+            }
+        }
+        Str => unescape_str(src, |range, res| {
+            if let Err(e) = res {
+                error_callback(range, e);
+            }
+        }),
+        ByteStr => unescape_byte_str(src, |range, res| {
+            if let Err(e) = res {
+                error_callback(range, e);
+            }
+        }),
+        CStr => unescape_c_str(src, |range, res| {
+            if let Err(e) = res {
+                error_callback(range, e);
+            }
+        }),
+        RawStr => check_raw_str(src, |range, res| {
+            if let Err(e) = res {
+                error_callback(range, e);
+            }
+        }),
+        RawByteStr => check_raw_byte_str(src, |range, res| {
+            if let Err(e) = res {
+                error_callback(range, e);
+            }
+        }),
+        RawCStr => check_raw_c_str(src, |range, res| {
+            if let Err(e) = res {
+                error_callback(range, e);
+            }
+        }),
+    }
+}
+
+pub fn check_raw_str(src: &str, mut callback: impl FnMut(Range<usize>, Result<char, EscapeError>)) {
+    unescape_unicode(src, Mode::RawStr, &mut callback)
+}
+
+pub fn check_raw_byte_str(
+    src: &str,
+    mut callback: impl FnMut(Range<usize>, Result<u8, EscapeError>),
+) {
+    unescape_unicode(src, Mode::RawByteStr, &mut |r, res| {
+        callback(r, res.map(byte_from_char))
+    })
+}
+
+pub fn check_raw_c_str(
+    src: &str,
+    mut callback: impl FnMut(Range<usize>, Result<char, EscapeError>),
+) {
+    unescape_unicode(src, Mode::RawCStr, &mut callback)
+}
+
+pub fn unescape_str(src: &str, mut callback: impl FnMut(Range<usize>, Result<char, EscapeError>)) {
+    unescape_unicode(src, Mode::Str, &mut callback)
+}
+
+pub fn unescape_byte_str(
+    src: &str,
+    mut callback: impl FnMut(Range<usize>, Result<u8, EscapeError>),
+) {
+    unescape_unicode(src, Mode::ByteStr, &mut |r, res| {
+        callback(r, res.map(byte_from_char))
+    })
+}
+
+pub fn unescape_c_str(
+    src: &str,
+    mut callback: impl FnMut(Range<usize>, Result<MixedUnit, EscapeError>),
+) {
+    unescape_mixed(src, Mode::CStr, &mut callback)
+}
+
 /// Takes the contents of a unicode-only (non-mixed-utf8) literal (without
 /// quotes) and produces a sequence of escaped characters or errors.
 ///
 /// Values are returned by invoking `callback`. For `Char` and `Byte` modes,
 /// the callback will be called exactly once.
-pub fn unescape_unicode<F>(src: &str, mode: Mode, callback: &mut F)
+fn unescape_unicode<F>(src: &str, mode: Mode, callback: &mut F)
 where
     F: FnMut(Range<usize>, Result<char, EscapeError>),
 {
@@ -147,7 +241,7 @@ impl From<u8> for MixedUnit {
 /// a sequence of escaped characters or errors.
 ///
 /// Values are returned by invoking `callback`.
-pub fn unescape_mixed<F>(src: &str, mode: Mode, callback: &mut F)
+fn unescape_mixed<F>(src: &str, mode: Mode, callback: &mut F)
 where
     F: FnMut(Range<usize>, Result<MixedUnit, EscapeError>),
 {
@@ -444,7 +538,7 @@ where
 }
 
 #[inline]
-pub fn byte_from_char(c: char) -> u8 {
+fn byte_from_char(c: char) -> u8 {
     let res = c as u32;
     debug_assert!(res <= u8::MAX as u32, "guaranteed because of ByteStr");
     res as u8