1 //! Hex binary-to-text encoding
3 pub use self::FromHexError::*;
8 /// A trait for converting a value to hexadecimal encoding
10 /// Converts the value of `self` to a hex value, returning the owned
12 fn to_hex(&self) -> String;
15 const CHARS: &[u8] = b"0123456789abcdef";
18 /// Turn a vector of `u8` bytes into a hexadecimal string.
23 /// #![feature(rustc_private)]
25 /// extern crate serialize;
26 /// use serialize::hex::ToHex;
29 /// let str = [52,32].to_hex();
30 /// println!("{}", str);
33 fn to_hex(&self) -> String {
34 let mut v = Vec::with_capacity(self.len() * 2);
36 v.push(CHARS[(byte >> 4) as usize]);
37 v.push(CHARS[(byte & 0xf) as usize]);
40 unsafe { String::from_utf8_unchecked(v) }
44 /// A trait for converting hexadecimal encoded values
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>;
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
60 impl fmt::Display for FromHexError {
61 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
63 InvalidHexCharacter(ch, idx) => {
64 write!(f, "Invalid character '{}' at position {}", ch, idx)
66 InvalidHexLength => write!(f, "Invalid input length"),
71 impl error::Error for FromHexError {}
73 impl FromHex for str {
74 /// Converts any hexadecimal encoded string (literal, `@`, `&`, or `~`)
75 /// to the byte values it encodes.
77 /// You can use the `String::from_utf8` function to turn a
78 /// `Vec<u8>` into a string with characters corresponding to those values.
82 /// This converts a string literal to hexadecimal and back.
85 /// #![feature(rustc_private)]
87 /// extern crate serialize;
88 /// use serialize::hex::{FromHex, ToHex};
91 /// let hello_str = "Hello, World".as_bytes().to_hex();
92 /// println!("{}", hello_str);
93 /// let bytes = hello_str.from_hex().unwrap();
94 /// println!("{:?}", bytes);
95 /// let result_str = String::from_utf8(bytes).unwrap();
96 /// println!("{}", result_str);
99 fn from_hex(&self) -> Result<Vec<u8>, FromHexError> {
100 // This may be an overestimate if there is any whitespace
101 let mut b = Vec::with_capacity(self.len() / 2);
105 for (idx, byte) in self.bytes().enumerate() {
109 b'A'..=b'F' => buf |= byte - b'A' + 10,
110 b'a'..=b'f' => buf |= byte - b'a' + 10,
111 b'0'..=b'9' => buf |= byte - b'0',
112 b' ' | b'\r' | b'\n' | b'\t' => {
117 let ch = self[idx..].chars().next().unwrap();
118 return Err(InvalidHexCharacter(ch, idx));
131 _ => Err(InvalidHexLength),