base64

• DecodeSliceError::OutputSliceTooSmall is now conservative rather than precise. That is, the error will only occur if the decoded output cannot fit, meaning that Engine::decode_slice can now be used with exactly-sized output slices. As part of this, Engine::internal_decode now returns DecodeSliceError instead of DecodeError, but that is not expected to affect any external callers.
• DecodeError::InvalidLength now refers specifically to the number of valid symbols being invalid (i.e. len % 4 == 1), rather than just the number of input bytes. This avoids confusing scenarios when based on interpretation you could make a case for either InvalidLength or InvalidByte being appropriate.
• Decoding is somewhat faster (5-10%)

• Support getting an alphabet's contents as a str via Alphabet::as_str()

• Improved introductory documentation and example

• Add Debug and Clone impls for the general purpose Engine

• Make encoded_len const, allowing the creation of arrays sized to encode compile-time-known data lengths

• Implement source instead of cause on Error types
• Roll back MSRV to 1.48.0 so Debian can continue to live in a time warp
• Slightly faster chunked encoding for short inputs
• Decrease binary size

• Rollback MSRV to 1.57.0 -- only dev dependencies need 1.60, not the main code

• Remove the possibility of panicking during decoded length calculations
• DecoderReader no longer sometimes erroneously ignores padding #226

Breaking changes

• Engine.internal_decode return type changed
• Update MSRV to 1.60.0

Migration

Functions

< 0.20 function	0.21 equivalent
encode()	engine::general_purpose::STANDARD.encode() or prelude::BASE64_STANDARD.encode()
encode_config()	engine.encode()
encode_config_buf()	engine.encode_string()
encode_config_slice()	engine.encode_slice()
decode()	engine::general_purpose::STANDARD.decode() or prelude::BASE64_STANDARD.decode()
decode_config()	engine.decode()
decode_config_buf()	engine.decode_vec()
decode_config_slice()	engine.decode_slice()

The short-lived 0.20 functions were the 0.13 functions with config replaced with engine.

Padding

If applicable, use the preset engines engine::STANDARD, engine::STANDARD_NO_PAD, engine::URL_SAFE, or engine::URL_SAFE_NO_PAD. The NO_PAD ones require that padding is absent when decoding, and the others require that canonical padding is present .

If you need the < 0.20 behavior that did not care about padding, or want to recreate < 0.20.0's predefined Configs precisely, see the following table.

0.13.1 Config	0.20.0+ alphabet	encode_padding	decode_padding_mode
STANDARD	STANDARD	true	Indifferent
STANDARD_NO_PAD	STANDARD	false	Indifferent
URL_SAFE	URL_SAFE	true	Indifferent
URL_SAFE_NO_PAD	URL_SAFE	false	Indifferent

• Restore the ability to decode into a slice of precisely the correct length with Engine.decode_slice_unchecked.
• Add Engine as a pub use in prelude.

Breaking changes

• Re-exports of preconfigured engines in engine are removed in favor of base64::prelude::... that are better suited to those who wish to use the entire path to a name.

Breaking changes

• FastPortable was only meant to be an interim name, and shouldn't have shipped in 0.20. It is now GeneralPurpose to make its intended usage more clear.
• 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, STANDARD_NO_PAD, URL_SAFE, URL_SAFE_NO_PAD}
  • These are pub used into engine as well
• The *_slice decode/encode functions now return an error instead of panicking when the output slice is too small
  • As part of this, there isn't now a public way to decode into a slice exactly the size needed for inputs that aren't multiples of 4 tokens. If adding up to 2 bytes to always be a multiple of 3 bytes for the decode buffer is a problem, file an issue.

Other changes

• decoded_len_estimate() is provided to make it easy to size decode buffers correctly.

Breaking changes

• Update MSRV to 1.57.0
• Decoding can now either ignore padding, require correct padding, or require no padding. The default is to require correct padding.
  • The NO_PAD config now requires that padding be absent when decoding.

0.20.0-alpha.1

Breaking changes

• Extended the Config concept into the Engine abstraction, allowing the user to pick different encoding / decoding implementations.
  • What was formerly the only algorithm is now the FastPortable engine, so named because it's portable (works on any CPU) and relatively fast.
  • This opens the door to a portable constant-time implementation (#153, presumably ConstantTimePortable?) for security-sensitive applications that need side-channel resistance, and CPU-specific SIMD implementations for more speed.
  • Standard base64 per the RFC is available via DEFAULT_ENGINE. To use different alphabets or other settings ( padding, etc), create your own engine instance.
• CharacterSet is now Alphabet (per the RFC), and allows creating custom alphabets. The corresponding tables that were previously code-generated are now built dynamically.
• Since there are already multiple breaking changes, various functions are renamed to be more consistent and discoverable.
• MSRV is now 1.47.0 to allow various things to use const fn.
• DecoderReader now owns its inner reader, and can expose it via into_inner(). For symmetry, EncoderWriter can do the same with its writer.
• encoded_len is now public so you can size encode buffers precisely.

• More precise decode buffer sizing, avoiding unnecessary allocation in decode_config.

• Config methods are const
• Added EncoderStringWriter to allow encoding directly to a String
• EncoderWriter now owns its delegate writer rather than keeping a reference to it (though refs still work)
  • As a consequence, it is now possible to extract the delegate writer from an EncoderWriter via finish(), which returns Result<W> instead of Result<()>. If you were calling finish() explicitly, you will now need to use let _ = foo.finish() instead of just foo.finish() to avoid a warning about the unused value.
• When decoding input that has both an invalid length and an invalid symbol as the last byte, InvalidByte will be emitted instead of InvalidLength to make the problem more obvious.

• Add BinHex alphabet

• Add Bcrypt alphabet

• A Read implementation (DecoderReader) to let users transparently decoded data from a b64 input source
• IMAP's modified b64 alphabet
• Relaxed type restrictions to just AsRef<[ut8]> for main encode*/decode* functions
• A minor performance improvement in encoding

• Minimum rust version 1.34.0
• no_std is now supported via the two new features alloc and std.

• Minimum rust version 1.27.2
• Fix bug in streaming encoding (#90): if the underlying writer didn't write all the bytes given to it, the remaining bytes would not be retried later. See the docs on EncoderWriter::write.
• Make it configurable whether or not to return an error when decoding detects excess trailing bits.

• Remove line wrapping. Line wrapping was never a great conceptual fit in this library, and other features (streaming encoding, etc) either couldn't support it or could support only special cases of it with a great increase in complexity. Line wrapping has been pulled out into a line-wrap crate, so it's still available if you need it.
  • Base64Display creation no longer uses a Result because it can't fail, which means its helper methods for common configs that unwrap() for you are no longer needed
• Add a streaming encoder Write impl to transparently base64 as you write.
• Remove the remaining unsafe code.
• Remove whitespace stripping to simplify no_std support. No out of the box configs use it, and it's trivial to do yourself if needed: filter(|b| !b" \n\t\r\x0b\x0c".contains(b).
• Detect invalid trailing symbols when decoding and return an error rather than silently ignoring them.

• Update safemem

• Derive Clone for DecodeError.

• Add support for crypt(3)'s base64 variant.

• decode_config_slice function for no-allocation decoding, analogous to encode_config_slice
• Decode performance optimization

• encode_config_slice function for no-allocation encoding

• STANDARD_NO_PAD config
• Base64Display heap-free wrapper for use in format strings, etc

• Decode performance improvements
• Use unsafe in fewer places
• Added fuzzers

• Avoid usize overflow when calculating length
• Better line wrapping performance

• Temporarily disable line wrapping
• Add Apache 2.0 license

• MIME support, including configurable line endings and line wrapping
• Removed decode_ws
• Renamed Base64Error to DecodeError

• Allow decoding a AsRef<[u8]> instead of just a &str

• Configurable padding
• Encode performance improvements

• Added encode/decode functions that do not allocate their own storage
• Decode performance improvements
• Extraneous padding bytes are no longer ignored. Now, an error will be returned.