Crate aliri_base64

Expand description

Wrappers for values that should be serialized or represented as base64

The aliri_base64 crate provides some utilities for more easily working with byte arrays and buffers that need to be serialized using Base64 encoding. This is particularly necessary for many of the types that aliri works with, but may also be of use to others as well.

Underlying data is stored as an actual byte slice. Costs of conversions between base64 and raw bytes only occur for calls to from_encoded() or conversions to strings via debug or display formatting.

This can make debugging byte arrays significantly less annoying, as Debug and Display implementations are provided as better views of the underlying byte data.

The underlying encoding/decoding mechanism is provided by the base64 crate.

§Supported encodings

Base64 and Base64Ref wrap owned and borrowed byte arrays that must be serialized in the standard Base64 encoding with padding.

Base64Url and Base64UrlRef wrap owned and borrowed byte arrays that must be serialized in the URL-safe Base64 encoding with no padding.

Additional encodings may be added in the future, but these were the two primary encodings required to support my base set of use cases.

§Unsafe code

Aliri Base64 makes use of two lines of unsafe code. This unsafe code is limited to the functions that allow the Base64Ref and Base64UrlRef to wrap borrowed byte slices. This reinterpretation is safe because these types are transparent wrappers around [u8], use #[repr(transparent)], and thus share the exact same representation as the underlying slice. This is currently necessary as there is currently no way to transmute equivalent representations of dynamically sized values in safe Rust.

For the above reason, this crate uses #![deny(unsafe_code)] rather than #![forbid(unsafe_code)]. The only #![allow(unsafe_code)] in the crate can be located in the private b64_builder! macro.

Note that, because cargo-geiger has difficulty parsing out unsafe usage from within macros, that tool won’t report these crates as “radioactive”, but probably should. Do your due diligence.

§Example

Using ToString::to_string():

use aliri_base64::Base64;

let data = Base64::from_raw("👋 hello, world! 👋".as_bytes());
let enc = data.to_string();
assert_eq!(enc, "8J+RiyBoZWxsbywgd29ybGQhIPCfkYs=");

Using format! and Display:

use aliri_base64::Base64;

let data = Base64::from_raw("👋 hello, world! 👋".as_bytes());
let enc = format!("MyData: {}", data);
assert_eq!(enc, "MyData: 8J+RiyBoZWxsbywgd29ybGQhIPCfkYs=");

Using format! and Debug:

Note that the output data is fenced in backticks when formatted for debugging.

use aliri_base64::Base64;

let data = Base64::from_raw("👋 hello, world! 👋".as_bytes());
let enc = format!("MyData: {:?}", data);
assert_eq!(enc, "MyData: `8J+RiyBoZWxsbywgd29ybGQhIPCfkYs=`");

Reinterpreting raw data, moving from URL encoding with no padding to standard encoding with padding:

use aliri_base64::{Base64, Base64Url};

let data = Base64Url::from_encoded("8J-RiyBoZWxsbywgd29ybGQhIPCfkYs").unwrap();
assert_eq!(data.as_slice(), "👋 hello, world! 👋".as_bytes());
let transcode = Base64::from_raw(data.into_inner());
let enc = transcode.to_string();
assert_eq!(enc, "8J+RiyBoZWxsbywgd29ybGQhIPCfkYs=");

§Serde

With the serde feature enabled, serializers and deserializers will be created that will encode the underlying byte array as a base64 string using the relevant encoding.

Structs§