Merge pull request #248 from marshallpierce/mp/alphabet-docs

Improve docs for using custom alphabets

Cargo.toml

@@ -25,6 +25,7 @@ structopt = "0.3.26"
 # test fixtures for engine tests
 rstest = "0.12.0"
 rstest_reuse = "0.3.0"
+lazy_static = "1.4.0"
 
 [features]
 default = ["std"]

src/alphabet.rs

@@ -12,13 +12,44 @@ const ALPHABET_SIZE: usize = 64;
 /// Common alphabets are provided as constants, and custom alphabets
 /// can be made via `from_str` or the `TryFrom<str>` implementation.
 ///
+/// # Examples
+///
+/// Building and using a custom Alphabet:
+///
 /// ```
 /// let custom = base64::alphabet::Alphabet::new("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/").unwrap();
 ///
 /// let engine = base64::engine::GeneralPurpose::new(
 ///     &custom,
 ///     base64::engine::general_purpose::PAD);
 /// ```
+///
+/// Building a const:
+///
+/// ```
+/// use base64::alphabet::Alphabet;
+///
+/// static CUSTOM: Alphabet = {
+///     // Result::unwrap() isn't const yet, but panic!() is OK
+///     match Alphabet::new("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/") {
+///         Ok(x) => x,
+///         Err(_) => panic!("creation of alphabet failed"),
+///     }
+/// };
+/// ```
+///
+/// Building a lazy_static:
+///
+/// ```
+/// use base64::{
+///     alphabet::Alphabet,
+///     engine::{general_purpose::GeneralPurpose, GeneralPurposeConfig},
+/// };
+///
+/// lazy_static::lazy_static! {
+///     static ref CUSTOM: Alphabet = Alphabet::new("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/").unwrap();
+/// }
+/// ```
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct Alphabet {
     pub(crate) symbols: [u8; ALPHABET_SIZE],

src/engine/tests.rs

@@ -623,7 +623,7 @@ fn decode_padding_before_final_non_padding_char_error_invalid_byte<E: EngineWrap
     let mut rng = seeded_rng();
 
     // the different amounts of proper padding, w/ offset from end for the last non-padding char
-    let suffixes = vec![("/w==", 2), ("iYu=", 1), ("zzzz", 0)];
+    let suffixes = [("/w==", 2), ("iYu=", 1), ("zzzz", 0)];
 
     let prefix_quads_range = distributions::Uniform::from(0..=256);
 
@@ -869,7 +869,7 @@ fn decode_pad_mode_requires_canonical_accepts_canonical<E: EngineWrapper>(engine
 fn decode_pad_mode_requires_canonical_rejects_non_canonical<E: EngineWrapper>(engine_wrapper: E) {
     let engine = E::standard_with_pad_mode(true, DecodePaddingMode::RequireCanonical);
 
-    let suffixes = vec!["/w", "/w=", "iYU"];
+    let suffixes = ["/w", "/w=", "iYU"];
     for num_prefix_quads in 0..256 {
         for &suffix in suffixes.iter() {
             let mut encoded = "AAAA".repeat(num_prefix_quads);
@@ -896,7 +896,7 @@ fn decode_pad_mode_requires_no_padding_accepts_no_padding<E: EngineWrapper>(engi
 fn decode_pad_mode_requires_no_padding_rejects_any_padding<E: EngineWrapper>(engine_wrapper: E) {
     let engine = E::standard_with_pad_mode(true, DecodePaddingMode::RequireNone);
 
-    let suffixes = vec!["/w=", "/w==", "iYU="];
+    let suffixes = ["/w=", "/w==", "iYU="];
     for num_prefix_quads in 0..256 {
         for &suffix in suffixes.iter() {
             let mut encoded = "AAAA".repeat(num_prefix_quads);

src/write/encoder_tests.rs

@@ -358,7 +358,7 @@ fn retrying_writes_that_error_with_interrupted_works() {
                     Ok(_) => break,
                     Err(e) => match e.kind() {
                         io::ErrorKind::Interrupted => continue,
-                        _ => Err(e).unwrap(), // bail
+                        _ => panic!("{:?}", e), // bail
                     },
                 }
             }