Move base64 and hex from libextra to libserialize

3 files changed, 581 insertions, 0 deletions

diff --git a/src/libserialize/base64.rs b/src/libserialize/base64.rs
new file mode 100644
index 00000000000..c22eefdb330
--- /dev/null
+++ b/src/libserialize/base64.rs
@@ -0,0 +1,367 @@
+// Copyright 2012-2013 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+//! Base64 binary-to-text encoding
+use std::str;
+
+/// Available encoding character sets
+pub enum CharacterSet {
+    /// The standard character set (uses `+` and `/`)
+    Standard,
+    /// The URL safe character set (uses `-` and `_`)
+    UrlSafe
+}
+
+/// Contains configuration parameters for `to_base64`.
+pub struct Config {
+    /// Character set to use
+    char_set: CharacterSet,
+    /// True to pad output with `=` characters
+    pad: bool,
+    /// `Some(len)` to wrap lines at `len`, `None` to disable line wrapping
+    line_length: Option<uint>
+}
+
+/// Configuration for RFC 4648 standard base64 encoding
+pub static STANDARD: Config =
+    Config {char_set: Standard, pad: true, line_length: None};
+
+/// Configuration for RFC 4648 base64url encoding
+pub static URL_SAFE: Config =
+    Config {char_set: UrlSafe, pad: false, line_length: None};
+
+/// Configuration for RFC 2045 MIME base64 encoding
+pub static MIME: Config =
+    Config {char_set: Standard, pad: true, line_length: Some(76)};
+
+static STANDARD_CHARS: &'static[u8] = bytes!("ABCDEFGHIJKLMNOPQRSTUVWXYZ",
+                                             "abcdefghijklmnopqrstuvwxyz",
+                                             "0123456789+/");
+
+static URLSAFE_CHARS: &'static[u8] = bytes!("ABCDEFGHIJKLMNOPQRSTUVWXYZ",
+                                            "abcdefghijklmnopqrstuvwxyz",
+                                            "0123456789-_");
+
+/// A trait for converting a value to base64 encoding.
+pub trait ToBase64 {
+    /// Converts the value of `self` to a base64 value following the specified
+    /// format configuration, returning the owned string.
+    fn to_base64(&self, config: Config) -> ~str;
+}
+
+impl<'a> ToBase64 for &'a [u8] {
+    /**
+     * Turn a vector of `u8` bytes into a base64 string.
+     *
+     * # Example
+     *
+     * ```rust
+     * extern mod serialize;
+     * use serialize::base64::{ToBase64, STANDARD};
+     *
+     * fn main () {
+     *     let str = [52,32].to_base64(STANDARD);
+     *     println!("base 64 output: {}", str);
+     * }
+     * ```
+     */
+    fn to_base64(&self, config: Config) -> ~str {
+        let bytes = match config.char_set {
+            Standard => STANDARD_CHARS,
+            UrlSafe => URLSAFE_CHARS
+        };
+
+        let mut v: ~[u8] = ~[];
+        let mut i = 0;
+        let mut cur_length = 0;
+        let len = self.len();
+        while i < len - (len % 3) {
+            match config.line_length {
+                Some(line_length) =>
+                    if cur_length >= line_length {
+                        v.push('\r' as u8);
+                        v.push('\n' as u8);
+                        cur_length = 0;
+                    },
+                None => ()
+            }
+
+            let n = (self[i] as u32) << 16 |
+                    (self[i + 1] as u32) << 8 |
+                    (self[i + 2] as u32);
+
+            // This 24-bit number gets separated into four 6-bit numbers.
+            v.push(bytes[(n >> 18) & 63]);
+            v.push(bytes[(n >> 12) & 63]);
+            v.push(bytes[(n >> 6 ) & 63]);
+            v.push(bytes[n & 63]);
+
+            cur_length += 4;
+            i += 3;
+        }
+
+        if len % 3 != 0 {
+            match config.line_length {
+                Some(line_length) =>
+                    if cur_length >= line_length {
+                        v.push('\r' as u8);
+                        v.push('\n' as u8);
+                    },
+                None => ()
+            }
+        }
+
+        // Heh, would be cool if we knew this was exhaustive
+        // (the dream of bounded integer types)
+        match len % 3 {
+            0 => (),
+            1 => {
+                let n = (self[i] as u32) << 16;
+                v.push(bytes[(n >> 18) & 63]);
+                v.push(bytes[(n >> 12) & 63]);
+                if config.pad {
+                    v.push('=' as u8);
+                    v.push('=' as u8);
+                }
+            }
+            2 => {
+                let n = (self[i] as u32) << 16 |
+                    (self[i + 1u] as u32) << 8;
+                v.push(bytes[(n >> 18) & 63]);
+                v.push(bytes[(n >> 12) & 63]);
+                v.push(bytes[(n >> 6 ) & 63]);
+                if config.pad {
+                    v.push('=' as u8);
+                }
+            }
+            _ => fail!("Algebra is broken, please alert the math police")
+        }
+
+        unsafe {
+            str::raw::from_utf8_owned(v)
+        }
+    }
+}
+
+/// A trait for converting from base64 encoded values.
+pub trait FromBase64 {
+    /// Converts the value of `self`, interpreted as base64 encoded data, into
+    /// an owned vector of bytes, returning the vector.
+    fn from_base64(&self) -> Result<~[u8], FromBase64Error>;
+}
+
+/// Errors that can occur when decoding a base64 encoded string
+pub enum FromBase64Error {
+    /// The input contained a character not part of the base64 format
+    InvalidBase64Character(char, uint),
+    /// The input had an invalid length
+    InvalidBase64Length,
+}
+
+impl ToStr for FromBase64Error {
+    fn to_str(&self) -> ~str {
+        match *self {
+            InvalidBase64Character(ch, idx) =>
+                format!("Invalid character '{}' at position {}", ch, idx),
+            InvalidBase64Length => ~"Invalid length",
+        }
+    }
+}
+
+impl<'a> FromBase64 for &'a str {
+    /**
+     * Convert any base64 encoded string (literal, `@`, `&`, or `~`)
+     * to the byte values it encodes.
+     *
+     * You can use the `from_utf8_owned` function in `std::str`
+     * to turn a `[u8]` into a string with characters corresponding to those
+     * values.
+     *
+     * # Example
+     *
+     * This converts a string literal to base64 and back.
+     *
+     * ```rust
+     * extern mod serialize;
+     * use serialize::base64::{ToBase64, FromBase64, STANDARD};
+     * use std::str;
+     *
+     * fn main () {
+     *     let hello_str = bytes!("Hello, World").to_base64(STANDARD);
+     *     println!("base64 output: {}", hello_str);
+     *     let res = hello_str.from_base64();
+     *     if res.is_ok() {
+     *       let optBytes = str::from_utf8_owned(res.unwrap());
+     *       if optBytes.is_some() {
+     *         println!("decoded from base64: {}", optBytes.unwrap());
+     *       }
+     *     }
+     * }
+     * ```
+     */
+    fn from_base64(&self) -> Result<~[u8], FromBase64Error> {
+        let mut r = ~[];
+        let mut buf: u32 = 0;
+        let mut modulus = 0;
+
+        let mut it = self.bytes().enumerate();
+        for (idx, byte) in it {
+            let val = byte as u32;
+
+            match byte as char {
+                'A'..'Z' => buf |= val - 0x41,
+                'a'..'z' => buf |= val - 0x47,
+                '0'..'9' => buf |= val + 0x04,
+                '+'|'-' => buf |= 0x3E,
+                '/'|'_' => buf |= 0x3F,
+                '\r'|'\n' => continue,
+                '=' => break,
+                _ => return Err(InvalidBase64Character(self.char_at(idx), idx)),
+            }
+
+            buf <<= 6;
+            modulus += 1;
+            if modulus == 4 {
+                modulus = 0;
+                r.push((buf >> 22) as u8);
+                r.push((buf >> 14) as u8);
+                r.push((buf >> 6 ) as u8);
+            }
+        }
+
+        for (idx, byte) in it {
+            match byte as char {
+                '='|'\r'|'\n' => continue,
+                _ => return Err(InvalidBase64Character(self.char_at(idx), idx)),
+            }
+        }
+
+        match modulus {
+            2 => {
+                r.push((buf >> 10) as u8);
+            }
+            3 => {
+                r.push((buf >> 16) as u8);
+                r.push((buf >> 8 ) as u8);
+            }
+            0 => (),
+            _ => return Err(InvalidBase64Length),
+        }
+
+        Ok(r)
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use extra::test::BenchHarness;
+    use base64::{Config, FromBase64, ToBase64, STANDARD, URL_SAFE};
+
+    #[test]
+    fn test_to_base64_basic() {
+        assert_eq!("".as_bytes().to_base64(STANDARD), ~"");
+        assert_eq!("f".as_bytes().to_base64(STANDARD), ~"Zg==");
+        assert_eq!("fo".as_bytes().to_base64(STANDARD), ~"Zm8=");
+        assert_eq!("foo".as_bytes().to_base64(STANDARD), ~"Zm9v");
+        assert_eq!("foob".as_bytes().to_base64(STANDARD), ~"Zm9vYg==");
+        assert_eq!("fooba".as_bytes().to_base64(STANDARD), ~"Zm9vYmE=");
+        assert_eq!("foobar".as_bytes().to_base64(STANDARD), ~"Zm9vYmFy");
+    }
+
+    #[test]
+    fn test_to_base64_line_break() {
+        assert!(![0u8, ..1000].to_base64(Config {line_length: None, ..STANDARD})
+                .contains("\r\n"));
+        assert_eq!("foobar".as_bytes().to_base64(Config {line_length: Some(4),
+                                                         ..STANDARD}),
+                   ~"Zm9v\r\nYmFy");
+    }
+
+    #[test]
+    fn test_to_base64_padding() {
+        assert_eq!("f".as_bytes().to_base64(Config {pad: false, ..STANDARD}), ~"Zg");
+        assert_eq!("fo".as_bytes().to_base64(Config {pad: false, ..STANDARD}), ~"Zm8");
+    }
+
+    #[test]
+    fn test_to_base64_url_safe() {
+        assert_eq!([251, 255].to_base64(URL_SAFE), ~"-_8");
+        assert_eq!([251, 255].to_base64(STANDARD), ~"+/8=");
+    }
+
+    #[test]
+    fn test_from_base64_basic() {
+        assert_eq!("".from_base64().unwrap(), "".as_bytes().to_owned());
+        assert_eq!("Zg==".from_base64().unwrap(), "f".as_bytes().to_owned());
+        assert_eq!("Zm8=".from_base64().unwrap(), "fo".as_bytes().to_owned());
+        assert_eq!("Zm9v".from_base64().unwrap(), "foo".as_bytes().to_owned());
+        assert_eq!("Zm9vYg==".from_base64().unwrap(), "foob".as_bytes().to_owned());
+        assert_eq!("Zm9vYmE=".from_base64().unwrap(), "fooba".as_bytes().to_owned());
+        assert_eq!("Zm9vYmFy".from_base64().unwrap(), "foobar".as_bytes().to_owned());
+    }
+
+    #[test]
+    fn test_from_base64_newlines() {
+        assert_eq!("Zm9v\r\nYmFy".from_base64().unwrap(),
+                   "foobar".as_bytes().to_owned());
+        assert_eq!("Zm9vYg==\r\n".from_base64().unwrap(),
+                   "foob".as_bytes().to_owned());
+    }
+
+    #[test]
+    fn test_from_base64_urlsafe() {
+        assert_eq!("-_8".from_base64().unwrap(), "+/8=".from_base64().unwrap());
+    }
+
+    #[test]
+    fn test_from_base64_invalid_char() {
+        assert!("Zm$=".from_base64().is_err())
+        assert!("Zg==$".from_base64().is_err());
+    }
+
+    #[test]
+    fn test_from_base64_invalid_padding() {
+        assert!("Z===".from_base64().is_err());
+    }
+
+    #[test]
+    fn test_base64_random() {
+        use std::rand::{task_rng, random, Rng};
+        use std::vec;
+
+        for _ in range(0, 1000) {
+            let times = task_rng().gen_range(1u, 100);
+            let v = vec::from_fn(times, |_| random::<u8>());
+            assert_eq!(v.to_base64(STANDARD).from_base64().unwrap(), v);
+        }
+    }
+
+    #[bench]
+    pub fn bench_to_base64(bh: & mut BenchHarness) {
+        let s = "イロハニホヘト チリヌルヲ ワカヨタレソ ツネナラム \
+                 ウヰノオクヤマ ケフコエテ アサキユメミシ ヱヒモセスン";
+        bh.iter(|| {
+            s.as_bytes().to_base64(STANDARD);
+        });
+        bh.bytes = s.len() as u64;
+    }
+
+    #[bench]
+    pub fn bench_from_base64(bh: & mut BenchHarness) {
+        let s = "イロハニホヘト チリヌルヲ ワカヨタレソ ツネナラム \
+                 ウヰノオクヤマ ケフコエテ アサキユメミシ ヱヒモセスン";
+        let b = s.as_bytes().to_base64(STANDARD);
+        bh.iter(|| {
+            b.from_base64().unwrap();
+        });
+        bh.bytes = b.len() as u64;
+    }
+
+}
diff --git a/src/libserialize/hex.rs b/src/libserialize/hex.rs
new file mode 100644
index 00000000000..409bf4af809
--- /dev/null
+++ b/src/libserialize/hex.rs
@@ -0,0 +1,210 @@
+// Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+//! Hex binary-to-text encoding
+use std::str;
+use std::vec;
+
+/// A trait for converting a value to hexadecimal encoding
+pub trait ToHex {
+    /// Converts the value of `self` to a hex value, returning the owned
+    /// string.
+    fn to_hex(&self) -> ~str;
+}
+
+static CHARS: &'static[u8] = bytes!("0123456789abcdef");
+
+impl<'a> ToHex for &'a [u8] {
+    /**
+     * Turn a vector of `u8` bytes into a hexadecimal string.
+     *
+     * # Example
+     *
+     * ```rust
+     * extern mod serialize;
+     * use serialize::hex::ToHex;
+     *
+     * fn main () {
+     *     let str = [52,32].to_hex();
+     *     println!("{}", str);
+     * }
+     * ```
+     */
+    fn to_hex(&self) -> ~str {
+        let mut v = vec::with_capacity(self.len() * 2);
+        for &byte in self.iter() {
+            v.push(CHARS[byte >> 4]);
+            v.push(CHARS[byte & 0xf]);
+        }
+
+        unsafe {
+            str::raw::from_utf8_owned(v)
+        }
+    }
+}
+
+/// A trait for converting hexadecimal encoded values
+pub trait FromHex {
+    /// Converts the value of `self`, interpreted as hexadecimal encoded data,
+    /// into an owned vector of bytes, returning the vector.
+    fn from_hex(&self) -> Result<~[u8], FromHexError>;
+}
+
+/// Errors that can occur when decoding a hex encoded string
+pub enum FromHexError {
+    /// The input contained a character not part of the hex format
+    InvalidHexCharacter(char, uint),
+    /// The input had an invalid length
+    InvalidHexLength,
+}
+
+impl ToStr for FromHexError {
+    fn to_str(&self) -> ~str {
+        match *self {
+            InvalidHexCharacter(ch, idx) =>
+                format!("Invalid character '{}' at position {}", ch, idx),
+            InvalidHexLength => ~"Invalid input length",
+        }
+    }
+}
+
+impl<'a> FromHex for &'a str {
+    /**
+     * Convert any hexadecimal encoded string (literal, `@`, `&`, or `~`)
+     * to the byte values it encodes.
+     *
+     * You can use the `from_utf8_owned` function in `std::str`
+     * to turn a `[u8]` into a string with characters corresponding to those
+     * values.
+     *
+     * # Example
+     *
+     * This converts a string literal to hexadecimal and back.
+     *
+     * ```rust
+     * extern mod serialize;
+     * use serialize::hex::{FromHex, ToHex};
+     * use std::str;
+     *
+     * fn main () {
+     *     let hello_str = "Hello, World".as_bytes().to_hex();
+     *     println!("{}", hello_str);
+     *     let bytes = hello_str.from_hex().unwrap();
+     *     println!("{:?}", bytes);
+     *     let result_str = str::from_utf8_owned(bytes).unwrap();
+     *     println!("{}", result_str);
+     * }
+     * ```
+     */
+    fn from_hex(&self) -> Result<~[u8], FromHexError> {
+        // This may be an overestimate if there is any whitespace
+        let mut b = vec::with_capacity(self.len() / 2);
+        let mut modulus = 0;
+        let mut buf = 0u8;
+
+        for (idx, byte) in self.bytes().enumerate() {
+            buf <<= 4;
+
+            match byte as char {
+                'A'..'F' => buf |= byte - ('A' as u8) + 10,
+                'a'..'f' => buf |= byte - ('a' as u8) + 10,
+                '0'..'9' => buf |= byte - ('0' as u8),
+                ' '|'\r'|'\n'|'\t' => {
+                    buf >>= 4;
+                    continue
+                }
+                _ => return Err(InvalidHexCharacter(self.char_at(idx), idx)),
+            }
+
+            modulus += 1;
+            if modulus == 2 {
+                modulus = 0;
+                b.push(buf);
+            }
+        }
+
+        match modulus {
+            0 => Ok(b),
+            _ => Err(InvalidHexLength),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use extra::test::BenchHarness;
+    use hex::{FromHex, ToHex};
+
+    #[test]
+    pub fn test_to_hex() {
+        assert_eq!("foobar".as_bytes().to_hex(), ~"666f6f626172");
+    }
+
+    #[test]
+    pub fn test_from_hex_okay() {
+        assert_eq!("666f6f626172".from_hex().unwrap(),
+                   "foobar".as_bytes().to_owned());
+        assert_eq!("666F6F626172".from_hex().unwrap(),
+                   "foobar".as_bytes().to_owned());
+    }
+
+    #[test]
+    pub fn test_from_hex_odd_len() {
+        assert!("666".from_hex().is_err());
+        assert!("66 6".from_hex().is_err());
+    }
+
+    #[test]
+    pub fn test_from_hex_invalid_char() {
+        assert!("66y6".from_hex().is_err());
+    }
+
+    #[test]
+    pub fn test_from_hex_ignores_whitespace() {
+        assert_eq!("666f 6f6\r\n26172 ".from_hex().unwrap(),
+                   "foobar".as_bytes().to_owned());
+    }
+
+    #[test]
+    pub fn test_to_hex_all_bytes() {
+        for i in range(0, 256) {
+            assert_eq!([i as u8].to_hex(), format!("{:02x}", i as uint));
+        }
+    }
+
+    #[test]
+    pub fn test_from_hex_all_bytes() {
+        for i in range(0, 256) {
+            assert_eq!(format!("{:02x}", i as uint).from_hex().unwrap(), ~[i as u8]);
+            assert_eq!(format!("{:02X}", i as uint).from_hex().unwrap(), ~[i as u8]);
+        }
+    }
+
+    #[bench]
+    pub fn bench_to_hex(bh: & mut BenchHarness) {
+        let s = "イロハニホヘト チリヌルヲ ワカヨタレソ ツネナラム \
+                 ウヰノオクヤマ ケフコエテ アサキユメミシ ヱヒモセスン";
+        bh.iter(|| {
+            s.as_bytes().to_hex();
+        });
+        bh.bytes = s.len() as u64;
+    }
+
+    #[bench]
+    pub fn bench_from_hex(bh: & mut BenchHarness) {
+        let s = "イロハニホヘト チリヌルヲ ワカヨタレソ ツネナラム \
+                 ウヰノオクヤマ ケフコエテ アサキユメミシ ヱヒモセスン";
+        let b = s.as_bytes().to_hex();
+        bh.iter(|| {
+            b.from_hex().unwrap();
+        });
+        bh.bytes = b.len() as u64;
+    }
+}
diff --git a/src/libserialize/lib.rs b/src/libserialize/lib.rs
index 5f473b25369..3b71b2237b1 100644
--- a/src/libserialize/lib.rs
+++ b/src/libserialize/lib.rs
@@ -30,4 +30,8 @@ pub use self::serialize::{Decoder, Encoder, Decodable, Encodable,
     DecoderHelpers, EncoderHelpers};
 
 mod serialize;
+
+pub mod base64;
 pub mod ebml;
+pub mod hex;
+