Struct radix64::configs::CustomConfig

pub struct CustomConfig { /* fields omitted */ }

A custom defined alphabet and padding.

All characters of the alphabet, as well as the padding character (if any), must be ascii characters.

Examples

// Create a custom base64 configuration that matches what `crypt(3)`
// produces. This is equivalent to using radix64::CRYPT except the builtin
// constant provides SIMD optimized encoding/decoding when available while a
// custom config cannot.
use radix64::CustomConfig;

let my_config = CustomConfig::with_alphabet(
    "./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
)
.no_padding()
.build()
.unwrap();

let my_encoded_msg = my_config.encode("my message");
assert_eq!("PLYUPKJnQq3bNE", my_encoded_msg.as_str());
assert_eq!("my message".as_bytes(), my_config.decode(&my_encoded_msg).unwrap().as_slice());

Note that building a custom configuration is somewhat expensive. It needs to iterate over the provided alphabet, sanity check it's contents, create an inverted alphabet for decoding, and store the results. For this reason it's encouraged to create a custom config early in program execution and share a single instance throughout the code. A simple way to do this is by utilizing lazy_static.

use lazy_static::lazy_static;
use radix64::CustomConfig;

lazy_static::lazy_static! {
    pub static ref MY_CONFIG: CustomConfig = CustomConfig::with_alphabet(
        "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/",
    )
    .with_padding(b'=')
    .build()
    .expect("failed to build custom base64 config");
}

let my_encoded_msg = MY_CONFIG.encode("my message");
assert_eq!("bXkgbWVzc2FnZQ==", my_encoded_msg.as_str());
assert_eq!("my message".as_bytes(), MY_CONFIG.decode(&my_encoded_msg).unwrap().as_slice());

Methods

impl CustomConfig

pub fn with_alphabet<A: AsRef<[u8]> + ?Sized>(
    alphabet: &A
) -> CustomConfigBuilder

Start creating a new CustomConfig with the provided alphabet. The provided alphabet needs to be 64 non-repeating ascii bytes.

pub fn encode<I: ?Sized>(&self, input: &I) -> String where
    I: AsRef<[u8]>, 

See Config::encode.

pub fn encode_with_buffer<'i, 'b, I: ?Sized>(
    &self,
    input: &'i I,
    buffer: &'b mut Vec<u8>
) -> &'b str where
    I: AsRef<[u8]>, 

See Config::encode_with_buffer.

pub fn encode_slice<I: ?Sized>(&self, input: &I, output: &mut [u8]) -> usize where
    I: AsRef<[u8]>, 

See Config::encode_slice.

pub fn decode<I: ?Sized>(&self, input: &I) -> Result<Vec<u8>, DecodeError> where
    I: AsRef<[u8]>, 

See Config::decode.

pub fn decode_with_buffer<'i, 'b, I: ?Sized>(
    &self,
    input: &'i I,
    buffer: &'b mut Vec<u8>
) -> Result<&'b [u8], DecodeError> where
    I: AsRef<[u8]>, 

See Config::decode_with_buffer.

pub fn decode_slice<'a, 'b, I: ?Sized>(
    &self,
    input: &'a I,
    output: &'b mut [u8]
) -> Result<usize, DecodeError> where
    I: AsRef<[u8]>, 

See Config::decode_slice.

Trait Implementations

impl<'_> Config for &'_ CustomConfig

fn encode<I: ?Sized>(self, input: &I) -> String where
    I: AsRef<[u8]>, 

Encode the provided input into a String.

fn encode_with_buffer<'i, 'b, I: ?Sized>(
    self,
    input: &'i I,
    buffer: &'b mut Vec<u8>
) -> &'b str where
    I: AsRef<[u8]>, 

Encode the provided input into the provided buffer, returning a &str of the encoded input. The returned &str is a view into the beginning of the provided buffer that contains the encoded data. This method overwrites the data in the buffer, it does not append to the buffer. This method exists to provide an efficient way to amortize allocations when repeatedly encoding different inputs. The same buffer can be provided for each invocation and will only be resized when necessary. Any data in the buffer outside the range of the returned &str is not part of the encoded output and should be ignored.

fn encode_slice<I: ?Sized>(self, input: &I, output: &mut [u8]) -> usize where
    I: AsRef<[u8]>, 

Encode the provided input into the provided output slice. The slice must be large enough to contain the encoded output and panics if it's not. Use input.len() * 4 / 3 + 3 as a conservative estimate. It returns the number of bytes of encoded output written to the output slice. This method allows for the most control over memory placement, but encode_with_buffer is typically more ergonomic and just as performant.

fn decode<I: ?Sized>(self, input: &I) -> Result<Vec<u8>, DecodeError> where
    I: AsRef<[u8]>, 

Decode the provided input.

fn decode_with_buffer<'i, 'b, I: ?Sized>(
    self,
    input: &'i I,
    buffer: &'b mut Vec<u8>
) -> Result<&'b [u8], DecodeError> where
    I: AsRef<[u8]>, 

Decode the provided input into the provided buffer, returning a &u8 of the decoded input. The returned &u8 is a view into the beginning of the provided buffer that contains the decoded data. This method overwrites the data in the buffer, it does not append to the buffer. This method exists to provide an efficient way to amortize allocations when repeatedly decoding different inputs. The same buffer can be provided for each invocation and will only be resized when necessary. Any data in the buffer outside the range of the returned &u8 is not part of the decoded output and should be ignored.

fn decode_slice<I: ?Sized>(
    self,
    input: &I,
    output: &mut [u8]
) -> Result<usize, DecodeError> where
    I: AsRef<[u8]>, 

Decode the provided input into the provided output slice. The slice must be large enough to contain the decoded output and panics if it's not. Use input.len() * 6 / 8 + 1 as a conservative estimate. It returns the number of bytes of decoded output written to the output slice. This method allows for the most control over memory placement, but decode_with_buffer is typically more ergonomic and just as performant.

impl Clone for CustomConfig

fn clone(&self) -> CustomConfig

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CustomConfig

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.