Trait Engine

pub trait Engine: Send + Sync {
    type Config: Config;
    type DecodeEstimate: DecodeEstimate;

    // Required method
    fn config(&self) -> &Self::Config;

    // Provided methods
    fn encode<T: AsRef<[u8]>>(&self, input: T) -> String { ... }
    fn encode_string<T: AsRef<[u8]>>(&self, input: T, output_buf: &mut String) { ... }
    fn encode_slice<T: AsRef<[u8]>>(
        &self,
        input: T,
        output_buf: &mut [u8],
    ) -> Result<usize, EncodeSliceError> { ... }
    fn decode<T: AsRef<[u8]>>(&self, input: T) -> Result<Vec<u8>, DecodeError> { ... }
    fn decode_vec<T: AsRef<[u8]>>(
        &self,
        input: T,
        buffer: &mut Vec<u8>,
    ) -> Result<(), DecodeError> { ... }
    fn decode_slice<T: AsRef<[u8]>>(
        &self,
        input: T,
        output: &mut [u8],
    ) -> Result<usize, DecodeSliceError> { ... }
    fn decode_slice_unchecked<T: AsRef<[u8]>>(
        &self,
        input: T,
        output: &mut [u8],
    ) -> Result<usize, DecodeError> { ... }
}

An Engine provides low-level encoding and decoding operations that all other higher-level parts of the API use. Users of the library will generally not need to implement this.

Different implementations offer different characteristics. The library currently ships with GeneralPurpose that offers good speed and works on any CPU, with more choices coming later, like a constant-time one when side channel resistance is called for, and vendor-specific vectorized ones for more speed.

See general_purpose::STANDARD_NO_PAD if you just want standard base64. Otherwise, when possible, it’s recommended to store the engine in a const so that references to it won’t pose any lifetime issues, and to avoid repeating the cost of engine setup.

Since almost nobody will need to implement Engine, docs for internal methods are hidden.

Required Associated Types

type Config: Config

The config type used by this engine

type DecodeEstimate: DecodeEstimate

The decode estimate used by this engine

Required Methods

fn config(&self) -> &Self::Config

Returns the config for this engine.

Provided Methods

fn encode<T: AsRef<[u8]>>(&self, input: T) -> String

Encode arbitrary octets as base64 using the provided Engine. Returns a String.

Example

use base64::{Engine as _, engine::{self, general_purpose}, alphabet};

let b64 = general_purpose::STANDARD.encode(b"hello world~");
println!("{}", b64);

const CUSTOM_ENGINE: engine::GeneralPurpose =
    engine::GeneralPurpose::new(&alphabet::URL_SAFE, general_purpose::NO_PAD);

let b64_url = CUSTOM_ENGINE.encode(b"hello internet~");

fn encode_string<T: AsRef<[u8]>>(&self, input: T, output_buf: &mut String)

Encode arbitrary octets as base64 into a supplied String. Writes into the supplied String, which may allocate if its internal buffer isn’t big enough.

Example

use base64::{Engine as _, engine::{self, general_purpose}, alphabet};
const CUSTOM_ENGINE: engine::GeneralPurpose =
    engine::GeneralPurpose::new(&alphabet::URL_SAFE, general_purpose::NO_PAD);

fn main() {
    let mut buf = String::new();
    general_purpose::STANDARD.encode_string(b"hello world~", &mut buf);
    println!("{}", buf);

    buf.clear();
    CUSTOM_ENGINE.encode_string(b"hello internet~", &mut buf);
    println!("{}", buf);
}

fn encode_slice<T: AsRef<[u8]>>( &self, input: T, output_buf: &mut [u8], ) -> Result<usize, EncodeSliceError>

Encode arbitrary octets as base64 into a supplied slice. Writes into the supplied output buffer.

This is useful if you wish to avoid allocation entirely (e.g. encoding into a stack-resident or statically-allocated buffer).

Example

use base64::{Engine as _, engine::general_purpose};
let s = b"hello internet!";
let mut buf = Vec::new();
// make sure we'll have a slice big enough for base64 + padding
buf.resize(s.len() * 4 / 3 + 4, 0);

let bytes_written = general_purpose::STANDARD.encode_slice(s, &mut buf).unwrap();

// shorten our vec down to just what was written
buf.truncate(bytes_written);

assert_eq!(s, general_purpose::STANDARD.decode(&buf).unwrap().as_slice());

fn decode<T: AsRef<[u8]>>(&self, input: T) -> Result<Vec<u8>, DecodeError>

Decode the input into a new Vec.

Example

use base64::{Engine as _, alphabet, engine::{self, general_purpose}};

let bytes = general_purpose::STANDARD
    .decode("aGVsbG8gd29ybGR+Cg==").unwrap();
println!("{:?}", bytes);

// custom engine setup
let bytes_url = engine::GeneralPurpose::new(
             &alphabet::URL_SAFE,
             general_purpose::NO_PAD)
    .decode("aGVsbG8gaW50ZXJuZXR-Cg").unwrap();
println!("{:?}", bytes_url);

fn decode_vec<T: AsRef<[u8]>>( &self, input: T, buffer: &mut Vec<u8>, ) -> Result<(), DecodeError>

Decode the input into the supplied buffer.

Writes into the supplied Vec, which may allocate if its internal buffer isn’t big enough. Returns a Result containing an empty tuple, aka ().

Example

use base64::{Engine as _, alphabet, engine::{self, general_purpose}};
const CUSTOM_ENGINE: engine::GeneralPurpose =
    engine::GeneralPurpose::new(&alphabet::URL_SAFE, general_purpose::PAD);

fn main() {
    use base64::Engine;
    let mut buffer = Vec::<u8>::new();
    // with the default engine
    general_purpose::STANDARD
        .decode_vec("aGVsbG8gd29ybGR+Cg==", &mut buffer,).unwrap();
    println!("{:?}", buffer);

    buffer.clear();

    // with a custom engine
    CUSTOM_ENGINE.decode_vec(
        "aGVsbG8gaW50ZXJuZXR-Cg==",
        &mut buffer,
    ).unwrap();
    println!("{:?}", buffer);
}

fn decode_slice<T: AsRef<[u8]>>( &self, input: T, output: &mut [u8], ) -> Result<usize, DecodeSliceError>

Decode the input into the provided output slice.

Returns the number of bytes written to the slice, or an error if output is smaller than the estimated decoded length.

This will not write any bytes past exactly what is decoded (no stray garbage bytes at the end).

See crate::decoded_len_estimate for calculating buffer sizes.

See Engine::decode_slice_unchecked for a version that panics instead of returning an error if the output buffer is too small.

fn decode_slice_unchecked<T: AsRef<[u8]>>( &self, input: T, output: &mut [u8], ) -> Result<usize, DecodeError>

Decode the input into the provided output slice.

Returns the number of bytes written to the slice.

This will not write any bytes past exactly what is decoded (no stray garbage bytes at the end).

See crate::decoded_len_estimate for calculating buffer sizes.

See Engine::decode_slice for a version that returns an error instead of panicking if the output buffer is too small.

Panics

Panics if the provided output buffer is too small for the decoded data.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl Engine for GeneralPurpose

type Config = GeneralPurposeConfig

type DecodeEstimate = GeneralPurposeEstimate