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

@@ -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>),
 {
@@ -146,7 +240,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>),
 {
@@ -443,7 +537,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')),
         ],
     );
 }