Encoding functions

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.

base58_decode

Reconstructs binary data from Bitcoin-alphabet Base58 text.

base58_decode(text:string) -> bytes

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

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

base58_encode

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

base58_encode(value:bytes|string) -> string

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

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

base64_decode

Decodes strictly padded Base64 text into its original byte sequence.

base64_decode(text:string) -> bytes

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

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

base64_decode_or_empty

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

base64_decode_or_empty(text:string) -> bytes

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

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

base64_encode

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

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

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

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

bin_decode

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

bin_decode(text:string) -> bytes

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

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

bin_encode

Displays input storage bytes as big-endian binary digits.

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

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

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

hex_decode

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

hex_decode(text:string) -> bytes

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

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

hex_encode

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

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

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

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

is_valid_utf8

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

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

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

is_valid_utf8(X 'C0AF')
-- → false

to_ascii

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

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

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

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

to_oct

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

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

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

to_oct(64)
-- → '100'