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
15 /// A trait for converting a value to hexadecimal encoding
17 /// Converts the value of `self` to a hex value, returning the owned
19 fn to_hex(&self) -> ~str;
22 static CHARS: &'static[u8] = bytes!("0123456789abcdef");
24 impl<'a> ToHex for &'a [u8] {
26 * Turn a vector of `u8` bytes into a hexadecimal string.
31 * extern crate serialize;
32 * use serialize::hex::ToHex;
35 * let str = [52,32].to_hex();
36 * println!("{}", str);
40 fn to_hex(&self) -> ~str {
41 let mut v = Vec::with_capacity(self.len() * 2);
42 for &byte in self.iter() {
43 v.push(CHARS[(byte >> 4) as uint]);
44 v.push(CHARS[(byte & 0xf) as uint]);
48 str::raw::from_utf8_owned(v.move_iter().collect())
53 /// A trait for converting hexadecimal encoded values
55 /// Converts the value of `self`, interpreted as hexadecimal encoded data,
56 /// into an owned vector of bytes, returning the vector.
57 fn from_hex(&self) -> Result<~[u8], FromHexError>;
60 /// Errors that can occur when decoding a hex encoded string
61 pub enum FromHexError {
62 /// The input contained a character not part of the hex format
63 InvalidHexCharacter(char, uint),
64 /// The input had an invalid length
68 impl fmt::Show for FromHexError {
69 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
71 InvalidHexCharacter(ch, idx) =>
72 write!(f.buf, "Invalid character '{}' at position {}", ch, idx),
73 InvalidHexLength => write!(f.buf, "Invalid input length"),
78 impl<'a> FromHex for &'a str {
80 * Convert any hexadecimal encoded string (literal, `@`, `&`, or `~`)
81 * to the byte values it encodes.
83 * You can use the `from_utf8_owned` function in `std::str`
84 * to turn a `[u8]` into a string with characters corresponding to those
89 * This converts a string literal to hexadecimal and back.
92 * extern crate serialize;
93 * use serialize::hex::{FromHex, ToHex};
97 * let hello_str = "Hello, World".as_bytes().to_hex();
98 * println!("{}", hello_str);
99 * let bytes = hello_str.from_hex().unwrap();
100 * println!("{:?}", bytes);
101 * let result_str = str::from_utf8_owned(bytes).unwrap();
102 * println!("{}", result_str);
106 fn from_hex(&self) -> Result<~[u8], FromHexError> {
107 // This may be an overestimate if there is any whitespace
108 let mut b = Vec::with_capacity(self.len() / 2);
112 for (idx, byte) in self.bytes().enumerate() {
116 'A'..'F' => buf |= byte - ('A' as u8) + 10,
117 'a'..'f' => buf |= byte - ('a' as u8) + 10,
118 '0'..'9' => buf |= byte - ('0' as u8),
119 ' '|'\r'|'\n'|'\t' => {
123 _ => return Err(InvalidHexCharacter(self.char_at(idx), idx)),
134 0 => Ok(b.move_iter().collect()),
135 _ => Err(InvalidHexLength),
143 use self::test::Bencher;
144 use hex::{FromHex, ToHex};
147 pub fn test_to_hex() {
148 assert_eq!("foobar".as_bytes().to_hex(), ~"666f6f626172");
152 pub fn test_from_hex_okay() {
153 assert_eq!("666f6f626172".from_hex().unwrap(),
154 "foobar".as_bytes().to_owned());
155 assert_eq!("666F6F626172".from_hex().unwrap(),
156 "foobar".as_bytes().to_owned());
160 pub fn test_from_hex_odd_len() {
161 assert!("666".from_hex().is_err());
162 assert!("66 6".from_hex().is_err());
166 pub fn test_from_hex_invalid_char() {
167 assert!("66y6".from_hex().is_err());
171 pub fn test_from_hex_ignores_whitespace() {
172 assert_eq!("666f 6f6\r\n26172 ".from_hex().unwrap(),
173 "foobar".as_bytes().to_owned());
177 pub fn test_to_hex_all_bytes() {
178 for i in range(0, 256) {
179 assert_eq!([i as u8].to_hex(), format!("{:02x}", i as uint));
184 pub fn test_from_hex_all_bytes() {
185 for i in range(0, 256) {
186 assert_eq!(format!("{:02x}", i as uint).from_hex().unwrap(), ~[i as u8]);
187 assert_eq!(format!("{:02X}", i as uint).from_hex().unwrap(), ~[i as u8]);
192 pub fn bench_to_hex(b: &mut Bencher) {
193 let s = "イロハニホヘト チリヌルヲ ワカヨタレソ ツネナラム \
194 ウヰノオクヤマ ケフコエテ アサキユメミシ ヱヒモセスン";
196 s.as_bytes().to_hex();
198 b.bytes = s.len() as u64;
202 pub fn bench_from_hex(b: &mut Bencher) {
203 let s = "イロハニホヘト チリヌルヲ ワカヨタレソ ツネナラム \
204 ウヰノオクヤマ ケフコエテ アサキユメミシ ヱヒモセスン";
205 let sb = s.as_bytes().to_hex();
207 sb.from_hex().unwrap();
209 b.bytes = sb.len() as u64;