Encoding

`encoding` — API Reference

Import: std/encoding.axs

Binary-to-text encoding and decoding for hex, base64 (RFC 4648), URL percent-encoding (RFC 3986), and base32 (RFC 4648).

All functions are implemented in pure Axon using existing runtime primitives — no additional C FFI beyond what std/string and std/mem already provide.

Encoding Functions

Hex

hex_encode(data: (ptr u8), data_len: i64) → string

Encode raw bytes as lower-case hexadecimal. Each byte produces two hex characters.

;; Example: [0x48, 0x65, 0x6c] → "48656c"
(call hex_encode buf (i64 3))

Base64

base64_encode(data: (ptr u8), data_len: i64) → string

Encode raw bytes to base64 using the standard RFC 4648 alphabet (A-Za-z0-9+/) with = padding.

;; Example: "Man" (77, 97, 110) → "TWFu"
(call base64_encode buf (i64 3))

URL Percent-Encoding

url_encode(s: string) → string

Percent-encode a string per RFC 3986. Unreserved characters (A-Za-z0-9-_.~) pass through unchanged; all others become %XX (upper-case hex).

;; Example: "hello world" → "hello%20world"
(call url_encode (str "hello world"))

Base32

base32_encode(data: (ptr u8), data_len: i64) → string

Encode raw bytes to base32 using the standard RFC 4648 alphabet (A-Z2-7) with = padding.

;; Example: "foo" (102, 111, 111) → "MZXW6==="
(call base32_encode buf (i64 3))

Decoding Functions

All decode functions return a 2-element (ptr i64) header containing [ptr, len]. Use the convenience accessors below to extract results. On invalid input, both elements are set to 0.

Hex Decode

hex_decode(s: string) → (ptr i64)

Decode a hex string to raw bytes. Accepts both upper and lower-case hex digits. Returns empty result for odd-length or invalid input.

Base64 Decode

base64_decode(s: string) → (ptr i64)

Decode a base64 string to raw bytes. Input length must be a multiple of 4. Returns empty result for invalid input.

URL Percent-Decode

url_decode(s: string) → string

Decode a percent-encoded string. Converts %XX escapes back to their byte values. Also converts + to space (form-encoding compat). Returns the decoded string directly (not a header).

Base32 Decode

base32_decode(s: string) → (ptr i64)

Decode a base32 string to raw bytes. Case-insensitive (a-z treated as A-Z). Input length must be a multiple of 8. Returns empty result for invalid input.

Decode Result Accessors

These convenience functions extract data from the 2-element header returned by hex_decode, base64_decode, and base32_decode.

decode_ptr(hdr: (ptr i64)) → (ptr u8)

Get the pointer to the decoded byte buffer.

decode_len(hdr: (ptr i64)) → i64

Get the length of the decoded data.

decode_to_str(hdr: (ptr i64)) → string

Convert the decoded bytes to an Axon string (via str_from_buf).

Public Functions Summary (11)

Function	Signature	Return Type
`hex_encode`	`(data: (ptr u8), data_len: i64)`	`string`
`hex_decode`	`(s: string)`	`(ptr i64)`
`base64_encode`	`(data: (ptr u8), data_len: i64)`	`string`
`base64_decode`	`(s: string)`	`(ptr i64)`
`url_encode`	`(s: string)`	`string`
`url_decode`	`(s: string)`	`string`
`base32_encode`	`(data: (ptr u8), data_len: i64)`	`string`
`base32_decode`	`(s: string)`	`(ptr i64)`
`decode_ptr`	`(hdr: (ptr i64))`	`(ptr u8)`
`decode_len`	`(hdr: (ptr i64))`	`i64`
`decode_to_str`	`(hdr: (ptr i64))`	`string`

FFI Extern Declarations (6)

These are private C/system function bindings used internally by the module.

Symbol	Parameters	Return Type
`malloc`	`i64`	`(ptr u8)`
`free`	`(ptr u8)`	`void`
`str_len`	`string`	`i64`
`str_char_at`	`string, i64`	`i64`
`str_from_buf`	`(ptr void), i64`	`string`
`str_concat`	`string, string`	`string`

Internal Functions (6)

These functions are module-private and not accessible via import.

Function	Parameters	Return Type
`char_to_str`	`(c: i64)`	`string`
`hex_nibble`	`(n: i64)`	`i64`
`hex_val`	`(c: i64)`	`i64`
`b64_char`	`(idx: i64)`	`i64`
`b64_val`	`(c: i64)`	`i64`
`is_unreserved`	`(c: i64)`	`i64`
`pct_nibble`	`(n: i64)`	`i64`
`b32_char`	`(idx: i64)`	`i64`
`b32_val`	`(c: i64)`	`i64`

Performance Notes

The current implementation is optimized for correctness and clarity, not for maximum throughput. All encode functions build output via repeated str_concat which is O(n²) for large inputs. For performance-critical encoding of large payloads (>1KB), consider:

Using malloc + direct buffer writes + a single str_from_buf call
Implementing a lookup-table approach for hex/base64 char mapping

For typical use cases (encoding API keys, tokens, small messages), the current implementation is adequate.

Auto-generated from std/encoding.axs by scripts/gen_docs.sh