# Encoding functions

> 12 Encoding functions in NYXDB: names, aliases, signatures and behaviour.

{/* AUTO-GENERATED from the function catalog. DO NOT EDIT — overwritten on every build. */}

12 functions. Names resolve case-insensitively; an alias binds the same function as its canonical name. Each entry gives the signatures, the behaviour and an example.

| Function | Summary |
| --- | --- |
| [`base58_decode`](#base58_decode) | Reconstructs binary data from Bitcoin-alphabet Base58 text. |
| [`base58_encode`](#base58_encode) | Encodes raw bytes using the compact alphabet that omits visually ambiguous characters. |
| [`base64_decode`](#base64_decode) | Decodes strictly padded Base64 text into its original byte sequence. |
| [`base64_decode_or_empty`](#base64_decode_or_empty) | Recovers bytes from Base64 while replacing malformed encodings with empty binary output. |
| [`base64_encode`](#base64_encode) | Produces padded RFC-style Base64 text from a string’s UTF-8 bytes or binary data. |
| [`bin_decode`](#bin_decode) | Packs binary digit text into octets after padding the first incomplete byte. |
| [`bin_encode`](#bin_encode) | Displays input storage bytes as big-endian binary digits. |
| [`hex_decode`](#hex_decode) | Turns hexadecimal text into bytes, padding an odd leading digit with a zero nibble. |
| [`hex_encode`](#hex_encode) | Renders raw bytes or a numeric representation as uppercase hexadecimal digits. |
| [`is_valid_utf8`](#is_valid_utf8) | Checks whether an input byte sequence forms well-encoded Unicode UTF-8. |
| [`to_ascii`](#to_ascii) | Validates ASCII text or replaces non-ASCII Unicode characters with an explicit substitute. |
| [`to_oct`](#to_oct) | Formats an integer in base eight with an optional leading minus sign. |

## base58_decode

Reconstructs binary data from Bitcoin-alphabet Base58 text.

```text
base58_decode(text:string) -> bytes
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `bytes` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Reads Base58 digits with the specified alphabet and restores leading zero bytes represented by leading ones. NULL input yields NULL, while excluded characters or malformed text raise INVALID_ENCODING. Empty text decodes to empty bytes and no checksum or address validation is implied.

**Example**

```sql
base58_decode('Cn8eVZg')
-- → X'68656C6C6F'
```

## base58_encode

Encodes raw bytes using the compact alphabet that omits visually ambiguous characters.

```text
base58_encode(value:bytes|string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Converts byte input, or the UTF-8 bytes of a string, into the Bitcoin-specified Base58 alphabet. Leading zero bytes become leading alphabet-zero characters, preserving their count on decode. NULL returns NULL, and output beyond the value-size budget raises RESOURCE_LIMIT.

**Example**

```sql
base58_encode('hello')
-- → 'Cn8eVZg'
```

## base64_decode

Decodes strictly padded Base64 text into its original byte sequence.

```text
base64_decode(text:string) -> bytes
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `bytes` |
| Aliases | `base64Decode` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Requires the standard alphabet and valid padding instead of silently accepting malformed encodings. Invalid characters or padding raise INVALID_ENCODING, whereas SQL NULL returns NULL. A valid empty string produces empty bytes; decoded data need not be UTF-8 text.

**Example**

```sql
base64_decode('aGVsbG8=')
-- → X'68656C6C6F'
```

## base64_decode_or_empty

Recovers bytes from Base64 while replacing malformed encodings with empty binary output.

```text
base64_decode_or_empty(text:string) -> bytes
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `bytes` |
| Aliases | `try_base64_decode`, `tryBase64Decode` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Applies the strict Base64 alphabet and padding rules, but catches encoding failures and returns empty bytes. SQL NULL still returns NULL, so an invalid encoding differs from a missing input but not from valid empty data. RESOURCE_LIMIT and unrelated engine failures are not swallowed.

**Example**

```sql
base64_decode_or_empty('%%%')
-- → X''
```

## base64_encode

Produces padded RFC-style Base64 text from a string’s UTF-8 bytes or binary data.

```text
base64_encode(x:string|bytes) -> string
base64_encode(value:bytes|string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `base64Encode` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Uses the standard Base64 alphabet with equals-sign padding and no inserted line breaks. A string contributes its UTF-8 encoding, while bytes are consumed without interpretation. NULL propagates, empty input produces empty text, and an oversized encoded result raises RESOURCE_LIMIT.

**Example**

```sql
base64_encode('hello')
-- → 'aGVsbG8='
```

## bin_decode

Packs binary digit text into octets after padding the first incomplete byte.

```text
bin_decode(text:string) -> bytes
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `bytes` |
| Aliases | `unbin` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Reads zero and one characters, adding leading zero bits when the first group has fewer than eight digits. The result is raw bytes, including zero octets rather than a textual number. NULL yields NULL and any other character raises INVALID_ENCODING; empty input is accepted as empty bytes.

**Example**

```sql
bin_decode('101')
-- → X'05'
```

## bin_encode

Displays input storage bytes as big-endian binary digits.

```text
bin_encode(x:int*|uint*|bytes|fixed_string(N)) -> string
bin_encode(value:bytes|string|fixed_string(N)) -> string
bin_encode(value:I|float32|float64|date|datetime64(p,tz)|uuid) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `bin` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Textual input contributes its bytes, while signed integers use their complete two’s-complement representation. Integer output suppresses leading zero octets except for zero itself, rather than suppressing individual bits within an octet. NULL stays NULL; incompatible descriptors raise TYPE_MISMATCH and expansion beyond the byte budget raises RESOURCE_LIMIT.

**Example**

```sql
bin_encode(cast(5 AS UINT8))
-- → '00000101'
```

## hex_decode

Turns hexadecimal text into bytes, padding an odd leading digit with a zero nibble.

```text
hex_decode(text:string) -> bytes
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `bytes` |
| Aliases | `unhex` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Decodes upper- or lowercase hexadecimal digits without imposing text encoding on the result. An odd number of digits is interpreted as though one zero preceded the first digit. NULL propagates, empty text yields empty bytes, and nonhexadecimal characters raise INVALID_ENCODING.

**Example**

```sql
hex_decode('F')
-- → X'0F'
```

## hex_encode

Renders raw bytes or a numeric representation as uppercase hexadecimal digits.

```text
hex_encode(x:int*|uint*|string|bytes|fixed_string(N)|uuid) -> string
hex_encode(value:bytes|string|fixed_string(N)) -> string
hex_encode(value:I|float32|float64|date|datetime64(p,tz)|uuid) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `hex` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Strings are encoded from their UTF-8 bytes, and signed integers expose their fixed-width two’s-complement bits. Unsigned integer formatting uses the documented big-endian display order without unnecessary leading zero octets. NULL returns NULL; incompatible values raise TYPE_MISMATCH and oversized output raises RESOURCE_LIMIT.

**Example**

```sql
hex_encode('Hi')
-- → '4869'
```

## is_valid_utf8

Checks whether an input byte sequence forms well-encoded Unicode UTF-8.

```text
is_valid_utf8(value:bytes|string) -> bool
is_valid_utf8(string) -> bool
is_valid_utf8(bytes) -> bool
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `bool` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Validates complete UTF-8 sequences, rejecting truncated encodings, surrogate code points and overlong forms. Malformed bytes produce false rather than an exception, while SQL NULL produces NULL. The empty sequence is valid; arguments outside the string or bytes overloads raise TYPE_MISMATCH.

**Example**

```sql
is_valid_utf8(X 'C0AF')
-- → false
```

## to_ascii

Validates ASCII text or replaces non-ASCII Unicode characters with an explicit substitute.

```text
to_ascii(value:string) -> string
to_ascii(value:string,replacement:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/1..2-ary` |
| Returns | `string` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

The one-argument form rejects any scalar above U+007F with INVALID_ENCODING. The two-argument form replaces each such scalar with the supplied ASCII string, which may be empty but must itself contain only ASCII. NULL propagates; this operation neither transliterates letters nor guesses a legacy byte encoding.

**Example**

```sql
to_ascii('café', '?')
-- → 'caf?'
```

## to_oct

Formats an integer in base eight with an optional leading minus sign.

```text
to_oct(x:int*|uint*) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Produces octal digits without a base prefix, using a minus sign for negative signed values. Zero becomes a single zero character and SQL NULL remains NULL. A noninteger argument raises TYPE_MISMATCH; formatting preserves the integer’s exact magnitude rather than converting through floating point.

**Example**

```sql
to_oct(64)
-- → '100'
```

---

Source: https://nyxdb.io/docs/functions/encoding/