Hack up a -jra version of this crate

contrib/check-for-api-changes.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+#
+# Checks the public API of crates, exits with non-zero if there are currently
+# changes to the public API not already committed to in the various api/*.txt
+# files.
+
+set -e
+
+REPO_DIR=$(git rev-parse --show-toplevel)
+API_DIR="$REPO_DIR/api"
+
+CARGO="cargo +nightly public-api --simplified"
+# `sort -n -u` doesn't work for some reason.
+SORT="sort --numeric-sort"
+
+# Sort order is effected by locale. See `man sort`.
+# > Set LC_ALL=C to get the traditional sort order that uses native byte values.
+export LC_ALL=C
+
+main() {
+    # cargo public-api uses nightly so the toolchain must be available.
+    if ! cargo +nightly --version > /dev/null; then
+        echo "script requires a nightly toolchain to be installed (possibly >= nightly-2023-05-24)" >&2
+        exit 1
+    fi
+
+    generate_api_files
+    check_for_changes
+}
+
+generate_api_files() {
+    pushd "$REPO_DIR" > /dev/null
+
+    $CARGO | $SORT | uniq > "$API_DIR/default-features.txt"
+
+    $CARGO --no-default-features | $SORT | uniq > "$API_DIR/no-default-features.txt"
+    $CARGO --no-default-features --features=alloc | $SORT | uniq > "$API_DIR/alloc.txt"
+    $CARGO --all-features | $SORT | uniq > "$API_DIR/all-features.txt"
+
+    popd > /dev/null
+}
+
+# Check if there are changes (dirty git index) to the `api/` directory.
+check_for_changes() {
+    pushd "$REPO_DIR" > /dev/null
+
+    if [[ $(git status --porcelain api) ]]; then
+        git diff --color=always
+
+        echo
+        echo "You have introduced changes to the public API, commit the changes to api/ currently in your working directory" >&2
+        exit 1
+
+    else
+        echo "No changes to the current public API"
+    fi
+
+    popd > /dev/null
+}
+
+#
+# Main script
+#
+main "$@"
+exit 0

src/error.rs

@@ -26,60 +26,33 @@ macro_rules! write_err {
     }
 }
 
-/// Hex decoding error.
+/// Hex decoding error while parsing to a vector of bytes.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub struct HexToBytesError(pub(crate) ToBytesError);
+pub enum HexToBytesError {
+    /// Non-hexadecimal character.
+    InvalidChar(InvalidCharError),
+    /// Purported hex string had odd length.
+    OddLengthString(OddLengthStringError),
+}
 
 impl From<Infallible> for HexToBytesError {
     #[inline]
     fn from(never: Infallible) -> Self { match never {} }
 }
 
-impl HexToBytesError {
-    /// Returns a [`ToBytesError`] from this [`HexToBytesError`].
-    // Use clone instead of reference to give use maximum forward flexibility.
-    #[inline]
-    pub fn parse_error(&self) -> ToBytesError { self.0.clone() }
-}
-
-impl fmt::Display for HexToBytesError {
-    #[inline]
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { fmt::Display::fmt(&self.0, f) }
-}
-
-#[cfg(feature = "std")]
-impl std::error::Error for HexToBytesError {
-    #[inline]
-    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { Some(&self.0) }
-}
-
 impl From<InvalidCharError> for HexToBytesError {
     #[inline]
-    fn from(e: InvalidCharError) -> Self { Self(e.into()) }
+    fn from(e: InvalidCharError) -> Self { Self::InvalidChar(e) }
 }
 
 impl From<OddLengthStringError> for HexToBytesError {
     #[inline]
-    fn from(e: OddLengthStringError) -> Self { Self(e.into()) }
-}
-
-/// Hex decoding error while parsing to a vector of bytes.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub enum ToBytesError {
-    /// Non-hexadecimal character.
-    InvalidChar(InvalidCharError),
-    /// Purported hex string had odd length.
-    OddLengthString(OddLengthStringError),
-}
-
-impl From<Infallible> for ToBytesError {
-    #[inline]
-    fn from(never: Infallible) -> Self { match never {} }
+    fn from(e: OddLengthStringError) -> Self { Self::OddLengthString(e) }
 }
 
-impl fmt::Display for ToBytesError {
+impl fmt::Display for HexToBytesError {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        use ToBytesError as E;
+        use HexToBytesError as E;
 
         match *self {
             E::InvalidChar(ref e) =>
@@ -91,9 +64,9 @@ impl fmt::Display for ToBytesError {
 }
 
 #[cfg(feature = "std")]
-impl std::error::Error for ToBytesError {
+impl std::error::Error for HexToBytesError {
     fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
-        use ToBytesError as E;
+        use HexToBytesError as E;
 
         match *self {
             E::InvalidChar(ref e) => Some(e),
@@ -102,17 +75,11 @@ impl std::error::Error for ToBytesError {
     }
 }
 
-impl From<InvalidCharError> for ToBytesError {
-    #[inline]
-    fn from(e: InvalidCharError) -> Self { Self::InvalidChar(e) }
-}
-
-impl From<OddLengthStringError> for ToBytesError {
-    #[inline]
-    fn from(e: OddLengthStringError) -> Self { Self::OddLengthString(e) }
-}
-
 /// Invalid hex character.
+///
+/// This error type only supports ASCII characters. If you try to parse a hex string that
+/// includes multi-byte UTF-8 encoded characters this error will be confusing as it will only
+/// include the first byte of the encoding not the whole character.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct InvalidCharError {
     pub(crate) invalid: u8,
@@ -126,8 +93,11 @@ impl From<Infallible> for InvalidCharError {
 
 impl InvalidCharError {
     /// Returns the invalid character byte.
+    ///
+    /// If the parsing error is caused by a multi-byte UTF-8 encoded character then this will only
+    /// return the first byte of that character.
     #[inline]
-    pub fn invalid_char(&self) -> u8 { self.invalid }
+    pub fn invalid_byte(&self) -> u8 { self.invalid }
     /// Returns the position of the invalid character byte.
     #[inline]
     pub fn pos(&self) -> usize { self.pos }
@@ -136,7 +106,7 @@ impl InvalidCharError {
 impl fmt::Display for InvalidCharError {
     #[inline]
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        write!(f, "invalid hex char {} at pos {}", self.invalid_char(), self.pos())
+        write!(f, "invalid hex char {} at pos {}", self.invalid_byte(), self.pos())
     }
 }
 
@@ -170,60 +140,23 @@ impl fmt::Display for OddLengthStringError {
 #[cfg(feature = "std")]
 impl std::error::Error for OddLengthStringError {}
 
-/// Hex decoding error.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct HexToArrayError(pub(crate) ToArrayError);
-
-impl From<Infallible> for HexToArrayError {
-    #[inline]
-    fn from(never: Infallible) -> Self { match never {} }
-}
-
-impl HexToArrayError {
-    /// Returns a [`ToArrayError`] from this [`HexToArrayError`].
-    // Use clone instead of reference to give use maximum forward flexibility.
-    #[inline]
-    pub fn parse_error(&self) -> ToArrayError { self.0.clone() }
-}
-
-impl fmt::Display for HexToArrayError {
-    #[inline]
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { fmt::Display::fmt(&self.0, f) }
-}
-
-#[cfg(feature = "std")]
-impl std::error::Error for HexToArrayError {
-    #[inline]
-    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { Some(&self.0) }
-}
-
-impl From<InvalidCharError> for HexToArrayError {
-    #[inline]
-    fn from(e: InvalidCharError) -> Self { Self(e.into()) }
-}
-
-impl From<InvalidLengthError> for HexToArrayError {
-    #[inline]
-    fn from(e: InvalidLengthError) -> Self { Self(e.into()) }
-}
-
 /// Hex decoding error while parsing a byte array.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub enum ToArrayError {
+pub enum HexToArrayError {
     /// Non-hexadecimal character.
     InvalidChar(InvalidCharError),
     /// Tried to parse fixed-length hash from a string with the wrong length.
     InvalidLength(InvalidLengthError),
 }
 
-impl From<Infallible> for ToArrayError {
+impl From<Infallible> for HexToArrayError {
     #[inline]
     fn from(never: Infallible) -> Self { match never {} }
 }
 
-impl fmt::Display for ToArrayError {
+impl fmt::Display for HexToArrayError {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        use ToArrayError as E;
+        use HexToArrayError as E;
 
         match *self {
             E::InvalidChar(ref e) => write_err!(f, "failed to parse hex digit"; e),
@@ -233,9 +166,9 @@ impl fmt::Display for ToArrayError {
 }
 
 #[cfg(feature = "std")]
-impl std::error::Error for ToArrayError {
+impl std::error::Error for HexToArrayError {
     fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
-        use ToArrayError as E;
+        use HexToArrayError as E;
 
         match *self {
             E::InvalidChar(ref e) => Some(e),
@@ -244,12 +177,12 @@ impl std::error::Error for ToArrayError {
     }
 }
 
-impl From<InvalidCharError> for ToArrayError {
+impl From<InvalidCharError> for HexToArrayError {
     #[inline]
     fn from(e: InvalidCharError) -> Self { Self::InvalidChar(e) }
 }
 
-impl From<InvalidLengthError> for ToArrayError {
+impl From<InvalidLengthError> for HexToArrayError {
     #[inline]
     fn from(e: InvalidLengthError) -> Self { Self::InvalidLength(e) }
 }
@@ -305,9 +238,9 @@ mod tests {
     fn invalid_char_error() {
         let result = <Vec<u8> as FromHex>::from_hex("12G4");
         let error = result.unwrap_err();
-        if let HexToBytesError(ToBytesError::InvalidChar(e)) = error {
+        if let HexToBytesError::InvalidChar(e) = error {
             assert!(!format!("{}", e).is_empty());
-            assert_eq!(e.invalid_char(), b'G');
+            assert_eq!(e.invalid_byte(), b'G');
             assert_eq!(e.pos(), 2);
         } else {
             panic!("Expected InvalidCharError");
@@ -320,7 +253,7 @@ mod tests {
         let error = result.unwrap_err();
         assert!(!format!("{}", error).is_empty());
         check_source(&error);
-        if let HexToBytesError(ToBytesError::OddLengthString(e)) = error {
+        if let HexToBytesError::OddLengthString(e) = error {
             assert!(!format!("{}", e).is_empty());
             assert_eq!(e.length(), 3);
         } else {
@@ -334,7 +267,7 @@ mod tests {
         let error = result.unwrap_err();
         assert!(!format!("{}", error).is_empty());
         check_source(&error);
-        if let HexToArrayError(ToArrayError::InvalidLength(e)) = error {
+        if let HexToArrayError::InvalidLength(e) = error {
             assert!(!format!("{}", e).is_empty());
             assert_eq!(e.expected_length(), 8);
             assert_eq!(e.invalid_length(), 3);
@@ -345,14 +278,14 @@ mod tests {
 
     #[test]
     fn to_bytes_error() {
-        let error = ToBytesError::OddLengthString(OddLengthStringError { len: 7 });
+        let error = HexToBytesError::OddLengthString(OddLengthStringError { len: 7 });
         assert!(!format!("{}", error).is_empty());
         check_source(&error);
     }
 
     #[test]
     fn to_array_error() {
-        let error = ToArrayError::InvalidLength(InvalidLengthError { expected: 8, invalid: 7 });
+        let error = HexToArrayError::InvalidLength(InvalidLengthError { expected: 8, invalid: 7 });
         assert!(!format!("{}", error).is_empty());
         check_source(&error);
     }

src/lib.rs

@@ -10,13 +10,17 @@
 //! // In your manifest use the `package` key to improve import ergonomics.
 //! // hex = { package = "hex-conservative", version = "*" }
 //! # use hex_conservative as hex; // No need for this if using `package` as above.
-//! use hex::prelude::*;
+//! use hex::prelude::*;  // Imports `FromHex` and `Display`.
 //!
 //! // Decode an arbitrary length hex string into a vector.
 //! let v = Vec::from_hex("deadbeef").expect("valid hex digits");
 //! // Or a known length hex string into a fixed size array.
 //! let a = <[u8; 4]>::from_hex("deadbeef").expect("valid length and valid hex digits");
 //!
+//! // If you don't want to import the `FromHex` trait use inherent functions instead.
+//! let v = hex::decode_vec("deadbeef").expect("even string length and valid hex digits");
+//! let a = hex::decode_array::<[u8; 4]>("deadbeef").expect("valid length and valid hex digits");
+//!
 //! // We support `LowerHex` and `UpperHex` out of the box for `[u8]` slices.
 //! println!("An array as lower hex: {:x}", a.as_hex());
 //! // And for vecs since `Vec` derefs to byte slice.
@@ -54,7 +58,7 @@ pub mod _export {
 
 pub mod buf_encoder;
 pub mod display;
-pub mod error;
+mod error;
 mod iter;
 pub mod parse;
 #[cfg(feature = "serde")]
@@ -76,8 +80,7 @@ pub(crate) use table::Table;
 pub use self::{
     display::DisplayHex,
     error::{
-        HexToArrayError, HexToBytesError, InvalidCharError, InvalidLengthError,
-        OddLengthStringError, ToArrayError, ToBytesError,
+        HexToArrayError, HexToBytesError, InvalidCharError, InvalidLengthError, OddLengthStringError,
     },
     iter::{BytesToHexIter, HexToBytesIter, HexSliceToBytesIter},
     parse::FromHex,

tests/api.rs

@@ -18,7 +18,7 @@ use hex_conservative::serde;
 // These imports test "typical" usage by user code.
 use hex_conservative::{
     buf_encoder, display, BytesToHexIter, Case, DisplayHex as _, HexToArrayError, HexToBytesError,
-    InvalidCharError, InvalidLengthError, OddLengthStringError, ToArrayError, ToBytesError,
+    InvalidCharError, InvalidLengthError, OddLengthStringError,
 };
 
 /// A struct that includes all public non-error enums.
@@ -86,13 +86,11 @@ impl Structs<'_, slice::Iter<'_, u8>, String> {
 // These derives are the policy of `rust-bitcoin` not Rust API guidelines.
 #[derive(Debug, Clone, PartialEq, Eq)] // All public types implement Debug (C-DEBUG).
 struct Errors {
-    a: ToArrayError,
-    b: ToBytesError,
-    c: HexToArrayError,
-    d: HexToBytesError,
-    e: InvalidCharError,
-    f: InvalidLengthError,
-    g: OddLengthStringError,
+    a: HexToArrayError,
+    b: HexToBytesError,
+    c: InvalidCharError,
+    d: InvalidLengthError,
+    e: OddLengthStringError,
 }
 
 // `Debug` representation is never empty (C-DEBUG-NONEMPTY).