Expand description
Getting started
- Perhaps one of the preconfigured engines in engine::general_purpose will suit, e.g.
engine::general_purpose::STANDARD_NO_PAD.
- These are re-exported in prelude with a
BASE64_
prefix for those who prefer touse base64::prelude::*
or equivalent, e.g. prelude::BASE64_STANDARD_NO_PAD
- These are re-exported in prelude with a
- If not, choose which alphabet you want. Most usage will want alphabet::STANDARD or alphabet::URL_SAFE.
- Choose which Engine implementation you want. For the moment there is only one: engine::GeneralPurpose.
- Configure the engine appropriately using the engine’s
Config
type.- This is where you’ll select whether to add padding (when encoding) or expect it (when decoding). If given the choice, prefer no padding.
- Build the engine using the selected alphabet and config.
For more detail, see below.
Alphabets
An alphabet::Alphabet defines what ASCII symbols are used to encode to or decode from.
Constants in alphabet like alphabet::STANDARD or alphabet::URL_SAFE provide commonly used alphabets, but you can also build your own custom alphabet::Alphabet if needed.
Engines
Once you have an Alphabet
, you can pick which Engine
you want. A few parts of the public
API provide a default, but otherwise the user must provide an Engine
to use.
See Engine for more.
Config
In addition to an Alphabet
, constructing an Engine
also requires an engine::Config. Each
Engine
has a corresponding Config
implementation since different Engine
s may offer different
levels of configurability.
Encoding
Several different encoding methods on Engine are available to you depending on your desire for convenience vs performance.
Method | Output | Allocates |
---|---|---|
Engine::encode | Returns a new String | Always |
Engine::encode_string | Appends to provided String | Only if String needs to grow |
Engine::encode_slice | Writes to provided &[u8] | Never - fastest |
All of the encoding methods will pad as per the engine’s config.
Decoding
Just as for encoding, there are different decoding methods available.
Method | Output | Allocates |
---|---|---|
Engine::decode | Returns a new Vec<u8> | Always |
Engine::decode_vec | Appends to provided Vec<u8> | Only if Vec needs to grow |
Engine::decode_slice | Writes to provided &[u8] | Never - fastest |
Unlike encoding, where all possible input is valid, decoding can fail (see DecodeError).
Input can be invalid because it has invalid characters or invalid padding. The nature of how padding is checked depends on the engine’s config. Whitespace in the input is invalid, just like any other non-base64 byte.
Read
and Write
To decode a std::io::Read of b64 bytes, wrap a reader (file, network socket, etc) with read::DecoderReader.
To write raw bytes and have them b64 encoded on the fly, wrap a std::io::Write with write::EncoderWriter.
There is some performance overhead (15% or so) because of the necessary buffer shuffling – still fast enough that almost nobody cares. Also, these implementations do not heap allocate.
Display
See display for how to transparently base64 data via a Display
implementation.
Examples
Using predefined engines
use base64::{Engine as _, engine::general_purpose};
let orig = b"data";
let encoded: String = general_purpose::STANDARD_NO_PAD.encode(orig);
assert_eq!("ZGF0YQ", encoded);
assert_eq!(orig.as_slice(), &general_purpose::STANDARD_NO_PAD.decode(encoded).unwrap());
// or, URL-safe
let encoded_url = general_purpose::URL_SAFE_NO_PAD.encode(orig);
Custom alphabet, config, and engine
use base64::{engine, alphabet, Engine as _};
// bizarro-world base64: +/ as the first symbols instead of the last
let alphabet =
alphabet::Alphabet::new("+/ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789")
.unwrap();
// a very weird config that encodes with padding but requires no padding when decoding...?
let crazy_config = engine::GeneralPurposeConfig::new()
.with_decode_allow_trailing_bits(true)
.with_encode_padding(true)
.with_decode_padding_mode(engine::DecodePaddingMode::RequireNone);
let crazy_engine = engine::GeneralPurpose::new(&alphabet, crazy_config);
let encoded = crazy_engine.encode(b"abc 123");
Panics
If length calculations result in overflowing usize
, a panic will result.
Re-exports
pub use engine::Engine;
Modules
- Provides Alphabet and constants for alphabets commonly used in the wild.
- Enables base64’d output anywhere you might use a
Display
implementation, like a format string. - Provides the Engine abstraction and out of the box implementations.
- Preconfigured engines for common use cases.
- Implementations of
io::Read
to transparently decode base64. - Implementations of
io::Write
to transparently handle base64.
Enums
- Errors that can occur while decoding.
- Errors that can occur while decoding into a slice.
- Errors that can occur while encoding into a slice.
Functions
- decodeDeprecatedDecode base64 using the
STANDARD
engine. - decode_engineDeprecatedDecode from string reference as octets using the specified Engine.
- decode_engine_sliceDeprecatedDecode the input into the provided output slice.
- decode_engine_vecDeprecatedDecode from string reference as octets.
- Returns a conservative estimate of the decoded size of
encoded_len
base64 symbols (rounded up to the next group of 3 decoded bytes). - encodeDeprecatedEncode arbitrary octets as base64 using the
STANDARD
engine. - encode_engineDeprecatedEncode arbitrary octets as base64 using the provided
Engine
into a newString
. - encode_engine_sliceDeprecatedEncode arbitrary octets as base64 into a supplied slice.
- encode_engine_stringDeprecatedEncode arbitrary octets as base64 into a supplied
String
. - Calculate the base64 encoded length for a given input length, optionally including any appropriate padding bytes.