Add STANDARD, URL_SAFE, URL_SAFE_NO_PAD consts

Author: marshallpierce

README.md

@@ -14,20 +14,6 @@ e.g. `decode_engine_slice` decodes into an existing `&mut [u8]` and is pretty fa
 whereas `decode_engine` allocates a new `Vec<u8>` and returns it, which might be more convenient in some cases, but is
 slower (although still fast enough for almost any purpose) at 2.1 GiB/s.
 
-## Example
-
-```rust
-use base64::{encode, decode};
-
-fn main() {
-    let a = b"hello world";
-    let b = "aGVsbG8gd29ybGQ=";
-
-    assert_eq!(encode(a), b);
-    assert_eq!(a, &decode(b).unwrap()[..]);
-}
-```
-
 See the [docs](https://docs.rs/base64) for all the details.
 
 ## FAQ

RELEASE-NOTES.md

@@ -7,6 +7,9 @@
 - `GeneralPurpose` and its config are now `pub use`'d in the `engine` module for convenience.
 - Change a few `from()` functions to be `new()`. `from()` causes confusing compiler errors because of confusion with `From::from`, and is a little misleading because some of those invocations are not very cheap as one would usually expect from a `from` call.
 - `encode*` and `decode*` top level functions are now methods on `Engine`.
+- `DEFAULT_ENGINE` was replaced by `engine::general_purpose::STANDARD`
+- Predefined engine consts `engine::general_purpose::{STANDARD, URL_SAFE, URL_SAFE_NO_PAD}`
+  - These are `pub use`d into `engine` as well
 
 # 0.20.0
 

benches/benchmarks.rs

@@ -3,7 +3,7 @@ extern crate criterion;
 
 use base64::{
     display,
-    engine::{Engine, DEFAULT_ENGINE},
+    engine::{Engine, STANDARD},
     write,
 };
 use criterion::{black_box, Bencher, BenchmarkId, Criterion, Throughput};
@@ -13,22 +13,22 @@ use std::io::{self, Read, Write};
 fn do_decode_bench(b: &mut Bencher, &size: &usize) {
     let mut v: Vec<u8> = Vec::with_capacity(size * 3 / 4);
     fill(&mut v);
-    let encoded = DEFAULT_ENGINE.encode(&v);
+    let encoded = STANDARD.encode(&v);
 
     b.iter(|| {
-        let orig = DEFAULT_ENGINE.decode(&encoded);
+        let orig = STANDARD.decode(&encoded);
         black_box(&orig);
     });
 }
 
 fn do_decode_bench_reuse_buf(b: &mut Bencher, &size: &usize) {
     let mut v: Vec<u8> = Vec::with_capacity(size * 3 / 4);
     fill(&mut v);
-    let encoded = DEFAULT_ENGINE.encode(&v);
+    let encoded = STANDARD.encode(&v);
 
     let mut buf = Vec::new();
     b.iter(|| {
-        DEFAULT_ENGINE.decode_vec(&encoded, &mut buf).unwrap();
+        STANDARD.decode_vec(&encoded, &mut buf).unwrap();
         black_box(&buf);
         buf.clear();
     });
@@ -37,28 +37,28 @@ fn do_decode_bench_reuse_buf(b: &mut Bencher, &size: &usize) {
 fn do_decode_bench_slice(b: &mut Bencher, &size: &usize) {
     let mut v: Vec<u8> = Vec::with_capacity(size * 3 / 4);
     fill(&mut v);
-    let encoded = DEFAULT_ENGINE.encode(&v);
+    let encoded = STANDARD.encode(&v);
 
     let mut buf = Vec::new();
     buf.resize(size, 0);
     b.iter(|| {
-        DEFAULT_ENGINE.decode_slice(&encoded, &mut buf).unwrap();
+        STANDARD.decode_slice(&encoded, &mut buf).unwrap();
         black_box(&buf);
     });
 }
 
 fn do_decode_bench_stream(b: &mut Bencher, &size: &usize) {
     let mut v: Vec<u8> = Vec::with_capacity(size * 3 / 4);
     fill(&mut v);
-    let encoded = DEFAULT_ENGINE.encode(&v);
+    let encoded = STANDARD.encode(&v);
 
     let mut buf = Vec::new();
     buf.resize(size, 0);
     buf.truncate(0);
 
     b.iter(|| {
         let mut cursor = io::Cursor::new(&encoded[..]);
-        let mut decoder = base64::read::DecoderReader::new(&mut cursor, &DEFAULT_ENGINE);
+        let mut decoder = base64::read::DecoderReader::new(&mut cursor, &STANDARD);
         decoder.read_to_end(&mut buf).unwrap();
         buf.clear();
         black_box(&buf);
@@ -69,7 +69,7 @@ fn do_encode_bench(b: &mut Bencher, &size: &usize) {
     let mut v: Vec<u8> = Vec::with_capacity(size);
     fill(&mut v);
     b.iter(|| {
-        let e = DEFAULT_ENGINE.encode(&v);
+        let e = STANDARD.encode(&v);
         black_box(&e);
     });
 }
@@ -78,7 +78,7 @@ fn do_encode_bench_display(b: &mut Bencher, &size: &usize) {
     let mut v: Vec<u8> = Vec::with_capacity(size);
     fill(&mut v);
     b.iter(|| {
-        let e = format!("{}", display::Base64Display::new(&v, &DEFAULT_ENGINE));
+        let e = format!("{}", display::Base64Display::new(&v, &STANDARD));
         black_box(&e);
     });
 }
@@ -88,7 +88,7 @@ fn do_encode_bench_reuse_buf(b: &mut Bencher, &size: &usize) {
     fill(&mut v);
     let mut buf = String::new();
     b.iter(|| {
-        DEFAULT_ENGINE.encode_string(&v, &mut buf);
+        STANDARD.encode_string(&v, &mut buf);
         buf.clear();
     });
 }
@@ -100,7 +100,7 @@ fn do_encode_bench_slice(b: &mut Bencher, &size: &usize) {
     // conservative estimate of encoded size
     buf.resize(v.len() * 2, 0);
     b.iter(|| {
-        DEFAULT_ENGINE.encode_slice(&v, &mut buf);
+        STANDARD.encode_slice(&v, &mut buf);
     });
 }
 
@@ -112,7 +112,7 @@ fn do_encode_bench_stream(b: &mut Bencher, &size: &usize) {
     buf.reserve(size * 2);
     b.iter(|| {
         buf.clear();
-        let mut stream_enc = write::EncoderWriter::new(&mut buf, &DEFAULT_ENGINE);
+        let mut stream_enc = write::EncoderWriter::new(&mut buf, &STANDARD);
         stream_enc.write_all(&v).unwrap();
         stream_enc.flush().unwrap();
     });
@@ -123,7 +123,7 @@ fn do_encode_bench_string_stream(b: &mut Bencher, &size: &usize) {
     fill(&mut v);
 
     b.iter(|| {
-        let mut stream_enc = write::EncoderStringWriter::new(&DEFAULT_ENGINE);
+        let mut stream_enc = write::EncoderStringWriter::new(&STANDARD);
         stream_enc.write_all(&v).unwrap();
         stream_enc.flush().unwrap();
         let _ = stream_enc.into_inner();
@@ -137,7 +137,7 @@ fn do_encode_bench_string_reuse_buf_stream(b: &mut Bencher, &size: &usize) {
     let mut buf = String::new();
     b.iter(|| {
         buf.clear();
-        let mut stream_enc = write::EncoderStringWriter::from_consumer(&mut buf, &DEFAULT_ENGINE);
+        let mut stream_enc = write::EncoderStringWriter::from_consumer(&mut buf, &STANDARD);
         stream_enc.write_all(&v).unwrap();
         stream_enc.flush().unwrap();
         let _ = stream_enc.into_inner();

fuzz/fuzzers/roundtrip.rs

@@ -2,10 +2,10 @@
 #[macro_use] extern crate libfuzzer_sys;
 extern crate base64;
 
-use base64::{Engine as _, engine::DEFAULT_ENGINE};
+use base64::{Engine as _, engine::STANDARD};
 
 fuzz_target!(|data: &[u8]| {
-    let encoded = DEFAULT_ENGINE.encode(data);
-    let decoded = DEFAULT_ENGINE.decode(&encoded).unwrap();
+    let encoded = STANDARD.encode(data);
+    let decoded = STANDARD.decode(&encoded).unwrap();
     assert_eq!(data, decoded.as_slice());
 });

src/decode.rs

@@ -1,6 +1,6 @@
 use crate::engine::Engine;
 #[cfg(any(feature = "alloc", feature = "std", test))]
-use crate::engine::DEFAULT_ENGINE;
+use crate::engine::STANDARD;
 #[cfg(any(feature = "alloc", feature = "std", test))]
 use alloc::vec::Vec;
 use core::fmt;
@@ -58,16 +58,16 @@ impl error::Error for DecodeError {
     }
 }
 
-///Decode base64 using the [default engine](DEFAULT_ENGINE).
+/// Decode base64 using the [`STANDARD` engine](STANDARD).
 ///
 /// See [Engine::decode].
 #[deprecated(since = "0.21.0", note = "Use Engine::decode")]
 #[cfg(any(feature = "alloc", feature = "std", test))]
 pub fn decode<T: AsRef<[u8]>>(input: T) -> Result<Vec<u8>, DecodeError> {
-    DEFAULT_ENGINE.decode(input)
+    STANDARD.decode(input)
 }
 
-///Decode from string reference as octets using the specified [Engine].
+/// Decode from string reference as octets using the specified [Engine].
 ///
 /// See [Engine::decode].
 ///Returns a `Result` containing a `Vec<u8>`.

src/display.rs

@@ -2,10 +2,10 @@
 //!
 //! ```
 //! use base64::display::Base64Display;
-//! use base64::engine::DEFAULT_ENGINE;
+//! use base64::engine::STANDARD;
 //!
 //! let data = vec![0x0, 0x1, 0x2, 0x3];
-//! let wrapper = Base64Display::new(&data, &DEFAULT_ENGINE);
+//! let wrapper = Base64Display::new(&data, &STANDARD);
 //!
 //! assert_eq!("base64: AAECAw==", format!("base64: {}", wrapper));
 //! ```
@@ -59,17 +59,17 @@ mod tests {
         chunked_encode_matches_normal_encode_random, SinkTestHelper,
     };
     use super::*;
-    use crate::engine::DEFAULT_ENGINE;
+    use crate::engine::STANDARD;
 
     #[test]
     fn basic_display() {
         assert_eq!(
             "~$Zm9vYmFy#*",
-            format!("~${}#*", Base64Display::new(b"foobar", &DEFAULT_ENGINE))
+            format!("~${}#*", Base64Display::new(b"foobar", &STANDARD))
         );
         assert_eq!(
             "~$Zm9vYmFyZg==#*",
-            format!("~${}#*", Base64Display::new(b"foobarf", &DEFAULT_ENGINE))
+            format!("~${}#*", Base64Display::new(b"foobarf", &STANDARD))
         );
     }
 

src/encode.rs

@@ -2,18 +2,18 @@
 use alloc::string::String;
 
 #[cfg(any(feature = "alloc", feature = "std", test))]
-use crate::engine::DEFAULT_ENGINE;
+use crate::engine::STANDARD;
 use crate::engine::{Config, Engine};
 use crate::PAD_BYTE;
 
-/// Encode arbitrary octets as base64 using the [default engine](DEFAULT_ENGINE).
+/// Encode arbitrary octets as base64 using the [`STANDARD` engine](STANDARD).
 ///
 /// See [Engine::encode].
 #[allow(unused)]
 #[deprecated(since = "0.21.0", note = "Use Engine::encode")]
 #[cfg(any(feature = "alloc", feature = "std", test))]
 pub fn encode<T: AsRef<[u8]>>(input: T) -> String {
-    DEFAULT_ENGINE.encode(input)
+    STANDARD.encode(input)
 }
 
 ///Encode arbitrary octets as base64 using the provided `Engine` into a new `String`.
@@ -133,10 +133,10 @@ mod tests {
     use super::*;
 
     use crate::{
-        alphabet::{IMAP_MUTF7, STANDARD, URL_SAFE},
+        alphabet,
         engine::{
             general_purpose::{GeneralPurpose, NO_PAD},
-            DEFAULT_ENGINE,
+            STANDARD,
         },
         tests::{assert_encode_sanity, random_config, random_engine},
     };
@@ -146,31 +146,31 @@ mod tests {
     };
     use std::str;
 
-    const URL_SAFE_NO_PAD_ENGINE: GeneralPurpose = GeneralPurpose::new(&URL_SAFE, NO_PAD);
+    const URL_SAFE_NO_PAD_ENGINE: GeneralPurpose = GeneralPurpose::new(&alphabet::URL_SAFE, NO_PAD);
 
     #[test]
     fn encoded_size_correct_standard() {
-        assert_encoded_length(0, 0, &DEFAULT_ENGINE, true);
+        assert_encoded_length(0, 0, &STANDARD, true);
 
-        assert_encoded_length(1, 4, &DEFAULT_ENGINE, true);
-        assert_encoded_length(2, 4, &DEFAULT_ENGINE, true);
-        assert_encoded_length(3, 4, &DEFAULT_ENGINE, true);
+        assert_encoded_length(1, 4, &STANDARD, true);
+        assert_encoded_length(2, 4, &STANDARD, true);
+        assert_encoded_length(3, 4, &STANDARD, true);
 
-        assert_encoded_length(4, 8, &DEFAULT_ENGINE, true);
-        assert_encoded_length(5, 8, &DEFAULT_ENGINE, true);
-        assert_encoded_length(6, 8, &DEFAULT_ENGINE, true);
+        assert_encoded_length(4, 8, &STANDARD, true);
+        assert_encoded_length(5, 8, &STANDARD, true);
+        assert_encoded_length(6, 8, &STANDARD, true);
 
-        assert_encoded_length(7, 12, &DEFAULT_ENGINE, true);
-        assert_encoded_length(8, 12, &DEFAULT_ENGINE, true);
-        assert_encoded_length(9, 12, &DEFAULT_ENGINE, true);
+        assert_encoded_length(7, 12, &STANDARD, true);
+        assert_encoded_length(8, 12, &STANDARD, true);
+        assert_encoded_length(9, 12, &STANDARD, true);
 
-        assert_encoded_length(54, 72, &DEFAULT_ENGINE, true);
+        assert_encoded_length(54, 72, &STANDARD, true);
 
-        assert_encoded_length(55, 76, &DEFAULT_ENGINE, true);
-        assert_encoded_length(56, 76, &DEFAULT_ENGINE, true);
-        assert_encoded_length(57, 76, &DEFAULT_ENGINE, true);
+        assert_encoded_length(55, 76, &STANDARD, true);
+        assert_encoded_length(56, 76, &STANDARD, true);
+        assert_encoded_length(57, 76, &STANDARD, true);
 
-        assert_encoded_length(58, 80, &DEFAULT_ENGINE, true);
+        assert_encoded_length(58, 80, &STANDARD, true);
     }
 
     #[test]
@@ -500,8 +500,8 @@ mod tests {
     #[test]
     fn encode_imap() {
         assert_eq!(
-            &GeneralPurpose::new(&IMAP_MUTF7, NO_PAD).encode(b"\xFB\xFF"),
-            &GeneralPurpose::new(&STANDARD, NO_PAD)
+            &GeneralPurpose::new(&alphabet::IMAP_MUTF7, NO_PAD).encode(b"\xFB\xFF"),
+            &GeneralPurpose::new(&alphabet::STANDARD, NO_PAD)
                 .encode(b"\xFB\xFF")
                 .replace('/', ",")
         );

src/engine/general_purpose/decode.rs

@@ -327,14 +327,14 @@ fn write_u64(output: &mut [u8], value: u64) {
 mod tests {
     use super::*;
 
-    use crate::engine::DEFAULT_ENGINE;
+    use crate::engine::STANDARD;
 
     #[test]
     fn decode_chunk_precise_writes_only_6_bytes() {
         let input = b"Zm9vYmFy"; // "foobar"
         let mut output = [0_u8, 1, 2, 3, 4, 5, 6, 7];
 
-        decode_chunk_precise(&input[..], 0, &DEFAULT_ENGINE.decode_table, &mut output).unwrap();
+        decode_chunk_precise(&input[..], 0, &STANDARD.decode_table, &mut output).unwrap();
         assert_eq!(&vec![b'f', b'o', b'o', b'b', b'a', b'r', 6, 7], &output);
     }
 
@@ -343,7 +343,7 @@ mod tests {
         let input = b"Zm9vYmFy"; // "foobar"
         let mut output = [0_u8, 1, 2, 3, 4, 5, 6, 7];
 
-        decode_chunk(&input[..], 0, &DEFAULT_ENGINE.decode_table, &mut output).unwrap();
+        decode_chunk(&input[..], 0, &STANDARD.decode_table, &mut output).unwrap();
         assert_eq!(&vec![b'f', b'o', b'o', b'b', b'a', b'r', 0, 0], &output);
     }
 }

src/engine/general_purpose/mod.rs

@@ -1,5 +1,6 @@
 //! Provides the [GeneralPurpose] engine and associated config types.
 use crate::{
+    alphabet,
     alphabet::Alphabet,
     engine::{Config, DecodePaddingMode},
     DecodeError,
@@ -324,6 +325,15 @@ impl Config for GeneralPurposeConfig {
     }
 }
 
+/// A [GeneralPurpose] engine using the [crate::alphabet::STANDARD] base64 alphabet and [crate::engine::general_purpose::PAD] config.
+pub const STANDARD: GeneralPurpose = GeneralPurpose::new(&alphabet::STANDARD, PAD);
+
+/// A [GeneralPurpose] engine using the [crate::alphabet::URL_SAFE] base64 alphabet and [crate::engine::general_purpose::PAD] config.
+pub const URL_SAFE: GeneralPurpose = GeneralPurpose::new(&alphabet::URL_SAFE, PAD);
+
+/// A [GeneralPurpose] engine using the [crate::alphabet::URL_SAFE] base64 alphabet and [crate::engine::general_purpose::NO_PAD] config.
+pub const URL_SAFE_NO_PAD: GeneralPurpose = GeneralPurpose::new(&alphabet::URL_SAFE, NO_PAD);
+
 /// Include padding bytes when encoding, and require that they be present when decoding.
 ///
 /// This is the standard per the base64 RFC, but consider using [NO_PAD] instead as padding serves