Utilities

Low-level helpers for encoding/decoding binary data and text.

All functions treat string as a raw byte container, so they work fine with binary data (including \0 bytes and non-UTF8).

Functions

string util_base64_encode(const string &in data)
bool   util_base64_decode(const string &in text, string &out data, string &out error)

string util_hex_encode(const string &in data)
bool   util_hex_decode(const string &in text, string &out data, string &out error)

string util_url_encode(const string &in data)
string util_url_decode(const string &in data)

---

Base64 helpers

string util_base64_encode(const string &in data)

Encodes arbitrary data as Base64 text.

• Parameters

  • data — Input bytes to encode (any string, including binary).

• Returns

  • Base64-encoded text using the standard alphabet A–Z a–z 0–9 + / with = padding.

Example

string original = "hello";
string enc = util_base64_encode(original);
log("Base64 = " + enc);   // "aGVsbG8="

---

bool util_base64_decode(const string &in text, string &out data, string &out error)

Decodes a Base64 string back into raw bytes.

• Parameters

  • text — Base64 text to decode.

  • data (out) — Output decoded bytes on success.

  • error (out) — Error message when returning false.

• Returns

  • true on success, false on error.

On success

• data contains decoded bytes.

• error is empty.

On failure

• data is empty.

• error contains a human-readable message (e.g. "Invalid base64 character").

Example

string src = "aGVsbG8=";
string raw, err;

if (util_base64_decode(src, raw, err))
{
    log("decoded = " + raw);   // "hello"
}
else
{
    log_error("base64 decode failed: " + err);
}

Error example

string bad = "aGVsbG8$";       // invalid char
string data, err;
bool ok = util_base64_decode(bad, data, err);
// ok  == false
// err == "Invalid base64 character"

---

Hex helpers

string util_hex_encode(const string &in data)

Encodes binary data as uppercase hexadecimal text.

• Parameters

  • data — Raw bytes to encode.

• Returns

  • Hex string using 0–9 A–F. Each byte becomes 2 characters.

Example

string original = "hello";
string hex = util_hex_encode(original);
log("hex = " + hex);      // "68656C6C6F"

---

bool util_hex_decode(const string &in text, string &out data, string &out error)

Decodes a hex string back into raw bytes.

• Parameters

Name	Type	Description
text	string	Hex text (must have even length)
data	string (out)	Output decoded bytes on success
error	string (out)	Error message when returning false

• Returns

  • true on success, false on error.

On success

• data contains decoded bytes.

• error is empty.

On failure

• data is empty.

• error contains a message.

Example

string hex = "68656C6C6F";
string raw, err;

if (util_hex_decode(hex, raw, err))
{
    log("raw = " + raw);   // "hello"
}
else
{
    log_error("hex decode failed: " + err);
}

Error examples

// 1) Odd length
string bad1  = "ABC";
string data1, err1;
bool ok1 = util_hex_decode(bad1, data1, err1);
// ok1  == false
// err1 == "Hex string length must be even"

// 2) Invalid characters
string bad2  = "GGGG";
string data2, err2;
bool ok2 = util_hex_decode(bad2, data2, err2);
// ok2  == false
// err2 == "Invalid hex character"

---

URL helpers

These functions use standard URL percent-encoding:

• Unreserved characters stay as-is: A–Z a–z 0–9 - _ . ~

• Everything else becomes %XX (hex byte).

Note: util_url_decode does not convert + to space. + is treated as a normal character.

string util_url_encode(const string &in data)

Percent-encodes a string for safe use in URLs (query params, etc).

• Parameters

  • data — Input string (can be binary, but typically text).

• Returns

  • URL-encoded string.

Example

string original = "hello world! 100% ok?";
string enc = util_url_encode(original);
// Example: "hello%20world%21%20100%25%20ok%3F"

log("url encoded = " + enc);

---

string util_url_decode(const string &in data)

Decodes %XX sequences back into raw bytes.

• Parameters

  • data — URL-encoded string (e.g. "hello%20world").

• Returns

  • Decoded string with %XX sequences converted to bytes.

  • Invalid % sequences are left as literal characters.

Example

string url = "name=John%20Doe&msg=hello%21";
string decoded = util_url_decode(url);
// "name=John Doe&msg=hello!"

log("url decoded = " + decoded);

---

Roundtrip examples

Base64 roundtrip

string original = "The quick brown fox.";
string enc = util_base64_encode(original);
string dec, err;

if (util_base64_decode(enc, dec, err) && dec == original)
{
    log("Base64 roundtrip OK");
}
else
{
    log_error("Base64 roundtrip failed: " + err);
}

Hex roundtrip

string original = "hello world!";
string hex = util_hex_encode(original);
string raw, err;

if (util_hex_decode(hex, raw, err) && raw == original)
{
    log("Hex roundtrip OK");
}
else
{
    log_error("Hex roundtrip failed: " + err);
}

URL roundtrip

string original = "[email protected]&msg=hi there!";
string enc = util_url_encode(original);
string dec = util_url_decode(enc);

if (dec == original)
{
    log("URL roundtrip OK");
}
else
{
    log_error("URL roundtrip failed");
}

---

Binary safety

All util_* functions operate on string as byte containers:

• You can safely encode/decode binary data.

• Data with \0 bytes is preserved.

• Non-UTF8 content is preserved.

Useful for:

• Network packets

• Encryption keys

• Hash outputs

• Serialized structs / blobs