Struct GeneralPurposeConfig

source

pub struct GeneralPurposeConfig { /* private fields */ }

Expand description

Contains configuration parameters for base64 encoding and decoding.

let config = GeneralPurposeConfig::new()
    .with_encode_padding(false);
    // further customize using `.with_*` methods as needed

The constants PAD and NO_PAD cover most use cases.

To specify the characters used, see Alphabet.

Implementations§

source §

impl GeneralPurposeConfig

source

pub const fn new() -> Self

Create a new config with padding = true, decode_allow_trailing_bits = false, and decode_padding_mode = DecodePaddingMode::RequireCanonicalPadding.

This probably matches most people’s expectations, but consider disabling padding to save a few bytes unless you specifically need it for compatibility with some legacy system.

source

pub const fn with_encode_padding(self, padding: bool) -> Self

Create a new config based on self with an updated padding setting.

If padding is true, encoding will append either 1 or 2 = padding characters as needed to produce an output whose length is a multiple of 4.

Padding is not needed for correct decoding and only serves to waste bytes, but it’s in the spec.

For new applications, consider not using padding if the decoders you’re using don’t require padding to be present.

source

pub const fn with_decode_allow_trailing_bits(self, allow: bool) -> Self

Create a new config based on self with an updated decode_allow_trailing_bits setting.

Most users will not need to configure this. It’s useful if you need to decode base64 produced by a buggy encoder that has bits set in the unused space on the last base64 character as per forgiving-base64 decode. If invalid trailing bits are present and this is true, those bits will be silently ignored, else DecodeError::InvalidLastSymbol will be emitted.

source

pub const fn with_decode_padding_mode(self, mode: DecodePaddingMode) -> Self

Create a new config based on self with an updated decode_padding_mode setting.

Padding is not useful in terms of representing encoded data – it makes no difference to the decoder if padding is present or not, so if you have some un-padded input to decode, it is perfectly fine to use DecodePaddingMode::Indifferent to prevent errors from being emitted.

However, since in practice people who learned nothing from BER vs DER seem to expect base64 to have one canonical encoding, the default setting is the stricter DecodePaddingMode::RequireCanonicalPadding.

Or, if “canonical” in your circumstance means no padding rather than padding to the next multiple of four, there’s DecodePaddingMode::RequireNoPadding.