44440e5c18
fmt::Show is for debugging, and can and should be implemented for
all public types. This trait is used with `{:?}` syntax. There still
exists #[derive(Show)].
fmt::String is for types that faithfully be represented as a String.
Because of this, there is no way to derive fmt::String, all
implementations must be purposeful. It is used by the default format
syntax, `{}`.
This will break most instances of `{}`, since that now requires the type
to impl fmt::String. In most cases, replacing `{}` with `{:?}` is the
correct fix. Types that were being printed specifically for users should
receive a fmt::String implementation to fix this.
Part of #20013
[breaking-change]
428 lines
14 KiB
Rust
428 lines
14 KiB
Rust
// Copyright 2012-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.
|
|
//
|
|
// ignore-lexer-test FIXME #15679
|
|
|
|
//! Base64 binary-to-text encoding
|
|
|
|
pub use self::FromBase64Error::*;
|
|
pub use self::CharacterSet::*;
|
|
|
|
use std::fmt;
|
|
use std::error;
|
|
|
|
/// Available encoding character sets
|
|
#[derive(Copy)]
|
|
pub enum CharacterSet {
|
|
/// The standard character set (uses `+` and `/`)
|
|
Standard,
|
|
/// The URL safe character set (uses `-` and `_`)
|
|
UrlSafe
|
|
}
|
|
|
|
/// Available newline types
|
|
#[derive(Copy)]
|
|
pub enum Newline {
|
|
/// A linefeed (i.e. Unix-style newline)
|
|
LF,
|
|
/// A carriage return and a linefeed (i.e. Windows-style newline)
|
|
CRLF
|
|
}
|
|
|
|
/// Contains configuration parameters for `to_base64`.
|
|
#[derive(Copy)]
|
|
pub struct Config {
|
|
/// Character set to use
|
|
pub char_set: CharacterSet,
|
|
/// Newline to use
|
|
pub newline: Newline,
|
|
/// True to pad output with `=` characters
|
|
pub pad: bool,
|
|
/// `Some(len)` to wrap lines at `len`, `None` to disable line wrapping
|
|
pub line_length: Option<uint>
|
|
}
|
|
|
|
/// Configuration for RFC 4648 standard base64 encoding
|
|
pub static STANDARD: Config =
|
|
Config {char_set: Standard, newline: Newline::CRLF, pad: true, line_length: None};
|
|
|
|
/// Configuration for RFC 4648 base64url encoding
|
|
pub static URL_SAFE: Config =
|
|
Config {char_set: UrlSafe, newline: Newline::CRLF, pad: false, line_length: None};
|
|
|
|
/// Configuration for RFC 2045 MIME base64 encoding
|
|
pub static MIME: Config =
|
|
Config {char_set: Standard, newline: Newline::CRLF, pad: true, line_length: Some(76)};
|
|
|
|
static STANDARD_CHARS: &'static[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ\
|
|
abcdefghijklmnopqrstuvwxyz\
|
|
0123456789+/";
|
|
|
|
static URLSAFE_CHARS: &'static[u8] = b"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) -> String;
|
|
}
|
|
|
|
impl ToBase64 for [u8] {
|
|
/// Turn a vector of `u8` bytes into a base64 string.
|
|
///
|
|
/// # Example
|
|
///
|
|
/// ```rust
|
|
/// extern crate 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) -> String {
|
|
let bytes = match config.char_set {
|
|
Standard => STANDARD_CHARS,
|
|
UrlSafe => URLSAFE_CHARS
|
|
};
|
|
|
|
// In general, this Vec only needs (4/3) * self.len() memory, but
|
|
// addition is faster than multiplication and division.
|
|
let mut v = Vec::with_capacity(self.len() + self.len());
|
|
let mut i = 0;
|
|
let mut cur_length = 0;
|
|
let len = self.len();
|
|
let mod_len = len % 3;
|
|
let cond_len = len - mod_len;
|
|
let newline = match config.newline {
|
|
Newline::LF => b"\n",
|
|
Newline::CRLF => b"\r\n"
|
|
};
|
|
while i < cond_len {
|
|
let (first, second, third) = (self[i], self[i + 1], self[i + 2]);
|
|
if let Some(line_length) = config.line_length {
|
|
if cur_length >= line_length {
|
|
v.push_all(newline);
|
|
cur_length = 0;
|
|
}
|
|
}
|
|
|
|
let n = (first as u32) << 16 |
|
|
(second as u32) << 8 |
|
|
(third as u32);
|
|
|
|
// This 24-bit number gets separated into four 6-bit numbers.
|
|
v.push(bytes[((n >> 18) & 63) as uint]);
|
|
v.push(bytes[((n >> 12) & 63) as uint]);
|
|
v.push(bytes[((n >> 6 ) & 63) as uint]);
|
|
v.push(bytes[(n & 63) as uint]);
|
|
|
|
cur_length += 4;
|
|
i += 3;
|
|
}
|
|
|
|
if mod_len != 0 {
|
|
if let Some(line_length) = config.line_length {
|
|
if cur_length >= line_length {
|
|
v.push_all(newline);
|
|
}
|
|
}
|
|
}
|
|
|
|
// Heh, would be cool if we knew this was exhaustive
|
|
// (the dream of bounded integer types)
|
|
match mod_len {
|
|
0 => (),
|
|
1 => {
|
|
let n = (self[i] as u32) << 16;
|
|
v.push(bytes[((n >> 18) & 63) as uint]);
|
|
v.push(bytes[((n >> 12) & 63) as uint]);
|
|
if config.pad {
|
|
v.push(b'=');
|
|
v.push(b'=');
|
|
}
|
|
}
|
|
2 => {
|
|
let n = (self[i] as u32) << 16 |
|
|
(self[i + 1u] as u32) << 8;
|
|
v.push(bytes[((n >> 18) & 63) as uint]);
|
|
v.push(bytes[((n >> 12) & 63) as uint]);
|
|
v.push(bytes[((n >> 6 ) & 63) as uint]);
|
|
if config.pad {
|
|
v.push(b'=');
|
|
}
|
|
}
|
|
_ => panic!("Algebra is broken, please alert the math police")
|
|
}
|
|
|
|
unsafe { String::from_utf8_unchecked(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<Vec<u8>, FromBase64Error>;
|
|
}
|
|
|
|
/// Errors that can occur when decoding a base64 encoded string
|
|
#[derive(Copy)]
|
|
pub enum FromBase64Error {
|
|
/// The input contained a character not part of the base64 format
|
|
InvalidBase64Byte(u8, uint),
|
|
/// The input had an invalid length
|
|
InvalidBase64Length,
|
|
}
|
|
|
|
impl fmt::Show for FromBase64Error {
|
|
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
|
|
match *self {
|
|
InvalidBase64Byte(ch, idx) =>
|
|
write!(f, "Invalid character '{}' at position {}", ch, idx),
|
|
InvalidBase64Length => write!(f, "Invalid length"),
|
|
}
|
|
}
|
|
}
|
|
|
|
impl error::Error for FromBase64Error {
|
|
fn description(&self) -> &str {
|
|
match *self {
|
|
InvalidBase64Byte(_, _) => "invalid character",
|
|
InvalidBase64Length => "invalid length",
|
|
}
|
|
}
|
|
|
|
fn detail(&self) -> Option<String> {
|
|
Some(format!("{:?}", self))
|
|
}
|
|
}
|
|
|
|
impl FromBase64 for str {
|
|
/// Convert any base64 encoded string (literal, `@`, `&`, or `~`)
|
|
/// to the byte values it encodes.
|
|
///
|
|
/// You can use the `String::from_utf8` function to turn a `Vec<u8>` into a
|
|
/// string with characters corresponding to those values.
|
|
///
|
|
/// # Example
|
|
///
|
|
/// This converts a string literal to base64 and back.
|
|
///
|
|
/// ```rust
|
|
/// extern crate serialize;
|
|
/// use serialize::base64::{ToBase64, FromBase64, STANDARD};
|
|
///
|
|
/// fn main () {
|
|
/// let hello_str = b"Hello, World".to_base64(STANDARD);
|
|
/// println!("base64 output: {}", hello_str);
|
|
/// let res = hello_str.as_slice().from_base64();
|
|
/// if res.is_ok() {
|
|
/// let opt_bytes = String::from_utf8(res.unwrap());
|
|
/// if opt_bytes.is_ok() {
|
|
/// println!("decoded from base64: {}", opt_bytes.unwrap());
|
|
/// }
|
|
/// }
|
|
/// }
|
|
/// ```
|
|
#[inline]
|
|
fn from_base64(&self) -> Result<Vec<u8>, FromBase64Error> {
|
|
self.as_bytes().from_base64()
|
|
}
|
|
}
|
|
|
|
impl FromBase64 for [u8] {
|
|
fn from_base64(&self) -> Result<Vec<u8>, FromBase64Error> {
|
|
let mut r = Vec::with_capacity(self.len());
|
|
let mut buf: u32 = 0;
|
|
let mut modulus = 0i;
|
|
|
|
let mut it = self.iter().enumerate();
|
|
for (idx, &byte) in it {
|
|
let val = byte as u32;
|
|
|
|
match byte {
|
|
b'A'...b'Z' => buf |= val - 0x41,
|
|
b'a'...b'z' => buf |= val - 0x47,
|
|
b'0'...b'9' => buf |= val + 0x04,
|
|
b'+' | b'-' => buf |= 0x3E,
|
|
b'/' | b'_' => buf |= 0x3F,
|
|
b'\r' | b'\n' => continue,
|
|
b'=' => break,
|
|
_ => return Err(InvalidBase64Byte(self[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 {
|
|
b'=' | b'\r' | b'\n' => continue,
|
|
_ => return Err(InvalidBase64Byte(self[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 tests {
|
|
extern crate test;
|
|
use self::test::Bencher;
|
|
use base64::{Config, Newline, 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_crlf_line_break() {
|
|
assert!(![0u8; 1000].to_base64(Config {line_length: None, ..STANDARD})
|
|
.contains("\r\n"));
|
|
assert_eq!(b"foobar".to_base64(Config {line_length: Some(4),
|
|
..STANDARD}),
|
|
"Zm9v\r\nYmFy");
|
|
}
|
|
|
|
#[test]
|
|
fn test_to_base64_lf_line_break() {
|
|
assert!(![0u8; 1000].to_base64(Config {line_length: None,
|
|
newline: Newline::LF,
|
|
..STANDARD})
|
|
.as_slice()
|
|
.contains("\n"));
|
|
assert_eq!(b"foobar".to_base64(Config {line_length: Some(4),
|
|
newline: Newline::LF,
|
|
..STANDARD}),
|
|
"Zm9v\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(), b"");
|
|
assert_eq!("Zg==".from_base64().unwrap(), b"f");
|
|
assert_eq!("Zm8=".from_base64().unwrap(), b"fo");
|
|
assert_eq!("Zm9v".from_base64().unwrap(), b"foo");
|
|
assert_eq!("Zm9vYg==".from_base64().unwrap(), b"foob");
|
|
assert_eq!("Zm9vYmE=".from_base64().unwrap(), b"fooba");
|
|
assert_eq!("Zm9vYmFy".from_base64().unwrap(), b"foobar");
|
|
}
|
|
|
|
#[test]
|
|
fn test_from_base64_bytes() {
|
|
assert_eq!(b"Zm9vYmFy".from_base64().unwrap(), b"foobar");
|
|
}
|
|
|
|
#[test]
|
|
fn test_from_base64_newlines() {
|
|
assert_eq!("Zm9v\r\nYmFy".from_base64().unwrap(),
|
|
b"foobar");
|
|
assert_eq!("Zm9vYg==\r\n".from_base64().unwrap(),
|
|
b"foob");
|
|
assert_eq!("Zm9v\nYmFy".from_base64().unwrap(),
|
|
b"foobar");
|
|
assert_eq!("Zm9vYg==\n".from_base64().unwrap(),
|
|
b"foob");
|
|
}
|
|
|
|
#[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::{thread_rng, random, Rng};
|
|
|
|
for _ in range(0u, 1000) {
|
|
let times = thread_rng().gen_range(1u, 100);
|
|
let v = thread_rng().gen_iter::<u8>().take(times).collect::<Vec<_>>();
|
|
assert_eq!(v.to_base64(STANDARD)
|
|
.from_base64()
|
|
.unwrap(),
|
|
v);
|
|
}
|
|
}
|
|
|
|
#[bench]
|
|
pub fn bench_to_base64(b: &mut Bencher) {
|
|
let s = "イロハニホヘト チリヌルヲ ワカヨタレソ ツネナラム \
|
|
ウヰノオクヤマ ケフコエテ アサキユメミシ ヱヒモセスン";
|
|
b.iter(|| {
|
|
s.as_bytes().to_base64(STANDARD);
|
|
});
|
|
b.bytes = s.len() as u64;
|
|
}
|
|
|
|
#[bench]
|
|
pub fn bench_from_base64(b: &mut Bencher) {
|
|
let s = "イロハニホヘト チリヌルヲ ワカヨタレソ ツネナラム \
|
|
ウヰノオクヤマ ケフコエテ アサキユメミシ ヱヒモセスン";
|
|
let sb = s.as_bytes().to_base64(STANDARD);
|
|
b.iter(|| {
|
|
sb.from_base64().unwrap();
|
|
});
|
|
b.bytes = sb.len() as u64;
|
|
}
|
|
|
|
}
|