src/libserialize/hex.rs

   1 // Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! Hex binary-to-text encoding
  12
  13 pub use self::FromHexError::*;
  14
  15 use std::fmt;
  16 use std::error;
  17
  18 /// A trait for converting a value to hexadecimal encoding
  19 pub trait ToHex {
  20     /// Converts the value of `self` to a hex value, returning the owned
  21     /// string.
  22     fn to_hex(&self) -> String;
  23 }
  24
  25 const CHARS: &'static [u8] = b"0123456789abcdef";
  26
  27 impl ToHex for [u8] {
  28     /// Turn a vector of `u8` bytes into a hexadecimal string.
  29     ///
  30     /// # Examples
  31     ///
  32     /// ```
  33     /// # #![feature(rustc_private)]
  34     /// extern crate serialize;
  35     /// use serialize::hex::ToHex;
  36     ///
  37     /// fn main () {
  38     ///     let str = [52,32].to_hex();
  39     ///     println!("{}", str);
  40     /// }
  41     /// ```
  42     fn to_hex(&self) -> String {
  43         let mut v = Vec::with_capacity(self.len() * 2);
  44         for &byte in self {
  45             v.push(CHARS[(byte >> 4) as usize]);
  46             v.push(CHARS[(byte & 0xf) as usize]);
  47         }
  48
  49         unsafe {
  50             String::from_utf8_unchecked(v)
  51         }
  52     }
  53 }
  54
  55 /// A trait for converting hexadecimal encoded values
  56 pub trait FromHex {
  57     /// Converts the value of `self`, interpreted as hexadecimal encoded data,
  58     /// into an owned vector of bytes, returning the vector.
  59     fn from_hex(&self) -> Result<Vec<u8>, FromHexError>;
  60 }
  61
  62 /// Errors that can occur when decoding a hex encoded string
  63 #[derive(Copy, Clone, Debug)]
  64 pub enum FromHexError {
  65     /// The input contained a character not part of the hex format
  66     InvalidHexCharacter(char, usize),
  67     /// The input had an invalid length
  68     InvalidHexLength,
  69 }
  70
  71 impl fmt::Display for FromHexError {
  72     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  73         match *self {
  74             InvalidHexCharacter(ch, idx) =>
  75                 write!(f, "Invalid character '{}' at position {}", ch, idx),
  76             InvalidHexLength => write!(f, "Invalid input length"),
  77         }
  78     }
  79 }
  80
  81 impl error::Error for FromHexError {
  82     fn description(&self) -> &str {
  83         match *self {
  84             InvalidHexCharacter(_, _) => "invalid character",
  85             InvalidHexLength => "invalid length",
  86         }
  87     }
  88 }
  89
  90
  91 impl FromHex for str {
  92     /// Convert any hexadecimal encoded string (literal, `@`, `&`, or `~`)
  93     /// to the byte values it encodes.
  94     ///
  95     /// You can use the `String::from_utf8` function to turn a
  96     /// `Vec<u8>` into a string with characters corresponding to those values.
  97     ///
  98     /// # Examples
  99     ///
 100     /// This converts a string literal to hexadecimal and back.
 101     ///
 102     /// ```
 103     /// # #![feature(rustc_private)]
 104     /// extern crate serialize;
 105     /// use serialize::hex::{FromHex, ToHex};
 106     ///
 107     /// fn main () {
 108     ///     let hello_str = "Hello, World".as_bytes().to_hex();
 109     ///     println!("{}", hello_str);
 110     ///     let bytes = hello_str.from_hex().unwrap();
 111     ///     println!("{:?}", bytes);
 112     ///     let result_str = String::from_utf8(bytes).unwrap();
 113     ///     println!("{}", result_str);
 114     /// }
 115     /// ```
 116     fn from_hex(&self) -> Result<Vec<u8>, FromHexError> {
 117         // This may be an overestimate if there is any whitespace
 118         let mut b = Vec::with_capacity(self.len() / 2);
 119         let mut modulus = 0;
 120         let mut buf = 0;
 121
 122         for (idx, byte) in self.bytes().enumerate() {
 123             buf <<= 4;
 124
 125             match byte {
 126                 b'A'...b'F' => buf |= byte - b'A' + 10,
 127                 b'a'...b'f' => buf |= byte - b'a' + 10,
 128                 b'0'...b'9' => buf |= byte - b'0',
 129                 b' '|b'\r'|b'\n'|b'\t' => {
 130                     buf >>= 4;
 131                     continue
 132                 }
 133                 _ => return Err(InvalidHexCharacter(self.char_at(idx), idx)),
 134             }
 135
 136             modulus += 1;
 137             if modulus == 2 {
 138                 modulus = 0;
 139                 b.push(buf);
 140             }
 141         }
 142
 143         match modulus {
 144             0 => Ok(b.into_iter().collect()),
 145             _ => Err(InvalidHexLength),
 146         }
 147     }
 148 }
 149
 150 #[cfg(test)]
 151 mod tests {
 152     extern crate test;
 153     use self::test::Bencher;
 154     use hex::{FromHex, ToHex};
 155
 156     #[test]
 157     pub fn test_to_hex() {
 158         assert_eq!("foobar".as_bytes().to_hex(), "666f6f626172");
 159     }
 160
 161     #[test]
 162     pub fn test_from_hex_okay() {
 163         assert_eq!("666f6f626172".from_hex().unwrap(),
 164                    b"foobar");
 165         assert_eq!("666F6F626172".from_hex().unwrap(),
 166                    b"foobar");
 167     }
 168
 169     #[test]
 170     pub fn test_from_hex_odd_len() {
 171         assert!("666".from_hex().is_err());
 172         assert!("66 6".from_hex().is_err());
 173     }
 174
 175     #[test]
 176     pub fn test_from_hex_invalid_char() {
 177         assert!("66y6".from_hex().is_err());
 178     }
 179
 180     #[test]
 181     pub fn test_from_hex_ignores_whitespace() {
 182         assert_eq!("666f 6f6\r\n26172 ".from_hex().unwrap(),
 183                    b"foobar");
 184     }
 185
 186     #[test]
 187     pub fn test_to_hex_all_bytes() {
 188         for i in 0..256 {
 189             assert_eq!([i as u8].to_hex(), format!("{:02x}", i as usize));
 190         }
 191     }
 192
 193     #[test]
 194     pub fn test_from_hex_all_bytes() {
 195         for i in 0..256 {
 196             let ii: &[u8] = &[i as u8];
 197             assert_eq!(format!("{:02x}", i as usize).from_hex()
 198                                                    .unwrap(),
 199                        ii);
 200             assert_eq!(format!("{:02X}", i as usize).from_hex()
 201                                                    .unwrap(),
 202                        ii);
 203         }
 204     }
 205
 206     #[bench]
 207     pub fn bench_to_hex(b: &mut Bencher) {
 208         let s = "イロハニホヘト チリヌルヲ ワカヨタレソ ツネナラム \
 209                  ウヰノオクヤマ ケフコエテ アサキユメミシ ヱヒモセスン";
 210         b.iter(|| {
 211             s.as_bytes().to_hex();
 212         });
 213         b.bytes = s.len() as u64;
 214     }
 215
 216     #[bench]
 217     pub fn bench_from_hex(b: &mut Bencher) {
 218         let s = "イロハニホヘト チリヌルヲ ワカヨタレソ ツネナラム \
 219                  ウヰノオクヤマ ケフコエテ アサキユメミシ ヱヒモセスン";
 220         let sb = s.as_bytes().to_hex();
 221         b.iter(|| {
 222             sb.from_hex().unwrap();
 223         });
 224         b.bytes = sb.len() as u64;
 225     }
 226 }