src/libserialize/hex.rs

   1 //! Hex binary-to-text encoding
   2
   3 pub use self::FromHexError::*;
   4
   5 use std::error;
   6 use std::fmt;
   7
   8 /// A trait for converting a value to hexadecimal encoding
   9 pub trait ToHex {
  10     /// Converts the value of `self` to a hex value, returning the owned
  11     /// string.
  12     fn to_hex(&self) -> String;
  13 }
  14
  15 const CHARS: &[u8] = b"0123456789abcdef";
  16
  17 impl ToHex for [u8] {
  18     /// Turn a vector of `u8` bytes into a hexadecimal string.
  19     ///
  20     /// # Examples
  21     ///
  22     /// ```
  23     /// #![feature(rustc_private)]
  24     ///
  25     /// extern crate serialize;
  26     /// use serialize::hex::ToHex;
  27     ///
  28     /// fn main () {
  29     ///     let str = [52,32].to_hex();
  30     ///     println!("{}", str);
  31     /// }
  32     /// ```
  33     fn to_hex(&self) -> String {
  34         let mut v = Vec::with_capacity(self.len() * 2);
  35         for &byte in self {
  36             v.push(CHARS[(byte >> 4) as usize]);
  37             v.push(CHARS[(byte & 0xf) as usize]);
  38         }
  39
  40         unsafe { String::from_utf8_unchecked(v) }
  41     }
  42 }
  43
  44 /// A trait for converting hexadecimal encoded values
  45 pub trait FromHex {
  46     /// Converts the value of `self`, interpreted as hexadecimal encoded data,
  47     /// into an owned vector of bytes, returning the vector.
  48     fn from_hex(&self) -> Result<Vec<u8>, FromHexError>;
  49 }
  50
  51 /// Errors that can occur when decoding a hex encoded string
  52 #[derive(Copy, Clone, Debug)]
  53 pub enum FromHexError {
  54     /// The input contained a character not part of the hex format
  55     InvalidHexCharacter(char, usize),
  56     /// The input had an invalid length
  57     InvalidHexLength,
  58 }
  59
  60 impl fmt::Display for FromHexError {
  61     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  62         match *self {
  63             InvalidHexCharacter(ch, idx) => {
  64                 write!(f, "Invalid character '{}' at position {}", ch, idx)
  65             }
  66             InvalidHexLength => write!(f, "Invalid input length"),
  67         }
  68     }
  69 }
  70
  71 impl error::Error for FromHexError {
  72     fn description(&self) -> &str {
  73         match *self {
  74             InvalidHexCharacter(..) => "invalid character",
  75             InvalidHexLength => "invalid length",
  76         }
  77     }
  78 }
  79
  80 impl FromHex for str {
  81     /// Converts any hexadecimal encoded string (literal, `@`, `&`, or `~`)
  82     /// to the byte values it encodes.
  83     ///
  84     /// You can use the `String::from_utf8` function to turn a
  85     /// `Vec<u8>` into a string with characters corresponding to those values.
  86     ///
  87     /// # Examples
  88     ///
  89     /// This converts a string literal to hexadecimal and back.
  90     ///
  91     /// ```
  92     /// #![feature(rustc_private)]
  93     ///
  94     /// extern crate serialize;
  95     /// use serialize::hex::{FromHex, ToHex};
  96     ///
  97     /// fn main () {
  98     ///     let hello_str = "Hello, World".as_bytes().to_hex();
  99     ///     println!("{}", hello_str);
 100     ///     let bytes = hello_str.from_hex().unwrap();
 101     ///     println!("{:?}", bytes);
 102     ///     let result_str = String::from_utf8(bytes).unwrap();
 103     ///     println!("{}", result_str);
 104     /// }
 105     /// ```
 106     fn from_hex(&self) -> Result<Vec<u8>, FromHexError> {
 107         // This may be an overestimate if there is any whitespace
 108         let mut b = Vec::with_capacity(self.len() / 2);
 109         let mut modulus = 0;
 110         let mut buf = 0;
 111
 112         for (idx, byte) in self.bytes().enumerate() {
 113             buf <<= 4;
 114
 115             match byte {
 116                 b'A'..=b'F' => buf |= byte - b'A' + 10,
 117                 b'a'..=b'f' => buf |= byte - b'a' + 10,
 118                 b'0'..=b'9' => buf |= byte - b'0',
 119                 b' ' | b'\r' | b'\n' | b'\t' => {
 120                     buf >>= 4;
 121                     continue;
 122                 }
 123                 _ => {
 124                     let ch = self[idx..].chars().next().unwrap();
 125                     return Err(InvalidHexCharacter(ch, idx));
 126                 }
 127             }
 128
 129             modulus += 1;
 130             if modulus == 2 {
 131                 modulus = 0;
 132                 b.push(buf);
 133             }
 134         }
 135
 136         match modulus {
 137             0 => Ok(b),
 138             _ => Err(InvalidHexLength),
 139         }
 140     }
 141 }
 142
 143 #[cfg(test)]
 144 mod tests;