Add interpretation function from byte to character (#154)

Author: ia0

bin/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.9-git
+
+### Patch
+
+- Update `data-encoding` version
+
 ## 0.3.8
 
 ### Patch

bin/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "data-encoding-bin"
-version = "0.3.8"
+version = "0.3.9-git"
 authors = ["Julien Cretin <git@ia0.eu>"]
 license = "MIT"
 edition = "2021"
@@ -17,5 +17,5 @@ name = "data-encoding"
 path = "src/main.rs"
 
 [dependencies]
-data-encoding = { version = "2.10.0", path = "../lib" }
+data-encoding = { version = "2.11.0-git", path = "../lib" }
 getopts = "0.2"

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));
     }
 }

lib/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.11.0-git
+
+### Minor
+
+- Add `Character` and `Encoding::interpret_byte()` to help with unsupported custom processing
+
 ## 2.10.0
 
 ### Minor

lib/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "data-encoding"
-version = "2.10.0"
+version = "2.11.0-git"
 authors = ["Julien Cretin <git@ia0.eu>"]
 license = "MIT"
 edition = "2018"

lib/macro/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "data-encoding-macro"
-version = "0.1.19"
+version = "0.1.20-git"
 authors = ["Julien Cretin <cretin@google.com>"]
 license = "MIT"
 edition = "2018"
@@ -14,5 +14,5 @@ description = "Macros for data-encoding"
 include = ["Cargo.toml", "LICENSE", "README.md", "src/lib.rs"]
 
 [dependencies]
-data-encoding = { version = "2.10.0", path = "..", default-features = false }
-data-encoding-macro-internal = { version = "0.1.17", path = "internal" }
+data-encoding = { version = "2.11.0-git", path = "..", default-features = false }
+data-encoding-macro-internal = { version = "0.1.18-git", path = "internal" }

lib/macro/internal/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "data-encoding-macro-internal"
-version = "0.1.17"
+version = "0.1.18-git"
 authors = ["Julien Cretin <cretin@google.com>"]
 license = "MIT"
 edition = "2018"
@@ -14,7 +14,7 @@ include = ["Cargo.toml", "LICENSE", "README.md", "src/lib.rs"]
 proc-macro = true
 
 [dependencies.data-encoding]
-version = "2.10.0"
+version = "2.11.0-git"
 path = "../.."
 default-features = false
 features = ["alloc"]

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: