vendor/base64-0.21.7/src/encode.rs - toolchain/rustc - Git at Google

 #[cfg(any(feature = "alloc", test))]
 use alloc::string::String;
 use core::fmt;
 #[cfg(any(feature = "std", test))]
 use std::error;

 #[cfg(any(feature = "alloc", test))]
 use crate::engine::general_purpose::STANDARD;
 use crate::engine::{Config, Engine};
 use crate::PAD_BYTE;

 /// 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", test))]
 pub fn encode<T: AsRef<[u8]>>(input: T) -> String {
     STANDARD.encode(input)
 }

 ///Encode arbitrary octets as base64 using the provided `Engine` into a new `String`.
 ///
 /// See [Engine::encode].
 #[allow(unused)]
 #[deprecated(since = "0.21.0", note = "Use Engine::encode")]
 #[cfg(any(feature = "alloc", test))]
 pub fn encode_engine<E: Engine, T: AsRef<[u8]>>(input: T, engine: &E) -> String {
     engine.encode(input)
 }

 ///Encode arbitrary octets as base64 into a supplied `String`.
 ///
 /// See [Engine::encode_string].
 #[allow(unused)]
 #[deprecated(since = "0.21.0", note = "Use Engine::encode_string")]
 #[cfg(any(feature = "alloc", test))]
 pub fn encode_engine_string<E: Engine, T: AsRef<[u8]>>(
     input: T,
     output_buf: &mut String,
     engine: &E,
 ) {
     engine.encode_string(input, output_buf)
 }

 /// Encode arbitrary octets as base64 into a supplied slice.
 ///
 /// See [Engine::encode_slice].
 #[allow(unused)]
 #[deprecated(since = "0.21.0", note = "Use Engine::encode_slice")]
 pub fn encode_engine_slice<E: Engine, T: AsRef<[u8]>>(
     input: T,
     output_buf: &mut [u8],
     engine: &E,
 ) -> Result<usize, EncodeSliceError> {
     engine.encode_slice(input, output_buf)
 }

 /// B64-encode and pad (if configured).
 ///
 /// This helper exists to avoid recalculating encoded_size, which is relatively expensive on short
 /// inputs.
 ///
 /// `encoded_size` is the encoded size calculated for `input`.
 ///
 /// `output` must be of size `encoded_size`.
 ///
 /// All bytes in `output` will be written to since it is exactly the size of the output.
 pub(crate) fn encode_with_padding<E: Engine + ?Sized>(
     input: &[u8],
     output: &mut [u8],
     engine: &E,
     expected_encoded_size: usize,
 ) {
     debug_assert_eq!(expected_encoded_size, output.len());

     let b64_bytes_written = engine.internal_encode(input, output);

     let padding_bytes = if engine.config().encode_padding() {
         add_padding(b64_bytes_written, &mut output[b64_bytes_written..])
     } else {
         0
     };

     let encoded_bytes = b64_bytes_written
         .checked_add(padding_bytes)
         .expect("usize overflow when calculating b64 length");

     debug_assert_eq!(expected_encoded_size, encoded_bytes);
 }

 /// Calculate the base64 encoded length for a given input length, optionally including any
 /// appropriate padding bytes.
 ///
 /// Returns `None` if the encoded length can't be represented in `usize`. This will happen for
 /// input lengths in approximately the top quarter of the range of `usize`.
 pub const fn encoded_len(bytes_len: usize, padding: bool) -> Option<usize> {
     let rem = bytes_len % 3;

     let complete_input_chunks = bytes_len / 3;
     // `?` is disallowed in const, and `let Some(_) = _ else` requires 1.65.0, whereas this
     // messier syntax works on 1.48
     let complete_chunk_output =
         if let Some(complete_chunk_output) = complete_input_chunks.checked_mul(4) {
             complete_chunk_output
         } else {
             return None;
         };

     if rem > 0 {
         if padding {
             complete_chunk_output.checked_add(4)
         } else {
             let encoded_rem = match rem {
                 1 => 2,
                 // only other possible remainder is 2
                 // can't use a separate _ => unreachable!() in const fns in ancient rust versions
                 _ => 3,
             };
             complete_chunk_output.checked_add(encoded_rem)
         }
     } else {
         Some(complete_chunk_output)
     }
 }

 /// Write padding characters.
 /// `unpadded_output_len` is the size of the unpadded but base64 encoded data.
 /// `output` is the slice where padding should be written, of length at least 2.
 ///
 /// Returns the number of padding bytes written.
 pub(crate) fn add_padding(unpadded_output_len: usize, output: &mut [u8]) -> usize {
     let pad_bytes = (4 - (unpadded_output_len % 4)) % 4;
     // for just a couple bytes, this has better performance than using
     // .fill(), or iterating over mutable refs, which call memset()
     #[allow(clippy::needless_range_loop)]
     for i in 0..pad_bytes {
         output[i] = PAD_BYTE;
     }

     pad_bytes
 }

 /// Errors that can occur while encoding into a slice.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum EncodeSliceError {
     /// The provided slice is too small.
     OutputSliceTooSmall,
 }

 impl fmt::Display for EncodeSliceError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
             Self::OutputSliceTooSmall => write!(f, "Output slice too small"),
         }
     }
 }

 #[cfg(any(feature = "std", test))]
 impl error::Error for EncodeSliceError {}

 #[cfg(test)]
 mod tests {
     use super::*;

     use crate::{
         alphabet,
         engine::general_purpose::{GeneralPurpose, NO_PAD, STANDARD},
         tests::{assert_encode_sanity, random_config, random_engine},
     };
     use rand::{
         distributions::{Distribution, Uniform},
         Rng, SeedableRng,
     };
     use std::str;

     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, &STANDARD, 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, &STANDARD, true);
         assert_encoded_length(5, 8, &STANDARD, true);
         assert_encoded_length(6, 8, &STANDARD, 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, &STANDARD, 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, &STANDARD, true);
     }

     #[test]
     fn encoded_size_correct_no_pad() {
         assert_encoded_length(0, 0, &URL_SAFE_NO_PAD_ENGINE, false);

         assert_encoded_length(1, 2, &URL_SAFE_NO_PAD_ENGINE, false);
         assert_encoded_length(2, 3, &URL_SAFE_NO_PAD_ENGINE, false);
         assert_encoded_length(3, 4, &URL_SAFE_NO_PAD_ENGINE, false);

         assert_encoded_length(4, 6, &URL_SAFE_NO_PAD_ENGINE, false);
         assert_encoded_length(5, 7, &URL_SAFE_NO_PAD_ENGINE, false);
         assert_encoded_length(6, 8, &URL_SAFE_NO_PAD_ENGINE, false);

         assert_encoded_length(7, 10, &URL_SAFE_NO_PAD_ENGINE, false);
         assert_encoded_length(8, 11, &URL_SAFE_NO_PAD_ENGINE, false);
         assert_encoded_length(9, 12, &URL_SAFE_NO_PAD_ENGINE, false);

         assert_encoded_length(54, 72, &URL_SAFE_NO_PAD_ENGINE, false);

         assert_encoded_length(55, 74, &URL_SAFE_NO_PAD_ENGINE, false);
         assert_encoded_length(56, 75, &URL_SAFE_NO_PAD_ENGINE, false);
         assert_encoded_length(57, 76, &URL_SAFE_NO_PAD_ENGINE, false);

         assert_encoded_length(58, 78, &URL_SAFE_NO_PAD_ENGINE, false);
     }

     #[test]
     fn encoded_size_overflow() {
         assert_eq!(None, encoded_len(usize::MAX, true));
     }

     #[test]
     fn encode_engine_string_into_nonempty_buffer_doesnt_clobber_prefix() {
         let mut orig_data = Vec::new();
         let mut prefix = String::new();
         let mut encoded_data_no_prefix = String::new();
         let mut encoded_data_with_prefix = String::new();
         let mut decoded = Vec::new();

         let prefix_len_range = Uniform::new(0, 1000);
         let input_len_range = Uniform::new(0, 1000);

         let mut rng = rand::rngs::SmallRng::from_entropy();

         for _ in 0..10_000 {
             orig_data.clear();
             prefix.clear();
             encoded_data_no_prefix.clear();
             encoded_data_with_prefix.clear();
             decoded.clear();

             let input_len = input_len_range.sample(&mut rng);

             for _ in 0..input_len {
                 orig_data.push(rng.gen());
             }

             let prefix_len = prefix_len_range.sample(&mut rng);
             for _ in 0..prefix_len {
                 // getting convenient random single-byte printable chars that aren't base64 is
                 // annoying
                 prefix.push('#');
             }
             encoded_data_with_prefix.push_str(&prefix);

             let engine = random_engine(&mut rng);
             engine.encode_string(&orig_data, &mut encoded_data_no_prefix);
             engine.encode_string(&orig_data, &mut encoded_data_with_prefix);

             assert_eq!(
                 encoded_data_no_prefix.len() + prefix_len,
                 encoded_data_with_prefix.len()
             );
             assert_encode_sanity(
                 &encoded_data_no_prefix,
                 engine.config().encode_padding(),
                 input_len,
             );
             assert_encode_sanity(
                 &encoded_data_with_prefix[prefix_len..],
                 engine.config().encode_padding(),
                 input_len,
             );

             // append plain encode onto prefix
             prefix.push_str(&encoded_data_no_prefix);

             assert_eq!(prefix, encoded_data_with_prefix);

             engine
                 .decode_vec(&encoded_data_no_prefix, &mut decoded)
                 .unwrap();
             assert_eq!(orig_data, decoded);
         }
     }

     #[test]
     fn encode_engine_slice_into_nonempty_buffer_doesnt_clobber_suffix() {
         let mut orig_data = Vec::new();
         let mut encoded_data = Vec::new();
         let mut encoded_data_original_state = Vec::new();
         let mut decoded = Vec::new();

         let input_len_range = Uniform::new(0, 1000);

         let mut rng = rand::rngs::SmallRng::from_entropy();

         for _ in 0..10_000 {
             orig_data.clear();
             encoded_data.clear();
             encoded_data_original_state.clear();
             decoded.clear();

             let input_len = input_len_range.sample(&mut rng);

             for _ in 0..input_len {
                 orig_data.push(rng.gen());
             }

             // plenty of existing garbage in the encoded buffer
             for _ in 0..10 * input_len {
                 encoded_data.push(rng.gen());
             }

             encoded_data_original_state.extend_from_slice(&encoded_data);

             let engine = random_engine(&mut rng);

             let encoded_size = encoded_len(input_len, engine.config().encode_padding()).unwrap();

             assert_eq!(
                 encoded_size,
                 engine.encode_slice(&orig_data, &mut encoded_data).unwrap()
             );

             assert_encode_sanity(
                 str::from_utf8(&encoded_data[0..encoded_size]).unwrap(),
                 engine.config().encode_padding(),
                 input_len,
             );

             assert_eq!(
                 &encoded_data[encoded_size..],
                 &encoded_data_original_state[encoded_size..]
             );

             engine
                 .decode_vec(&encoded_data[0..encoded_size], &mut decoded)
                 .unwrap();
             assert_eq!(orig_data, decoded);
         }
     }

     #[test]
     fn encode_to_slice_random_valid_utf8() {
         let mut input = Vec::new();
         let mut output = Vec::new();

         let input_len_range = Uniform::new(0, 1000);

         let mut rng = rand::rngs::SmallRng::from_entropy();

         for _ in 0..10_000 {
             input.clear();
             output.clear();

             let input_len = input_len_range.sample(&mut rng);

             for _ in 0..input_len {
                 input.push(rng.gen());
             }

             let config = random_config(&mut rng);
             let engine = random_engine(&mut rng);

             // fill up the output buffer with garbage
             let encoded_size = encoded_len(input_len, config.encode_padding()).unwrap();
             for _ in 0..encoded_size {
                 output.push(rng.gen());
             }

             let orig_output_buf = output.clone();

             let bytes_written = engine.internal_encode(&input, &mut output);

             // make sure the part beyond bytes_written is the same garbage it was before
             assert_eq!(orig_output_buf[bytes_written..], output[bytes_written..]);

             // make sure the encoded bytes are UTF-8
             let _ = str::from_utf8(&output[0..bytes_written]).unwrap();
         }
     }

     #[test]
     fn encode_with_padding_random_valid_utf8() {
         let mut input = Vec::new();
         let mut output = Vec::new();

         let input_len_range = Uniform::new(0, 1000);

         let mut rng = rand::rngs::SmallRng::from_entropy();

         for _ in 0..10_000 {
             input.clear();
             output.clear();

             let input_len = input_len_range.sample(&mut rng);

             for _ in 0..input_len {
                 input.push(rng.gen());
             }

             let engine = random_engine(&mut rng);

             // fill up the output buffer with garbage
             let encoded_size = encoded_len(input_len, engine.config().encode_padding()).unwrap();
             for _ in 0..encoded_size + 1000 {
                 output.push(rng.gen());
             }

             let orig_output_buf = output.clone();

             encode_with_padding(&input, &mut output[0..encoded_size], &engine, encoded_size);

             // make sure the part beyond b64 is the same garbage it was before
             assert_eq!(orig_output_buf[encoded_size..], output[encoded_size..]);

             // make sure the encoded bytes are UTF-8
             let _ = str::from_utf8(&output[0..encoded_size]).unwrap();
         }
     }

     #[test]
     fn add_padding_random_valid_utf8() {
         let mut output = Vec::new();

         let mut rng = rand::rngs::SmallRng::from_entropy();

         // cover our bases for length % 4
         for unpadded_output_len in 0..20 {
             output.clear();

             // fill output with random
             for _ in 0..100 {
                 output.push(rng.gen());
             }

             let orig_output_buf = output.clone();

             let bytes_written = add_padding(unpadded_output_len, &mut output);

             // make sure the part beyond bytes_written is the same garbage it was before
             assert_eq!(orig_output_buf[bytes_written..], output[bytes_written..]);

             // make sure the encoded bytes are UTF-8
             let _ = str::from_utf8(&output[0..bytes_written]).unwrap();
         }
     }

     fn assert_encoded_length<E: Engine>(
         input_len: usize,
         enc_len: usize,
         engine: &E,
         padded: bool,
     ) {
         assert_eq!(enc_len, encoded_len(input_len, padded).unwrap());

         let mut bytes: Vec<u8> = Vec::new();
         let mut rng = rand::rngs::SmallRng::from_entropy();

         for _ in 0..input_len {
             bytes.push(rng.gen());
         }

         let encoded = engine.encode(&bytes);
         assert_encode_sanity(&encoded, padded, input_len);

         assert_eq!(enc_len, encoded.len());
     }

     #[test]
     fn encode_imap() {
         assert_eq!(
             &GeneralPurpose::new(&alphabet::IMAP_MUTF7, NO_PAD).encode(b"\xFB\xFF"),
             &GeneralPurpose::new(&alphabet::STANDARD, NO_PAD)
                 .encode(b"\xFB\xFF")
                 .replace('/', ",")
         );
     }
 }
	#[cfg(any(feature = "alloc", test))]
	use alloc::string::String;
	use core::fmt;
	#[cfg(any(feature = "std", test))]
	use std::error;

	#[cfg(any(feature = "alloc", test))]
	use crate::engine::general_purpose::STANDARD;
	use crate::engine::{Config, Engine};
	use crate::PAD_BYTE;

	/// 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", test))]
	pub fn encode<T: AsRef<[u8]>>(input: T) -> String {
	STANDARD.encode(input)
	}

	///Encode arbitrary octets as base64 using the provided `Engine` into a new `String`.
	///
	/// See [Engine::encode].
	#[allow(unused)]
	#[deprecated(since = "0.21.0", note = "Use Engine::encode")]
	#[cfg(any(feature = "alloc", test))]
	pub fn encode_engine<E: Engine, T: AsRef<[u8]>>(input: T, engine: &E) -> String {
	engine.encode(input)
	}

	///Encode arbitrary octets as base64 into a supplied `String`.
	///
	/// See [Engine::encode_string].
	#[allow(unused)]
	#[deprecated(since = "0.21.0", note = "Use Engine::encode_string")]
	#[cfg(any(feature = "alloc", test))]
	pub fn encode_engine_string<E: Engine, T: AsRef<[u8]>>(
	input: T,
	output_buf: &mut String,
	engine: &E,
	) {
	engine.encode_string(input, output_buf)
	}

	/// Encode arbitrary octets as base64 into a supplied slice.
	///
	/// See [Engine::encode_slice].
	#[allow(unused)]
	#[deprecated(since = "0.21.0", note = "Use Engine::encode_slice")]
	pub fn encode_engine_slice<E: Engine, T: AsRef<[u8]>>(
	input: T,
	output_buf: &mut [u8],
	engine: &E,
	) -> Result<usize, EncodeSliceError> {
	engine.encode_slice(input, output_buf)
	}

	/// B64-encode and pad (if configured).
	///
	/// This helper exists to avoid recalculating encoded_size, which is relatively expensive on short
	/// inputs.
	///
	/// `encoded_size` is the encoded size calculated for `input`.
	///
	/// `output` must be of size `encoded_size`.
	///
	/// All bytes in `output` will be written to since it is exactly the size of the output.
	pub(crate) fn encode_with_padding<E: Engine + ?Sized>(
	input: &[u8],
	output: &mut [u8],
	engine: &E,
	expected_encoded_size: usize,
	) {
	debug_assert_eq!(expected_encoded_size, output.len());

	let b64_bytes_written = engine.internal_encode(input, output);

	let padding_bytes = if engine.config().encode_padding() {
	add_padding(b64_bytes_written, &mut output[b64_bytes_written..])
	} else {
	0
	};

	let encoded_bytes = b64_bytes_written
	.checked_add(padding_bytes)
	.expect("usize overflow when calculating b64 length");

	debug_assert_eq!(expected_encoded_size, encoded_bytes);
	}

	/// Calculate the base64 encoded length for a given input length, optionally including any
	/// appropriate padding bytes.
	///
	/// Returns `None` if the encoded length can't be represented in `usize`. This will happen for
	/// input lengths in approximately the top quarter of the range of `usize`.
	pub const fn encoded_len(bytes_len: usize, padding: bool) -> Option<usize> {
	let rem = bytes_len % 3;

	let complete_input_chunks = bytes_len / 3;
	// `?` is disallowed in const, and `let Some(_) = _ else` requires 1.65.0, whereas this
	// messier syntax works on 1.48
	let complete_chunk_output =
	if let Some(complete_chunk_output) = complete_input_chunks.checked_mul(4) {
	complete_chunk_output
	} else {
	return None;
	};

	if rem > 0 {
	if padding {
	complete_chunk_output.checked_add(4)
	} else {
	let encoded_rem = match rem {
	1 => 2,
	// only other possible remainder is 2
	// can't use a separate _ => unreachable!() in const fns in ancient rust versions
	_ => 3,
	};
	complete_chunk_output.checked_add(encoded_rem)
	}
	} else {
	Some(complete_chunk_output)
	}
	}

	/// Write padding characters.
	/// `unpadded_output_len` is the size of the unpadded but base64 encoded data.
	/// `output` is the slice where padding should be written, of length at least 2.
	///
	/// Returns the number of padding bytes written.
	pub(crate) fn add_padding(unpadded_output_len: usize, output: &mut [u8]) -> usize {
	let pad_bytes = (4 - (unpadded_output_len % 4)) % 4;
	// for just a couple bytes, this has better performance than using
	// .fill(), or iterating over mutable refs, which call memset()
	#[allow(clippy::needless_range_loop)]
	for i in 0..pad_bytes {
	output[i] = PAD_BYTE;
	}

	pad_bytes
	}

	/// Errors that can occur while encoding into a slice.
	#[derive(Clone, Debug, PartialEq, Eq)]
	pub enum EncodeSliceError {
	/// The provided slice is too small.
	OutputSliceTooSmall,
	}

	impl fmt::Display for EncodeSliceError {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
	match self {
	Self::OutputSliceTooSmall => write!(f, "Output slice too small"),
	}
	}
	}

	#[cfg(any(feature = "std", test))]
	impl error::Error for EncodeSliceError {}

	#[cfg(test)]
	mod tests {
	use super::*;

	use crate::{
	alphabet,
	engine::general_purpose::{GeneralPurpose, NO_PAD, STANDARD},
	tests::{assert_encode_sanity, random_config, random_engine},
	};
	use rand::{
	distributions::{Distribution, Uniform},
	Rng, SeedableRng,
	};
	use std::str;

	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, &STANDARD, 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, &STANDARD, true);
	assert_encoded_length(5, 8, &STANDARD, true);
	assert_encoded_length(6, 8, &STANDARD, 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, &STANDARD, 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, &STANDARD, true);
	}

	#[test]
	fn encoded_size_correct_no_pad() {
	assert_encoded_length(0, 0, &URL_SAFE_NO_PAD_ENGINE, false);

	assert_encoded_length(1, 2, &URL_SAFE_NO_PAD_ENGINE, false);
	assert_encoded_length(2, 3, &URL_SAFE_NO_PAD_ENGINE, false);
	assert_encoded_length(3, 4, &URL_SAFE_NO_PAD_ENGINE, false);

	assert_encoded_length(4, 6, &URL_SAFE_NO_PAD_ENGINE, false);
	assert_encoded_length(5, 7, &URL_SAFE_NO_PAD_ENGINE, false);
	assert_encoded_length(6, 8, &URL_SAFE_NO_PAD_ENGINE, false);

	assert_encoded_length(7, 10, &URL_SAFE_NO_PAD_ENGINE, false);
	assert_encoded_length(8, 11, &URL_SAFE_NO_PAD_ENGINE, false);
	assert_encoded_length(9, 12, &URL_SAFE_NO_PAD_ENGINE, false);

	assert_encoded_length(54, 72, &URL_SAFE_NO_PAD_ENGINE, false);

	assert_encoded_length(55, 74, &URL_SAFE_NO_PAD_ENGINE, false);
	assert_encoded_length(56, 75, &URL_SAFE_NO_PAD_ENGINE, false);
	assert_encoded_length(57, 76, &URL_SAFE_NO_PAD_ENGINE, false);

	assert_encoded_length(58, 78, &URL_SAFE_NO_PAD_ENGINE, false);
	}

	#[test]
	fn encoded_size_overflow() {
	assert_eq!(None, encoded_len(usize::MAX, true));
	}

	#[test]
	fn encode_engine_string_into_nonempty_buffer_doesnt_clobber_prefix() {
	let mut orig_data = Vec::new();
	let mut prefix = String::new();
	let mut encoded_data_no_prefix = String::new();
	let mut encoded_data_with_prefix = String::new();
	let mut decoded = Vec::new();

	let prefix_len_range = Uniform::new(0, 1000);
	let input_len_range = Uniform::new(0, 1000);

	let mut rng = rand::rngs::SmallRng::from_entropy();

	for _ in 0..10_000 {
	orig_data.clear();
	prefix.clear();
	encoded_data_no_prefix.clear();
	encoded_data_with_prefix.clear();
	decoded.clear();

	let input_len = input_len_range.sample(&mut rng);

	for _ in 0..input_len {
	orig_data.push(rng.gen());
	}

	let prefix_len = prefix_len_range.sample(&mut rng);
	for _ in 0..prefix_len {
	// getting convenient random single-byte printable chars that aren't base64 is
	// annoying
	prefix.push('#');
	}
	encoded_data_with_prefix.push_str(&prefix);

	let engine = random_engine(&mut rng);
	engine.encode_string(&orig_data, &mut encoded_data_no_prefix);
	engine.encode_string(&orig_data, &mut encoded_data_with_prefix);

	assert_eq!(
	encoded_data_no_prefix.len() + prefix_len,
	encoded_data_with_prefix.len()
	);
	assert_encode_sanity(
	&encoded_data_no_prefix,
	engine.config().encode_padding(),
	input_len,
	);
	assert_encode_sanity(
	&encoded_data_with_prefix[prefix_len..],
	engine.config().encode_padding(),
	input_len,
	);

	// append plain encode onto prefix
	prefix.push_str(&encoded_data_no_prefix);

	assert_eq!(prefix, encoded_data_with_prefix);

	engine
	.decode_vec(&encoded_data_no_prefix, &mut decoded)
	.unwrap();
	assert_eq!(orig_data, decoded);
	}
	}

	#[test]
	fn encode_engine_slice_into_nonempty_buffer_doesnt_clobber_suffix() {
	let mut orig_data = Vec::new();
	let mut encoded_data = Vec::new();
	let mut encoded_data_original_state = Vec::new();
	let mut decoded = Vec::new();

	let input_len_range = Uniform::new(0, 1000);

	let mut rng = rand::rngs::SmallRng::from_entropy();

	for _ in 0..10_000 {
	orig_data.clear();
	encoded_data.clear();
	encoded_data_original_state.clear();
	decoded.clear();

	let input_len = input_len_range.sample(&mut rng);

	for _ in 0..input_len {
	orig_data.push(rng.gen());
	}

	// plenty of existing garbage in the encoded buffer
	for _ in 0..10 * input_len {
	encoded_data.push(rng.gen());
	}

	encoded_data_original_state.extend_from_slice(&encoded_data);

	let engine = random_engine(&mut rng);

	let encoded_size = encoded_len(input_len, engine.config().encode_padding()).unwrap();

	assert_eq!(
	encoded_size,
	engine.encode_slice(&orig_data, &mut encoded_data).unwrap()
	);

	assert_encode_sanity(
	str::from_utf8(&encoded_data[0..encoded_size]).unwrap(),
	engine.config().encode_padding(),
	input_len,
	);

	assert_eq!(
	&encoded_data[encoded_size..],
	&encoded_data_original_state[encoded_size..]
	);

	engine
	.decode_vec(&encoded_data[0..encoded_size], &mut decoded)
	.unwrap();
	assert_eq!(orig_data, decoded);
	}
	}

	#[test]
	fn encode_to_slice_random_valid_utf8() {
	let mut input = Vec::new();
	let mut output = Vec::new();

	let input_len_range = Uniform::new(0, 1000);

	let mut rng = rand::rngs::SmallRng::from_entropy();

	for _ in 0..10_000 {
	input.clear();
	output.clear();

	let input_len = input_len_range.sample(&mut rng);

	for _ in 0..input_len {
	input.push(rng.gen());
	}

	let config = random_config(&mut rng);
	let engine = random_engine(&mut rng);

	// fill up the output buffer with garbage
	let encoded_size = encoded_len(input_len, config.encode_padding()).unwrap();
	for _ in 0..encoded_size {
	output.push(rng.gen());
	}

	let orig_output_buf = output.clone();

	let bytes_written = engine.internal_encode(&input, &mut output);

	// make sure the part beyond bytes_written is the same garbage it was before
	assert_eq!(orig_output_buf[bytes_written..], output[bytes_written..]);

	// make sure the encoded bytes are UTF-8
	let _ = str::from_utf8(&output[0..bytes_written]).unwrap();
	}
	}

	#[test]
	fn encode_with_padding_random_valid_utf8() {
	let mut input = Vec::new();
	let mut output = Vec::new();

	let input_len_range = Uniform::new(0, 1000);

	let mut rng = rand::rngs::SmallRng::from_entropy();

	for _ in 0..10_000 {
	input.clear();
	output.clear();

	let input_len = input_len_range.sample(&mut rng);

	for _ in 0..input_len {
	input.push(rng.gen());
	}

	let engine = random_engine(&mut rng);

	// fill up the output buffer with garbage
	let encoded_size = encoded_len(input_len, engine.config().encode_padding()).unwrap();
	for _ in 0..encoded_size + 1000 {
	output.push(rng.gen());
	}

	let orig_output_buf = output.clone();

	encode_with_padding(&input, &mut output[0..encoded_size], &engine, encoded_size);

	// make sure the part beyond b64 is the same garbage it was before
	assert_eq!(orig_output_buf[encoded_size..], output[encoded_size..]);

	// make sure the encoded bytes are UTF-8
	let _ = str::from_utf8(&output[0..encoded_size]).unwrap();
	}
	}

	#[test]
	fn add_padding_random_valid_utf8() {
	let mut output = Vec::new();

	let mut rng = rand::rngs::SmallRng::from_entropy();

	// cover our bases for length % 4
	for unpadded_output_len in 0..20 {
	output.clear();

	// fill output with random
	for _ in 0..100 {
	output.push(rng.gen());
	}

	let orig_output_buf = output.clone();

	let bytes_written = add_padding(unpadded_output_len, &mut output);

	// make sure the part beyond bytes_written is the same garbage it was before
	assert_eq!(orig_output_buf[bytes_written..], output[bytes_written..]);

	// make sure the encoded bytes are UTF-8
	let _ = str::from_utf8(&output[0..bytes_written]).unwrap();
	}
	}

	fn assert_encoded_length<E: Engine>(
	input_len: usize,
	enc_len: usize,
	engine: &E,
	padded: bool,
	) {
	assert_eq!(enc_len, encoded_len(input_len, padded).unwrap());

	let mut bytes: Vec<u8> = Vec::new();
	let mut rng = rand::rngs::SmallRng::from_entropy();

	for _ in 0..input_len {
	bytes.push(rng.gen());
	}

	let encoded = engine.encode(&bytes);
	assert_encode_sanity(&encoded, padded, input_len);

	assert_eq!(enc_len, encoded.len());
	}

	#[test]
	fn encode_imap() {
	assert_eq!(
	&GeneralPurpose::new(&alphabet::IMAP_MUTF7, NO_PAD).encode(b"\xFB\xFF"),
	&GeneralPurpose::new(&alphabet::STANDARD, NO_PAD)
	.encode(b"\xFB\xFF")
	.replace('/', ",")
	);
	}
	}