std.encoding

std.encoding provides text encoders and decoders for binary data. Encoders accept borrowed bytes.Bytes input and return owned ^str output. Encoded output is ASCII text and therefore satisfies the str UTF-8 invariant. Decoders return byte arrays; they do not implicitly reinterpret decoded bytes as text.

How It Works

encoding.base64 uses the standard alphabet with + and / by default and accepts .UrlSafe to use the URL-safe alphabet with - and _. The encode function keeps = padding by default and accepts .Unpadded as the optional padding mode. The decode function accepts padded and unpadded input. encoding.hex uses lowercase ASCII by default and accepts lowercase or uppercase ASCII when decoding.

import std.bytes;
import std.encoding;
import std.mem.{ AllocError };

fn main() {
	let padded = try encoding.base64.encode(bytes.Bytes("fo"));
	assert padded == "Zm8=";

	let compact = try encoding.base64.encode(bytes.Bytes("fo"), .Standard, .Unpadded);
	assert compact == "Zm8";

	let decoded = try encoding.base64.decode(compact);
	assert decoded.length == 2 as usize;
	assert decoded[0] == 102 as u8;
	assert decoded[1] == 111 as u8;
}

URL Safe Encoding

Use encoding.base64 with .UrlSafe when encoded text will be placed in URLs, filenames, or tokens that should not contain + or /.

import std.bytes;
import std.encoding;
import std.mem.{ AllocError };

fn main() {
	let data = [251 as u8, 255 as u8, 238 as u8];
	let data_view: [u8] in _ = data[0..<data.length];
	let view = bytes.Bytes(data_view);

	let padded = try encoding.base64.encode(view, .UrlSafe);
	assert padded == "-__u";

	let compact = try encoding.base64.encode(bytes.Bytes("hello?"), .UrlSafe, .Unpadded);
	assert compact == "aGVsbG8_";

	let decoded = try encoding.base64.decode(compact, .UrlSafe);
	assert decoded.length == 6 as usize;
	assert decoded[5] == 63 as u8;
}

Hex Encoding

Use encoding.hex for compact ASCII byte dumps, protocol fields, and test vectors.

import std.bytes;
import std.encoding;
import std.mem.{ AllocError };

fn main() {
	let text = try encoding.hex.encode(bytes.Bytes("Hi"));
	assert text == "4869";

	let upper = try encoding.hex.encode(bytes.Bytes("Hello"), .Upper);
	assert upper == "48656C6C6F";

	let bytes_out = try encoding.hex.decode("486900");
	assert bytes_out.length == 3 as usize;
	assert bytes_out[0] == 72 as u8;
	assert bytes_out[1] == 105 as u8;
	assert bytes_out[2] == 0 as u8;
}

Ownership, Allocation, Errors, And Unspecified Behavior

Encoders borrow Bytes input and allocate owned ^str output. Decoders allocate owned ^[u8] output, while hex.encode_into and hex.decode_into write into caller-owned buffers. Decoded bytes are arbitrary binary data; convert them to text (str) only after validating text expectations.

Base64 invalid input is reported as base64.Base64Error.Invalid. Hex invalid input and too-small output buffers are reported as HexError. Allocating helpers can throw AllocError.

Encoded byte layout is exactly the selected Base64 or hex spelling. Whitespace handling, line wrapping, MIME policy, URL token policy, and text decoding policy are intentionally outside this module.

Use std.bytes for binary inputs and std.unicode when decoded bytes must become text.

API Reference

Modules

Module	Description
encoding.base64	Standard and URL-safe Base64 encoder/decoder.
encoding.hex	Hex encoder/decoder with lower or upper output case.

Errors

Error	Description
base64.Base64Error.Invalid	Input length, padding, alphabet, or trailing bits are invalid.
HexError.Invalid	Input has odd length or contains a non-hex digit.
HexError.Buffer	Caller-provided output buffer is too small.

Functions

Function	Signature	Parameters	Returns	Description
base64.encode	encode(data: Bytes, alphabet: base64.Alphabet = .Standard, padding: base64.Padding = .Padded) throws(AllocError) -> ^str	data: bytes to encode, alphabet: .Standard or .UrlSafe, padding: .Padded or .Unpadded	^str throws(AllocError)	Encodes with the selected Base64 alphabet.
base64.decode	decode(text: str, alphabet: base64.Alphabet = .Standard) throws(base64.Base64Error | AllocError) -> ^[u8]	text: Base64 text, alphabet: .Standard or .UrlSafe	^[u8] throws(base64.Base64Error | AllocError)	Decodes padded or unpadded Base64 into owned bytes.
hex.valid	valid(text: str) -> bool	text: hex text	bool	Returns true only for even-length ASCII hex.
hex.encode	encode(data: Bytes, letter_case: hex.Case = .Lower) throws(AllocError) -> ^str	data: bytes to encode, letter_case: .Lower or .Upper	^str throws(AllocError)	Encodes hex using the selected output case.
hex.encode_into	encode_into(data: Bytes, out: &[u8], letter_case: hex.Case = .Lower) throws(hex.HexError) -> usize	data, out: ASCII output, letter_case: .Lower or .Upper	usize throws(hex.HexError)	Encodes hex into caller-owned output.
hex.decode	decode(text: str) throws(hex.HexError | AllocError) -> ^[u8]	text: hex text	^[u8] throws(hex.HexError | AllocError)	Decodes lowercase or uppercase hex into owned bytes.
hex.decode_into	decode_into(text: str, out: &[u8]) throws(hex.HexError) -> usize	text, out: byte output	usize throws(hex.HexError)	Decodes into caller-owned output.

Status

std.encoding is the current public text encoding facade for Base64 and hex. For the full exported surface, see Standard Library Inventory.