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.3
+
+- 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.2
 
 - Add new `rustc-dep-of-std` feature to allow building `libproc-macro`

Cargo.lock

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

Cargo.toml

@@ -3,7 +3,9 @@
 extern crate test;
 
 use rustc_literal_escaper::*;
+use std::fmt::Debug;
 use std::iter::repeat_n;
+use std::ops::Range;
 
 const LEN: usize = 10_000;
 
@@ -23,9 +25,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,58 +37,71 @@ 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());
+#[allow(clippy::type_complexity)]
+fn bench_check_raw<UNIT: Into<char> + PartialEq + Debug + Copy>(
+    b: &mut test::Bencher,
+    c: UNIT,
+    check_raw: fn(&str, &mut dyn FnMut(Range<usize>, Result<UNIT, EscapeError>)),
+) {
+    let input: String = test::black_box(repeat_n(c.into(), LEN).collect());
+    assert_eq!(input.len(), LEN * c.into().len_utf8());
+
     b.iter(|| {
         let mut output = vec![];
-        unescape_unicode(&input, mode, &mut |range, res| output.push((range, res)));
+
+        check_raw(&input, &mut |range, res| output.push((range, res)));
         assert_eq!(output.len(), LEN);
-        assert_eq!(output[0], ((0..c.len_utf8()), Ok(c)));
+        assert_eq!(output[0], (0..c.into().len_utf8(), Ok(c)));
     });
 }
 
 // raw str
 
 #[bench]
 fn bench_check_raw_str_ascii(b: &mut test::Bencher) {
-    bench_check_raw(b, 'a', Mode::RawStr);
+    bench_check_raw(b, 'a', |s, cb| check_raw_str(s, cb));
 }
 
 #[bench]
 fn bench_check_raw_str_unicode(b: &mut test::Bencher) {
-    bench_check_raw(b, '🦀', Mode::RawStr);
+    bench_check_raw(b, '🦀', |s, cb| check_raw_str(s, cb));
 }
 
 // raw byte str
 
 #[bench]
 fn bench_check_raw_byte_str(b: &mut test::Bencher) {
-    bench_check_raw(b, 'a', Mode::RawByteStr);
+    bench_check_raw(b, b'a', |s, cb| check_raw_byte_str(s, cb));
 }
 
 // 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(b, 'a', |s, cb| check_raw_c_str(s, cb));
 }
 
 #[bench]
 fn bench_check_raw_c_str_unicode(b: &mut test::Bencher) {
-    bench_check_raw(b, '🦀', Mode::RawCStr);
+    bench_check_raw(b, '🦀', |s, cb| check_raw_c_str(s, cb));
 }
 
 //
 // Unescape
 //
 
-fn bench_unescape(b: &mut test::Bencher, s: &str, mode: Mode, expected: char) {
+#[allow(clippy::type_complexity)]
+fn bench_unescape<UNIT: Into<char> + PartialEq + Debug + Copy>(
+    b: &mut test::Bencher,
+    s: &str,
+    expected: UNIT,
+    unescape: fn(&str, &mut dyn FnMut(Range<usize>, Result<UNIT, EscapeError>)),
+) {
     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)));
+        unescape(&input, &mut |range, res| output.push((range, res)));
         assert_eq!(output.len(), LEN);
         assert_eq!(output[0], ((0..s.len()), Ok(expected)));
     });
@@ -98,39 +111,39 @@ fn bench_unescape(b: &mut test::Bencher, s: &str, mode: Mode, expected: char) {
 
 #[bench]
 fn bench_unescape_str_trivial(b: &mut test::Bencher) {
-    bench_unescape(b, r"a", Mode::Str, 'a');
+    bench_unescape(b, r"a", 'a', |s, cb| unescape_str(s, cb));
 }
 
 #[bench]
 fn bench_unescape_str_ascii(b: &mut test::Bencher) {
-    bench_unescape(b, r"\n", Mode::Str, '\n');
+    bench_unescape(b, r"\n", '\n', |s, cb| unescape_str(s, cb));
 }
 
 #[bench]
 fn bench_unescape_str_hex(b: &mut test::Bencher) {
-    bench_unescape(b, r"\x22", Mode::Str, '"');
+    bench_unescape(b, r"\x22", '"', |s, cb| unescape_str(s, cb));
 }
 
 #[bench]
 fn bench_unescape_str_unicode(b: &mut test::Bencher) {
-    bench_unescape(b, r"\u{1f980}", Mode::Str, '🦀');
+    bench_unescape(b, r"\u{1f980}", '🦀', |s, cb| unescape_str(s, cb));
 }
 
 // byte str
 
 #[bench]
 fn bench_unescape_byte_str_trivial(b: &mut test::Bencher) {
-    bench_unescape(b, r"a", Mode::ByteStr, 'a');
+    bench_unescape(b, r"a", b'a', |s, cb| unescape_byte_str(s, cb));
 }
 
 #[bench]
 fn bench_unescape_byte_str_ascii(b: &mut test::Bencher) {
-    bench_unescape(b, r"\n", Mode::ByteStr, b'\n' as char);
+    bench_unescape(b, r"\n", b'\n', |s, cb| unescape_byte_str(s, cb));
 }
 
 #[bench]
 fn bench_unescape_byte_str_hex(b: &mut test::Bencher) {
-    bench_unescape(b, r"\xff", Mode::ByteStr, b'\xff' as char);
+    bench_unescape(b, r"\xff", b'\xff', |s, cb| unescape_byte_str(s, cb));
 }
 
 // C str
@@ -140,9 +153,7 @@ fn bench_unescape_c_str(b: &mut test::Bencher, s: &str, expected: MixedUnit) {
     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))
-        });
+        unescape_c_str(&input, &mut |range, res| output.push((range, res)));
         assert_eq!(output.len(), LEN);
         assert_eq!(output[0], ((0..s.len()), Ok(expected)));
     });

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

src/lib.rs

@@ -100,9 +100,7 @@ fn test_unescape_char_good() {
 fn test_unescape_str_warn() {
     fn check(literal: &str, expected: &[(Range<usize>, Result<char, EscapeError>)]) {
         let mut unescaped = Vec::with_capacity(literal.len());
-        unescape_unicode(literal, Mode::Str, &mut |range, res| {
-            unescaped.push((range, res))
-        });
+        unescape_str(literal, |range, res| unescaped.push((range, res)));
         assert_eq!(unescaped, expected);
     }
 
@@ -132,7 +130,7 @@ fn test_unescape_str_warn() {
 fn test_unescape_str_good() {
     fn check(literal_text: &str, expected: &str) {
         let mut buf = Ok(String::with_capacity(literal_text.len()));
-        unescape_unicode(literal_text, Mode::Str, &mut |range, c| {
+        unescape_str(literal_text, |range, c| {
             if let Ok(b) = &mut buf {
                 match c {
                     Ok(c) => b.push(c),
@@ -248,16 +246,16 @@ fn test_unescape_byte_good() {
 #[test]
 fn test_unescape_byte_str_good() {
     fn check(literal_text: &str, expected: &[u8]) {
-        let mut buf = Ok(Vec::with_capacity(literal_text.len()));
-        unescape_unicode(literal_text, Mode::ByteStr, &mut |range, c| {
-            if let Ok(b) = &mut buf {
-                match c {
-                    Ok(c) => b.push(byte_from_char(c)),
-                    Err(e) => buf = Err((range, e)),
+        let mut result = Ok(Vec::with_capacity(literal_text.len()));
+        unescape_byte_str(literal_text, |range, res| {
+            if let Ok(buf) = &mut result {
+                match res {
+                    Ok(b) => buf.push(b),
+                    Err(e) => result = Err((range, e)),
                 }
             }
         });
-        assert_eq!(buf.as_deref(), Ok(expected))
+        assert_eq!(result.as_deref(), Ok(expected))
     }
 
     check("foo", b"foo");
@@ -272,9 +270,7 @@ fn test_unescape_byte_str_good() {
 fn test_unescape_raw_str() {
     fn check(literal: &str, expected: &[(Range<usize>, Result<char, EscapeError>)]) {
         let mut unescaped = Vec::with_capacity(literal.len());
-        unescape_unicode(literal, Mode::RawStr, &mut |range, res| {
-            unescaped.push((range, res))
-        });
+        check_raw_str(literal, |range, res| unescaped.push((range, res)));
         assert_eq!(unescaped, expected);
     }
 
@@ -293,11 +289,9 @@ fn test_unescape_raw_str() {
 
 #[test]
 fn test_unescape_raw_byte_str() {
-    fn check(literal: &str, expected: &[(Range<usize>, Result<char, EscapeError>)]) {
+    fn check(literal: &str, expected: &[(Range<usize>, Result<u8, EscapeError>)]) {
         let mut unescaped = Vec::with_capacity(literal.len());
-        unescape_unicode(literal, Mode::RawByteStr, &mut |range, res| {
-            unescaped.push((range, res))
-        });
+        check_raw_byte_str(literal, |range, res| unescaped.push((range, res)));
         assert_eq!(unescaped, expected);
     }
 
@@ -310,7 +304,7 @@ fn test_unescape_raw_byte_str() {
         "🦀a",
         &[
             (0..4, Err(EscapeError::NonAsciiCharInByte)),
-            (4..5, Ok('a')),
+            (4..5, Ok(b'a')),
         ],
     );
 }