Crate base64

source ·
Expand description

§Getting started

  1. Perhaps one of the preconfigured engines in engine::general_purpose will suit, e.g. engine::general_purpose::STANDARD_NO_PAD.
  2. If not, choose which alphabet you want. Most usage will want alphabet::STANDARD or alphabet::URL_SAFE.
  3. Choose which Engine implementation you want. For the moment there is only one: engine::GeneralPurpose.
  4. 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.
  5. 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 Engines 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.

MethodOutputAllocates
Engine::encodeReturns a new StringAlways
Engine::encode_stringAppends to provided StringOnly if String needs to grow
Engine::encode_sliceWrites 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.

MethodOutputAllocates
Engine::decodeReturns a new Vec<u8>Always
Engine::decode_vecAppends to provided Vec<u8>Only if Vec needs to grow
Engine::decode_sliceWrites 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§

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§

Functions§

  • decodeDeprecated
    Decode base64 using the STANDARD engine.
  • decode_engineDeprecated
    Decode from string reference as octets using the specified Engine.
  • Decode the input into the provided output slice.
  • Decode 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).
  • encodeDeprecated
    Encode arbitrary octets as base64 using the STANDARD engine.
  • encode_engineDeprecated
    Encode arbitrary octets as base64 using the provided Engine into a new String.
  • Encode arbitrary octets as base64 into a supplied slice.
  • Encode arbitrary octets as base64 into a supplied String.
  • Calculate the base64 encoded length for a given input length, optionally including any appropriate padding bytes.