Crate const_decoder

Constant functions for converting hex- and base64-encoded strings into bytes. Works on stable Rust and in no-std environments. Base-(2,4,8,16,32,64) encodings with custom alphabets are supported as well via Encoding.

Decoder is the base type encapsulating decoding logic, with SkipWhitespace and Pem types providing its variations with slightly different properties. (For example, Pem allows to parse PEM files.)

Methods in base types require specifying the length of the output byte array, either in its type, or using the turbofish syntax (see the examples below). To avoid this, you can instead use the decode! macro.

Conversions are primarily useful for testing, but can be used in other contexts as well.

Alternatives

hex-literal and binary_macros crates expose similar functionality as procedural macros. Because of this, macros cannot be used in no-std environments, while this approach can.

In the longer-term (after stabilizing const mutable refs, etc.) it should become possible to use “ordinary” encoding crates, such as hex.

Examples

use const_decoder::Decoder;
// An Ed25519 secret key.
const SECRET_KEY: [u8; 64] = Decoder::Hex.decode(
    b"9e55d1e1aa1f455b8baad9fdf975503655f8b359d542fa7e4ce84106d625b352\
      06fac1f22240cffd637ead6647188429fafda9c9cb7eae43386ac17f61115075",
);

Same input string decoded using decode!:

use const_decoder::{decode, Decoder};

const SECRET_KEY: &[u8] = &decode!(
    Decoder::Hex,
    b"9e55d1e1aa1f455b8baad9fdf975503655f8b359d542fa7e4ce84106d625b352\
      06fac1f22240cffd637ead6647188429fafda9c9cb7eae43386ac17f61115075",
);

Note how specifying the output length is avoided by placing the decode! output behind a reference.

include_bytes! macro works as well.

const CERT: &[u8] = &decode!(Pem, include_bytes!("certificate.crt"));

Naturally, all code works in the runtime context as well.

let public_key: [u8; 32] = Decoder::Hex.decode(
    b"06fac1f22240cffd637ead6647188429fafda9c9cb7eae43386ac17f61115075",
);
let other_public_key: [u8; 32] = Decoder::Base64.decode(
    b"6IcUt5J4tArK8SR8SpBZb8Rp7E7kyvaTfv9N8WlOinw=",
);

Compile-time errors

The code will fail to compile if there is an error in the literal:

// The provided hex string is too short
const BOGUS: [u8; 32] = Decoder::Hex.decode(b"c0ffee");

// The provided hex string is too long
const BOGUS: [u8; 3] = Decoder::Hex.decode(b"c01dbeef");

// The provided string contains invalid chars
const BOGUS: [u8; 5] = Decoder::Hex.decode(b"c0ffeecup");

Re-exports

• pub use crate::macros::DecoderWrapper;

Macros

• decode
  Computes the output length in compile time and decodes the input. This allows to skip specifying output length manually.

Structs

• Encoding
  Custom encoding scheme based on a certain alphabet (mapping between a subset of ASCII chars and digits in 0..P, where P is a power of 2).
• Pem
  Decoder for the PEM file format (Base64 with additional header / trailer lines).
• SkipWhitespace
  Decoder wrapper that skips whitespace during decoding instead of panicking.

Enums

• Decoder
  Decoder of a human-friendly encoding, such as hex or base64, into bytes.