Crate aliri_base64[−][src]
aliri_base64
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=");
use aliri_base64::Base64; let data = Base64::from_raw("👋 hello, world! 👋".as_bytes()); let enc = format!("MyData: {}", data); assert_eq!(enc, "MyData: 8J+RiyBoZWxsbywgd29ybGQhIPCfkYs=");
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
Base64 | Owned data to be encoded as standard base64 |
Base64Ref | Borrowed data to be encoded as standard base64 |
Base64Url | Owned data to be encoded as URL-safe base64 (no padding) |
Base64UrlRef | Borrowed data to be encoded as URL-safe base64 (no padding) |
InvalidBase64Data | An error while decoding a value which is not properly formatted base64 data |