Rename error types to convey their semantics

If a downstream library decodes a hex string into a particular type
using a function in this library the returned error type would "leak"
which type the library used internally. The specific type shouldn't
really concern the callers since it can change anyway. What is relevant
though is whether the length is known at compile time or not.

We might also add more functions in the future decoding to different
types and it'd be better to share error types in such case.

This change renames `HexToBytesError` to `DecodeDynSizedBytesError` and
`HexToArrayError` to `DecodeFixedSizedBytesError` so that types are not
mentioned.

Author: Kixunil

examples/hexy.rs

@@ -8,7 +8,9 @@
 use std::fmt;
 use std::str::FromStr;
 
-use hex_conservative::{fmt_hex_exact, Case, DisplayHex as _, FromHex as _, HexToArrayError};
+use hex_conservative::{
+    fmt_hex_exact, Case, DecodeFixedSizedBytesError, DisplayHex as _, FromHex as _,
+};
 
 fn main() {
     let s = "deadbeefcafebabedeadbeefcafebabedeadbeefcafebabedeadbeefcafebabe";
@@ -46,7 +48,7 @@ impl fmt::Display for Hexy {
 }
 
 impl FromStr for Hexy {
-    type Err = HexToArrayError;
+    type Err = DecodeFixedSizedBytesError;
 
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         // Errors if the input is invalid

examples/wrap_array.rs

@@ -7,7 +7,7 @@
 use core::fmt;
 use core::str::FromStr;
 
-use hex_conservative::{DisplayHex as _, FromHex as _, HexToArrayError};
+use hex_conservative::{DecodeFixedSizedBytesError, DisplayHex as _, FromHex as _};
 
 fn main() {
     let hex = "deadbeefcafebabedeadbeefcafebabedeadbeefcafebabedeadbeefcafebabe";
@@ -72,6 +72,6 @@ impl fmt::UpperHex for Wrap {
 }
 
 impl FromStr for Wrap {
-    type Err = HexToArrayError;
+    type Err = DecodeFixedSizedBytesError;
     fn from_str(s: &str) -> Result<Self, Self::Err> { Ok(Self(<[u8; 32]>::from_hex(s)?)) }
 }

src/error.rs

@@ -70,17 +70,17 @@ pub(crate) use write_err;
 /// This represents the first error encountered during decoding, however we may add other remaining
 /// ones in the future.
 ///
-/// This error differs from [`HexToArrayError`] in that the number of bytes is only known at
-/// run time - e.g. when decoding `Vec<u8>`.
+/// This error differs from [`DecodeFixedSizedBytesError`] in that the number of bytes is only known
+/// at run time - e.g. when decoding `Vec<u8>`.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub enum HexToBytesError {
+pub enum DecodeDynSizedBytesError {
     /// Non-hexadecimal character.
     InvalidChar(InvalidCharError),
     /// Purported hex string had odd (not even) length.
     OddLengthString(OddLengthStringError),
 }
 
-impl HexToBytesError {
+impl DecodeDynSizedBytesError {
     /// Adds `by_bytes` to all character positions stored inside.
     ///
     /// If you're parsing a larger string that consists of multiple hex sub-strings and want to
@@ -97,7 +97,7 @@ impl HexToBytesError {
     #[must_use]
     #[inline]
     pub fn offset(self, by_bytes: usize) -> Self {
-        use HexToBytesError as E;
+        use DecodeDynSizedBytesError as E;
 
         match self {
             E::InvalidChar(e) => E::InvalidChar(e.offset(by_bytes)),
@@ -106,15 +106,15 @@ impl HexToBytesError {
     }
 }
 
-impl From<Infallible> for HexToBytesError {
+impl From<Infallible> for DecodeDynSizedBytesError {
     #[inline]
     fn from(never: Infallible) -> Self { match never {} }
 }
 
-impl fmt::Display for HexToBytesError {
+impl fmt::Display for DecodeDynSizedBytesError {
     #[inline]
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        use HexToBytesError as E;
+        use DecodeDynSizedBytesError as E;
 
         match *self {
             E::InvalidChar(ref e) => write_err!(f, "failed to decode hex"; e),
@@ -124,10 +124,10 @@ impl fmt::Display for HexToBytesError {
 }
 
 if_std_error! {{
-    impl StdError for HexToBytesError {
+    impl StdError for DecodeDynSizedBytesError {
         #[inline]
         fn source(&self) -> Option<&(dyn StdError + 'static)> {
-            use HexToBytesError as E;
+            use DecodeDynSizedBytesError as E;
 
             match *self {
                 E::InvalidChar(ref e) => Some(e),
@@ -137,12 +137,12 @@ if_std_error! {{
     }
 }}
 
-impl From<InvalidCharError> for HexToBytesError {
+impl From<InvalidCharError> for DecodeDynSizedBytesError {
     #[inline]
     fn from(e: InvalidCharError) -> Self { Self::InvalidChar(e) }
 }
 
-impl From<OddLengthStringError> for HexToBytesError {
+impl From<OddLengthStringError> for DecodeDynSizedBytesError {
     #[inline]
     fn from(e: OddLengthStringError) -> Self { Self::OddLengthString(e) }
 }
@@ -169,7 +169,7 @@ impl InvalidCharError {
 
     /// Adds `by_bytes` to all character positions stored inside.
     ///
-    /// **Important**: if you have `HexToBytesError` or `HexToArrayError` you
+    /// **Important**: if you have `DecodeDynSizedBytesError` or `DecodeFixedSizedBytesError` you
     /// should call the method *on them* - do not match them and manually call this method. Doing
     /// so may lead to broken behavior in the future.
     ///
@@ -280,17 +280,17 @@ if_std_error! {{
 
 /// Error returned when hex decoding bytes whose length is known at compile time.
 ///
-/// This error differs from [`HexToBytesError`] in that the number of bytes is known at
+/// This error differs from [`DecodeDynSizedBytesError`] in that the number of bytes is known at
 /// compile time - e.g. when decoding to an array of bytes.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub enum HexToArrayError {
+pub enum DecodeFixedSizedBytesError {
     /// Non-hexadecimal character.
     InvalidChar(InvalidCharError),
     /// Tried to parse fixed-length hash from a string with the wrong length.
     InvalidLength(InvalidLengthError),
 }
 
-impl HexToArrayError {
+impl DecodeFixedSizedBytesError {
     /// Adds `by_bytes` to all character positions stored inside.
     ///
     /// If you're parsing a larger string that consists of multiple hex sub-strings and want to
@@ -307,7 +307,7 @@ impl HexToArrayError {
     #[must_use]
     #[inline]
     pub fn offset(self, by_bytes: usize) -> Self {
-        use HexToArrayError as E;
+        use DecodeFixedSizedBytesError as E;
 
         match self {
             E::InvalidChar(e) => E::InvalidChar(e.offset(by_bytes)),
@@ -316,15 +316,15 @@ impl HexToArrayError {
     }
 }
 
-impl From<Infallible> for HexToArrayError {
+impl From<Infallible> for DecodeFixedSizedBytesError {
     #[inline]
     fn from(never: Infallible) -> Self { match never {} }
 }
 
-impl fmt::Display for HexToArrayError {
+impl fmt::Display for DecodeFixedSizedBytesError {
     #[inline]
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        use HexToArrayError as E;
+        use DecodeFixedSizedBytesError as E;
 
         match *self {
             E::InvalidChar(ref e) => write_err!(f, "failed to parse hex"; e),
@@ -334,10 +334,10 @@ impl fmt::Display for HexToArrayError {
 }
 
 if_std_error! {{
-    impl StdError for HexToArrayError {
+    impl StdError for DecodeFixedSizedBytesError {
         #[inline]
         fn source(&self) -> Option<&(dyn StdError + 'static)> {
-            use HexToArrayError as E;
+            use DecodeFixedSizedBytesError as E;
 
             match *self {
                 E::InvalidChar(ref e) => Some(e),
@@ -347,12 +347,12 @@ if_std_error! {{
     }
 }}
 
-impl From<InvalidCharError> for HexToArrayError {
+impl From<InvalidCharError> for DecodeFixedSizedBytesError {
     #[inline]
     fn from(e: InvalidCharError) -> Self { Self::InvalidChar(e) }
 }
 
-impl From<InvalidLengthError> for HexToArrayError {
+impl From<InvalidLengthError> for DecodeFixedSizedBytesError {
     #[inline]
     fn from(e: InvalidLengthError) -> Self { Self::InvalidLength(e) }
 }
@@ -421,7 +421,7 @@ mod tests {
     fn invalid_char_error() {
         let result = <Vec<u8> as FromHex>::from_hex("12G4");
         let error = result.unwrap_err();
-        if let HexToBytesError::InvalidChar(e) = error {
+        if let DecodeDynSizedBytesError::InvalidChar(e) = error {
             assert!(!format!("{}", e).is_empty());
             assert_eq!(e.invalid_char(), b'G');
             assert_eq!(e.pos(), 2);
@@ -437,7 +437,7 @@ mod tests {
         let error = result.unwrap_err();
         assert!(!format!("{}", error).is_empty());
         check_source(&error);
-        if let HexToBytesError::OddLengthString(e) = error {
+        if let DecodeDynSizedBytesError::OddLengthString(e) = error {
             assert!(!format!("{}", e).is_empty());
             assert_eq!(e.length(), 3);
         } else {
@@ -451,7 +451,7 @@ mod tests {
         let error = result.unwrap_err();
         assert!(!format!("{}", error).is_empty());
         check_source(&error);
-        if let HexToArrayError::InvalidLength(e) = error {
+        if let DecodeFixedSizedBytesError::InvalidLength(e) = error {
             assert!(!format!("{}", e).is_empty());
             assert_eq!(e.expected_length(), 8);
             assert_eq!(e.invalid_length(), 3);
@@ -462,14 +462,17 @@ mod tests {
 
     #[test]
     fn to_bytes_error() {
-        let error = HexToBytesError::OddLengthString(OddLengthStringError { len: 7 });
+        let error = DecodeDynSizedBytesError::OddLengthString(OddLengthStringError { len: 7 });
         assert!(!format!("{}", error).is_empty());
         check_source(&error);
     }
 
     #[test]
     fn to_array_error() {
-        let error = HexToArrayError::InvalidLength(InvalidLengthError { expected: 8, invalid: 7 });
+        let error = DecodeFixedSizedBytesError::InvalidLength(InvalidLengthError {
+            expected: 8,
+            invalid: 7,
+        });
         assert!(!format!("{}", error).is_empty());
         check_source(&error);
     }

src/lib.rs

@@ -113,7 +113,7 @@ pub(crate) use table::Table;
 pub use self::{
     display::DisplayHex,
     error::{
-        HexToArrayError, HexToBytesError, InvalidCharError, InvalidLengthError,
+        DecodeFixedSizedBytesError, DecodeDynSizedBytesError, InvalidCharError, InvalidLengthError,
         OddLengthStringError,
     },
     iter::{BytesToHexIter, HexToBytesIter, HexSliceToBytesIter},
@@ -130,11 +130,11 @@ pub use self::{
 ///
 /// Returns an error if `hex` contains invalid characters or doesn't have even length.
 #[cfg(feature = "alloc")]
-pub fn decode_to_vec(hex: &str) -> Result<Vec<u8>, HexToBytesError> {
+pub fn decode_to_vec(hex: &str) -> Result<Vec<u8>, DecodeDynSizedBytesError> {
     Ok(HexToBytesIter::new(hex)?.drain_to_vec()?)
 }
 
-/// Decodes a hex string with an expected length kown at compile time.
+/// Decodes a hex string with an expected length known at compile time.
 ///
 /// If you don't know the required length at compile time you need to use [`decode_to_vec`]
 /// instead.
@@ -143,7 +143,7 @@ pub fn decode_to_vec(hex: &str) -> Result<Vec<u8>, HexToBytesError> {
 ///
 /// Returns an error if `hex` contains invalid characters or has incorrect length. (Should be
 /// `N * 2`.)
-pub fn decode_to_array<const N: usize>(hex: &str) -> Result<[u8; N], HexToArrayError> {
+pub fn decode_to_array<const N: usize>(hex: &str) -> Result<[u8; N], DecodeFixedSizedBytesError> {
     if hex.len() == N * 2 {
         let mut ret = [0u8; N];
         // checked above

src/parse.rs

@@ -8,7 +8,7 @@ use core::{fmt, str};
 use crate::alloc::vec::Vec;
 
 #[rustfmt::skip]                // Keep public re-exports separate.
-pub use crate::error::{HexToBytesError, HexToArrayError};
+pub use crate::error::{DecodeDynSizedBytesError, DecodeFixedSizedBytesError};
 
 /// Trait for objects that can be deserialized from hex strings.
 pub trait FromHex: Sized + sealed::Sealed {
@@ -25,14 +25,14 @@ pub trait FromHex: Sized + sealed::Sealed {
 
 #[cfg(feature = "alloc")]
 impl FromHex for Vec<u8> {
-    type Error = HexToBytesError;
+    type Error = DecodeDynSizedBytesError;
 
     #[inline]
     fn from_hex(s: &str) -> Result<Self, Self::Error> { crate::decode_to_vec(s) }
 }
 
 impl<const LEN: usize> FromHex for [u8; LEN] {
-    type Error = HexToArrayError;
+    type Error = DecodeFixedSizedBytesError;
 
     fn from_hex(s: &str) -> Result<Self, Self::Error> { crate::decode_to_array(s) }
 }

tests/api.rs

@@ -17,8 +17,9 @@ use core::{fmt, slice};
 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,
+    buf_encoder, display, BytesToHexIter, Case, DecodeDynSizedBytesError,
+    DecodeFixedSizedBytesError, DisplayHex as _, InvalidCharError, InvalidLengthError,
+    OddLengthStringError,
 };
 
 /// A struct that includes all public non-error enums.
@@ -86,8 +87,8 @@ 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 {
-    c: HexToArrayError,
-    d: HexToBytesError,
+    c: DecodeFixedSizedBytesError,
+    d: DecodeDynSizedBytesError,
     e: InvalidCharError,
     f: InvalidLengthError,
     g: OddLengthStringError,