1 // Copyright 2012-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 // ignore-lexer-test FIXME #15679
13 //! Base64 binary-to-text encoding
15 pub use self::FromBase64Error::*;
16 pub use self::CharacterSet::*;
21 /// Available encoding character sets
23 pub enum CharacterSet {
24 /// The standard character set (uses `+` and `/`)
26 /// The URL safe character set (uses `-` and `_`)
30 /// Available newline types
33 /// A linefeed (i.e. Unix-style newline)
35 /// A carriage return and a linefeed (i.e. Windows-style newline)
39 /// Contains configuration parameters for `to_base64`.
42 /// Character set to use
43 pub char_set: CharacterSet,
46 /// True to pad output with `=` characters
48 /// `Some(len)` to wrap lines at `len`, `None` to disable line wrapping
49 pub line_length: Option<uint>
52 /// Configuration for RFC 4648 standard base64 encoding
53 pub static STANDARD: Config =
54 Config {char_set: Standard, newline: Newline::CRLF, pad: true, line_length: None};
56 /// Configuration for RFC 4648 base64url encoding
57 pub static URL_SAFE: Config =
58 Config {char_set: UrlSafe, newline: Newline::CRLF, pad: false, line_length: None};
60 /// Configuration for RFC 2045 MIME base64 encoding
61 pub static MIME: Config =
62 Config {char_set: Standard, newline: Newline::CRLF, pad: true, line_length: Some(76)};
64 static STANDARD_CHARS: &'static[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ\
65 abcdefghijklmnopqrstuvwxyz\
68 static URLSAFE_CHARS: &'static[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ\
69 abcdefghijklmnopqrstuvwxyz\
72 /// A trait for converting a value to base64 encoding.
73 pub trait ToBase64 for Sized? {
74 /// Converts the value of `self` to a base64 value following the specified
75 /// format configuration, returning the owned string.
76 fn to_base64(&self, config: Config) -> String;
79 impl ToBase64 for [u8] {
80 /// Turn a vector of `u8` bytes into a base64 string.
85 /// extern crate serialize;
86 /// use serialize::base64::{ToBase64, STANDARD};
89 /// let str = [52,32].to_base64(STANDARD);
90 /// println!("base 64 output: {}", str);
93 fn to_base64(&self, config: Config) -> String {
94 let bytes = match config.char_set {
95 Standard => STANDARD_CHARS,
96 UrlSafe => URLSAFE_CHARS
99 // In general, this Vec only needs (4/3) * self.len() memory, but
100 // addition is faster than multiplication and division.
101 let mut v = Vec::with_capacity(self.len() + self.len());
103 let mut cur_length = 0;
104 let len = self.len();
105 let mod_len = len % 3;
106 let cond_len = len - mod_len;
107 let newline = match config.newline {
108 Newline::LF => b"\n",
109 Newline::CRLF => b"\r\n"
112 let (first, second, third) = (self[i], self[i + 1], self[i + 2]);
113 if let Some(line_length) = config.line_length {
114 if cur_length >= line_length {
120 let n = (first as u32) << 16 |
121 (second as u32) << 8 |
124 // This 24-bit number gets separated into four 6-bit numbers.
125 v.push(bytes[((n >> 18) & 63) as uint]);
126 v.push(bytes[((n >> 12) & 63) as uint]);
127 v.push(bytes[((n >> 6 ) & 63) as uint]);
128 v.push(bytes[(n & 63) as uint]);
135 if let Some(line_length) = config.line_length {
136 if cur_length >= line_length {
142 // Heh, would be cool if we knew this was exhaustive
143 // (the dream of bounded integer types)
147 let n = (self[i] as u32) << 16;
148 v.push(bytes[((n >> 18) & 63) as uint]);
149 v.push(bytes[((n >> 12) & 63) as uint]);
156 let n = (self[i] as u32) << 16 |
157 (self[i + 1u] as u32) << 8;
158 v.push(bytes[((n >> 18) & 63) as uint]);
159 v.push(bytes[((n >> 12) & 63) as uint]);
160 v.push(bytes[((n >> 6 ) & 63) as uint]);
165 _ => panic!("Algebra is broken, please alert the math police")
168 unsafe { String::from_utf8_unchecked(v) }
172 /// A trait for converting from base64 encoded values.
173 pub trait FromBase64 for Sized? {
174 /// Converts the value of `self`, interpreted as base64 encoded data, into
175 /// an owned vector of bytes, returning the vector.
176 fn from_base64(&self) -> Result<Vec<u8>, FromBase64Error>;
179 /// Errors that can occur when decoding a base64 encoded string
181 pub enum FromBase64Error {
182 /// The input contained a character not part of the base64 format
183 InvalidBase64Byte(u8, uint),
184 /// The input had an invalid length
188 impl fmt::Show for FromBase64Error {
189 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
191 InvalidBase64Byte(ch, idx) =>
192 write!(f, "Invalid character '{}' at position {}", ch, idx),
193 InvalidBase64Length => write!(f, "Invalid length"),
198 impl error::Error for FromBase64Error {
199 fn description(&self) -> &str {
201 InvalidBase64Byte(_, _) => "invalid character",
202 InvalidBase64Length => "invalid length",
206 fn detail(&self) -> Option<String> {
207 Some(self.to_string())
211 impl FromBase64 for str {
212 /// Convert any base64 encoded string (literal, `@`, `&`, or `~`)
213 /// to the byte values it encodes.
215 /// You can use the `String::from_utf8` function to turn a `Vec<u8>` into a
216 /// string with characters corresponding to those values.
220 /// This converts a string literal to base64 and back.
223 /// extern crate serialize;
224 /// use serialize::base64::{ToBase64, FromBase64, STANDARD};
227 /// let hello_str = b"Hello, World".to_base64(STANDARD);
228 /// println!("base64 output: {}", hello_str);
229 /// let res = hello_str.as_slice().from_base64();
231 /// let opt_bytes = String::from_utf8(res.unwrap());
232 /// if opt_bytes.is_ok() {
233 /// println!("decoded from base64: {}", opt_bytes.unwrap());
239 fn from_base64(&self) -> Result<Vec<u8>, FromBase64Error> {
240 self.as_bytes().from_base64()
244 impl FromBase64 for [u8] {
245 fn from_base64(&self) -> Result<Vec<u8>, FromBase64Error> {
246 let mut r = Vec::with_capacity(self.len());
247 let mut buf: u32 = 0;
248 let mut modulus = 0i;
250 let mut it = self.iter().enumerate();
251 for (idx, &byte) in it {
252 let val = byte as u32;
255 b'A'...b'Z' => buf |= val - 0x41,
256 b'a'...b'z' => buf |= val - 0x47,
257 b'0'...b'9' => buf |= val + 0x04,
258 b'+' | b'-' => buf |= 0x3E,
259 b'/' | b'_' => buf |= 0x3F,
260 b'\r' | b'\n' => continue,
262 _ => return Err(InvalidBase64Byte(self[idx], idx)),
269 r.push((buf >> 22) as u8);
270 r.push((buf >> 14) as u8);
271 r.push((buf >> 6 ) as u8);
275 for (idx, &byte) in it {
277 b'=' | b'\r' | b'\n' => continue,
278 _ => return Err(InvalidBase64Byte(self[idx], idx)),
284 r.push((buf >> 10) as u8);
287 r.push((buf >> 16) as u8);
288 r.push((buf >> 8 ) as u8);
291 _ => return Err(InvalidBase64Length),
301 use self::test::Bencher;
302 use base64::{Config, Newline, FromBase64, ToBase64, STANDARD, URL_SAFE};
305 fn test_to_base64_basic() {
306 assert_eq!("".as_bytes().to_base64(STANDARD), "");
307 assert_eq!("f".as_bytes().to_base64(STANDARD), "Zg==");
308 assert_eq!("fo".as_bytes().to_base64(STANDARD), "Zm8=");
309 assert_eq!("foo".as_bytes().to_base64(STANDARD), "Zm9v");
310 assert_eq!("foob".as_bytes().to_base64(STANDARD), "Zm9vYg==");
311 assert_eq!("fooba".as_bytes().to_base64(STANDARD), "Zm9vYmE=");
312 assert_eq!("foobar".as_bytes().to_base64(STANDARD), "Zm9vYmFy");
316 fn test_to_base64_crlf_line_break() {
317 assert!(![0u8; 1000].to_base64(Config {line_length: None, ..STANDARD})
319 assert_eq!(b"foobar".to_base64(Config {line_length: Some(4),
325 fn test_to_base64_lf_line_break() {
326 assert!(![0u8; 1000].to_base64(Config {line_length: None,
327 newline: Newline::LF,
331 assert_eq!(b"foobar".to_base64(Config {line_length: Some(4),
332 newline: Newline::LF,
338 fn test_to_base64_padding() {
339 assert_eq!("f".as_bytes().to_base64(Config {pad: false, ..STANDARD}), "Zg");
340 assert_eq!("fo".as_bytes().to_base64(Config {pad: false, ..STANDARD}), "Zm8");
344 fn test_to_base64_url_safe() {
345 assert_eq!([251, 255].to_base64(URL_SAFE), "-_8");
346 assert_eq!([251, 255].to_base64(STANDARD), "+/8=");
350 fn test_from_base64_basic() {
351 assert_eq!("".from_base64().unwrap(), b"");
352 assert_eq!("Zg==".from_base64().unwrap(), b"f");
353 assert_eq!("Zm8=".from_base64().unwrap(), b"fo");
354 assert_eq!("Zm9v".from_base64().unwrap(), b"foo");
355 assert_eq!("Zm9vYg==".from_base64().unwrap(), b"foob");
356 assert_eq!("Zm9vYmE=".from_base64().unwrap(), b"fooba");
357 assert_eq!("Zm9vYmFy".from_base64().unwrap(), b"foobar");
361 fn test_from_base64_bytes() {
362 assert_eq!(b"Zm9vYmFy".from_base64().unwrap(), b"foobar");
366 fn test_from_base64_newlines() {
367 assert_eq!("Zm9v\r\nYmFy".from_base64().unwrap(),
369 assert_eq!("Zm9vYg==\r\n".from_base64().unwrap(),
371 assert_eq!("Zm9v\nYmFy".from_base64().unwrap(),
373 assert_eq!("Zm9vYg==\n".from_base64().unwrap(),
378 fn test_from_base64_urlsafe() {
379 assert_eq!("-_8".from_base64().unwrap(), "+/8=".from_base64().unwrap());
383 fn test_from_base64_invalid_char() {
384 assert!("Zm$=".from_base64().is_err());
385 assert!("Zg==$".from_base64().is_err());
389 fn test_from_base64_invalid_padding() {
390 assert!("Z===".from_base64().is_err());
394 fn test_base64_random() {
395 use std::rand::{thread_rng, random, Rng};
397 for _ in range(0u, 1000) {
398 let times = thread_rng().gen_range(1u, 100);
399 let v = Vec::from_fn(times, |_| random::<u8>());
400 assert_eq!(v.to_base64(STANDARD)
408 pub fn bench_to_base64(b: &mut Bencher) {
409 let s = "イロハニホヘト チリヌルヲ ワカヨタレソ ツネナラム \
410 ウヰノオクヤマ ケフコエテ アサキユメミシ ヱヒモセスン";
412 s.as_bytes().to_base64(STANDARD);
414 b.bytes = s.len() as u64;
418 pub fn bench_from_base64(b: &mut Bencher) {
419 let s = "イロハニホヘト チリヌルヲ ワカヨタレソ ツネナラム \
420 ウヰノオクヤマ ケフコエテ アサキユメミシ ヱヒモセスン";
421 let sb = s.as_bytes().to_base64(STANDARD);
423 sb.from_base64().unwrap();
425 b.bytes = sb.len() as u64;