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.
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.
11 //! Hex binary-to-text encoding
13 pub use self::FromHexError::*;
18 /// A trait for converting a value to hexadecimal encoding
20 /// Converts the value of `self` to a hex value, returning the owned
22 fn to_hex(&self) -> String;
25 const CHARS: &'static [u8] = b"0123456789abcdef";
28 /// Turn a vector of `u8` bytes into a hexadecimal string.
33 /// #![feature(rustc_private)]
35 /// extern crate serialize;
36 /// use serialize::hex::ToHex;
39 /// let str = [52,32].to_hex();
40 /// println!("{}", str);
43 fn to_hex(&self) -> String {
44 let mut v = Vec::with_capacity(self.len() * 2);
46 v.push(CHARS[(byte >> 4) as usize]);
47 v.push(CHARS[(byte & 0xf) as usize]);
51 String::from_utf8_unchecked(v)
56 /// A trait for converting hexadecimal encoded values
58 /// Converts the value of `self`, interpreted as hexadecimal encoded data,
59 /// into an owned vector of bytes, returning the vector.
60 fn from_hex(&self) -> Result<Vec<u8>, FromHexError>;
63 /// Errors that can occur when decoding a hex encoded string
64 #[derive(Copy, Clone, Debug)]
65 pub enum FromHexError {
66 /// The input contained a character not part of the hex format
67 InvalidHexCharacter(char, usize),
68 /// The input had an invalid length
72 impl fmt::Display for FromHexError {
73 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
75 InvalidHexCharacter(ch, idx) =>
76 write!(f, "Invalid character '{}' at position {}", ch, idx),
77 InvalidHexLength => write!(f, "Invalid input length"),
82 impl error::Error for FromHexError {
83 fn description(&self) -> &str {
85 InvalidHexCharacter(_, _) => "invalid character",
86 InvalidHexLength => "invalid length",
92 impl FromHex for str {
93 /// Convert any hexadecimal encoded string (literal, `@`, `&`, or `~`)
94 /// to the byte values it encodes.
96 /// You can use the `String::from_utf8` function to turn a
97 /// `Vec<u8>` into a string with characters corresponding to those values.
101 /// This converts a string literal to hexadecimal and back.
104 /// #![feature(rustc_private)]
106 /// extern crate serialize;
107 /// use serialize::hex::{FromHex, ToHex};
110 /// let hello_str = "Hello, World".as_bytes().to_hex();
111 /// println!("{}", hello_str);
112 /// let bytes = hello_str.from_hex().unwrap();
113 /// println!("{:?}", bytes);
114 /// let result_str = String::from_utf8(bytes).unwrap();
115 /// println!("{}", result_str);
118 fn from_hex(&self) -> Result<Vec<u8>, FromHexError> {
119 // This may be an overestimate if there is any whitespace
120 let mut b = Vec::with_capacity(self.len() / 2);
124 for (idx, byte) in self.bytes().enumerate() {
128 b'A'...b'F' => buf |= byte - b'A' + 10,
129 b'a'...b'f' => buf |= byte - b'a' + 10,
130 b'0'...b'9' => buf |= byte - b'0',
131 b' '|b'\r'|b'\n'|b'\t' => {
135 _ => return Err(InvalidHexCharacter(self.char_at(idx), idx)),
146 0 => Ok(b.into_iter().collect()),
147 _ => Err(InvalidHexLength),
155 use self::test::Bencher;
156 use hex::{FromHex, ToHex};
159 pub fn test_to_hex() {
160 assert_eq!("foobar".as_bytes().to_hex(), "666f6f626172");
164 pub fn test_from_hex_okay() {
165 assert_eq!("666f6f626172".from_hex().unwrap(),
167 assert_eq!("666F6F626172".from_hex().unwrap(),
172 pub fn test_from_hex_odd_len() {
173 assert!("666".from_hex().is_err());
174 assert!("66 6".from_hex().is_err());
178 pub fn test_from_hex_invalid_char() {
179 assert!("66y6".from_hex().is_err());
183 pub fn test_from_hex_ignores_whitespace() {
184 assert_eq!("666f 6f6\r\n26172 ".from_hex().unwrap(),
189 pub fn test_to_hex_all_bytes() {
191 assert_eq!([i as u8].to_hex(), format!("{:02x}", i as usize));
196 pub fn test_from_hex_all_bytes() {
198 let ii: &[u8] = &[i as u8];
199 assert_eq!(format!("{:02x}", i as usize).from_hex()
202 assert_eq!(format!("{:02X}", i as usize).from_hex()
209 pub fn bench_to_hex(b: &mut Bencher) {
210 let s = "イロハニホヘト チリヌルヲ ワカヨタレソ ツネナラム \
211 ウヰノオクヤマ ケフコエテ アサキユメミシ ヱヒモセスン";
213 s.as_bytes().to_hex();
215 b.bytes = s.len() as u64;
219 pub fn bench_from_hex(b: &mut Bencher) {
220 let s = "イロハニホヘト チリヌルヲ ワカヨタレソ ツネナラム \
221 ウヰノオクヤマ ケフコエテ アサキユメミシ ヱヒモセスン";
222 let sb = s.as_bytes().to_hex();
224 sb.from_hex().unwrap();
226 b.bytes = sb.len() as u64;