Trait base64::engine::Engine

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

    fn encode(&self, input: &[u8], output: &mut [u8]) -> usize;
    fn decoded_length_estimate(&self, input_len: usize) -> Self::DecodeEstimate;
    fn decode(
        &self,
        input: &[u8],
        output: &mut [u8],
        decode_estimate: Self::DecodeEstimate
    ) -> Result<usize, DecodeError>;
    fn config(&self) -> &Self::Config;
}

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 a general-purpose FastPortable impl 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 DEFAULT_ENGINE 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.

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 encode(&self, input: &[u8], output: &mut [u8]) -> usize

Encode the input bytes into the output buffer based on the mapping in encode_table.

output will be long enough to hold the encoded data.

Returns the number of bytes written.

No padding should be written; that is handled separately.

Must not write any bytes into the output slice other than the encoded data.

fn decoded_length_estimate(&self, input_len: usize) -> Self::DecodeEstimate

As an optimization to prevent the decoded length from being calculated twice, it is sometimes helpful to have a conservative estimate of the decoded size before doing the decoding, so this calculation is done separately and passed to Engine::decode() as needed.

fn decode(
    &self,
    input: &[u8],
    output: &mut [u8],
    decode_estimate: Self::DecodeEstimate
) -> Result<usize, DecodeError>

Decode input base64 bytes into the output buffer.

decode_estimate is the result of Engine::decoded_length_estimate(), which is passed in to avoid calculating it again (expensive on short inputs).`

Returns the number of bytes written to output.

Each complete 4-byte chunk of encoded data decodes to 3 bytes of decoded data, but this function must also handle the final possibly partial chunk. If the input length is not a multiple of 4, or uses padding bytes to reach a multiple of 4, the trailing 2 or 3 bytes must decode to 1 or 2 bytes, respectively, as per the RFC.

Decoding must not write any bytes into the output slice other than the decoded data.

Non-canonical trailing bits in the final tokens or non-canonical padding must be reported as errors unless the engine is configured otherwise.

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

Returns the config for this engine.

Implementors

impl Engine for FastPortable

type Config = FastPortableConfig

type DecodeEstimate = FastPortableEstimate