Add interpretation function from byte to character

This is useful for custom processing that cannot be easily provided in a generic way. For example,
the `FromBase64` function of ECMA-262 is not a simple instantiation of the existing customizations.
It needs additional special processing.

Author: ia0

cmp/build.rs

@@ -6,6 +6,7 @@ fn main() {
             .compiler(compiler)
             .define("COMPILER", Some(*compiler))
             .file("src/ref.c")
+            .flag_if_supported("-Wno-unterminated-string-initialization")
             .compile(&format!("libref_{}.a", compiler));
     }
 }

cmp/tests/lib.rs

@@ -31,10 +31,7 @@ fn encode_exact() {
 fn difference() {
     let x = b"AAB=";
     assert_eq!(BASE64.decode(x).err().unwrap(), DecodeError { position: 2, kind: Trailing });
-    assert_eq!(
-        BASE64_STANDARD.decode(x).err().unwrap(),
-        InvalidLastSymbol { offset: 2, symbol: b'B', symbol_value: 0x01 },
-    );
+    assert_eq!(BASE64_STANDARD.decode(x).err().unwrap(), InvalidLastSymbol(2, b'B'),);
     let x = b"AA\nB=";
     assert_eq!(BASE64.decode(x).err().unwrap(), DecodeError { position: 4, kind: Length });
     assert_eq!(BASE64_STANDARD.decode(x).err().unwrap(), InvalidByte(2, b'\n'));

lib/src/lib.rs

@@ -840,6 +840,56 @@ pub enum BitOrder {
 #[cfg(feature = "alloc")]
 use crate::BitOrder::*;
 
+/// Interpretation of a byte for decoding purposes
+///
+/// For a given encoding, a byte can either be a symbol of that encoding (with a value within the
+/// number of symbols of that encoding), a padding character, an ignored character, or an invalid
+/// character.
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+pub enum Character {
+    /// A symbol
+    Symbol {
+        /// The value of the symbol
+        value: usize,
+    },
+
+    /// A padding character
+    Padding,
+
+    /// An ignored character
+    Ignored,
+
+    /// An invalid character
+    Invalid,
+}
+
+impl Character {
+    /// Returns whether the character is a symbol
+    ///
+    /// If the character is a symbol, its value is returned.
+    pub fn is_symbol(self) -> Option<usize> {
+        match self {
+            Character::Symbol { value } => Some(value),
+            _ => None,
+        }
+    }
+
+    /// Returns whether the character is padding
+    pub fn is_padding(self) -> bool {
+        matches!(self, Character::Padding)
+    }
+
+    /// Returns whether the character is ignored
+    pub fn is_ignored(self) -> bool {
+        matches!(self, Character::Ignored)
+    }
+
+    /// Returns whether the character is invalid
+    pub fn is_invalid(self) -> bool {
+        matches!(self, Character::Invalid)
+    }
+}
+
 #[doc(hidden)]
 #[cfg(feature = "alloc")]
 pub type InternalEncoding = Cow<'static, [u8]>;
@@ -1600,6 +1650,16 @@ impl Encoding {
         self.bit()
     }
 
+    /// Interprets a byte as a character
+    pub fn interpret_byte(&self, byte: u8) -> Character {
+        match self.val()[byte as usize] {
+            INVALID => Character::Invalid,
+            IGNORE => Character::Ignored,
+            PADDING => Character::Padding,
+            value => Character::Symbol { value: value as usize },
+        }
+    }
+
     /// Returns whether the encoding is canonical
     ///
     /// An encoding is not canonical if one of the following conditions holds: