bytes
Byte-level operations on the CX bytes scalar kind. Covers inspection and slicing, search, hex/base64/base32 encoding, gzip and zstd compression, fixed-width binary pack and unpack, and UTF-8/Latin-1 string conversion. All operations are pure with no I/O, and every result is a new immutable bytes value. For file and stream I/O see cx-stdlib/io.
bytes:length
[$bytes:length] -> int — Return the number of bytes in a bytes value.
[?lib 'cx-stdlib/bytes']
[$bytes:length [$bytes:from-hex "deadbeef"]]
4
bytes:at
[$bytes:at] -> int — Return the byte value 0-255 at an index; raises if out of bounds.
[?lib 'cx-stdlib/bytes']
[$bytes:at [$bytes:from-string-utf8 "ABC"] 0]
65
bytes:is-empty
[$bytes:is-empty] -> bool — Report whether a bytes value has zero length.
[?lib 'cx-stdlib/bytes']
[$bytes:is-empty [$bytes:from-hex ""]]
true
bytes:equals
[$bytes:equals] -> bool — Report whether two bytes values are byte-for-byte equal.
[?lib 'cx-stdlib/bytes']
[$bytes:equals [$bytes:from-hex "00ff"] [$bytes:from-hex "00ff"]]
true
bytes:constant-time-equals
[$bytes:constant-time-equals] -> bool — Compare two bytes values for equality in constant time, resistant to timing attacks.
[?lib 'cx-stdlib/bytes']
[$bytes:constant-time-equals [$bytes:from-hex "abcd"] [$bytes:from-hex "abcd"]]
true
bytes:slice
[$bytes:slice] -> bytes — Extract a half-open byte range; bounds clamp and negative indices count from the end.
[?lib 'cx-stdlib/bytes']
[$bytes:to-hex [$bytes:slice [$bytes:from-hex "00112233"] 1 3]]
'1122'
bytes:head
[$bytes:head] -> bytes — Return the first n bytes.
[?lib 'cx-stdlib/bytes']
[$bytes:to-hex [$bytes:head [$bytes:from-hex "00112233"] 2]]
'0011'
bytes:tail
[$bytes:tail] -> bytes — Return the last n bytes.
[?lib 'cx-stdlib/bytes']
[$bytes:to-hex [$bytes:tail [$bytes:from-hex "00112233"] 2]]
'2233'
bytes:concat
[$bytes:concat] -> bytes — Concatenate a sequence of bytes values into one; raises if the result exceeds the length ceiling.
[?lib 'cx-stdlib/bytes']
[$bytes:to-hex [$bytes:concat ([$bytes:from-hex "0011"], [$bytes:from-hex "2233"])]]
'00112233'
bytes:repeat
[$bytes:repeat] -> bytes — Concatenate n copies of a bytes value; raises if the result exceeds the length ceiling.
[?lib 'cx-stdlib/bytes']
[$bytes:to-hex [$bytes:repeat [$bytes:from-hex "ab"] 3]]
'ababab'
bytes:find
[$bytes:find] -> int — Return the index of the first occurrence of a needle in the haystack, or -1 if absent.
[?lib 'cx-stdlib/bytes']
[$bytes:find [$bytes:from-string-utf8 "hello world"] [$bytes:from-string-utf8 "hello"]]
0
bytes:contains
[$bytes:contains] -> bool — Report whether the haystack contains the needle.
[?lib 'cx-stdlib/bytes']
[$bytes:contains [$bytes:from-string-utf8 "hello world"] [$bytes:from-string-utf8 "o w"]]
true
bytes:starts-with
[$bytes:starts-with] -> bool — Report whether a bytes value begins with the given prefix.
[?lib 'cx-stdlib/bytes']
[$bytes:starts-with [$bytes:from-string-utf8 "hello"] [$bytes:from-string-utf8 "he"]]
true
bytes:ends-with
[$bytes:ends-with] -> bool — Report whether a bytes value ends with the given suffix.
[?lib 'cx-stdlib/bytes']
[$bytes:ends-with [$bytes:from-string-utf8 "hello"] [$bytes:from-string-utf8 "lo"]]
true
bytes:split
[$bytes:split] -> [sequence bytes] — Split a bytes value on each occurrence of a separator.
[?lib 'cx-stdlib/bytes']
[$bytes:to-string-utf8 [$nth [$bytes:split [$bytes:from-string-utf8 "a,b,c"] [$bytes:from-string-utf8 ","]] 3]]
'c'
bytes:to-hex
[$bytes:to-hex] -> string — Encode bytes as a lowercase hexadecimal string.
[?lib 'cx-stdlib/bytes']
[$bytes:to-hex [$bytes:from-hex "deadbeef"]]
'deadbeef'
bytes:from-hex
[$bytes:from-hex] -> bytes — Decode a hexadecimal string (either case) to bytes; raises on non-hex input.
[?lib 'cx-stdlib/bytes']
[$bytes:to-hex [$bytes:from-hex "deadbeef"]]
'deadbeef'
bytes:to-hex-upper
[$bytes:to-hex-upper] -> string — Encode bytes as an uppercase hexadecimal string.
[?lib 'cx-stdlib/bytes']
[$bytes:to-hex-upper [$bytes:from-hex "deadbeef"]]
'DEADBEEF'
bytes:to-base64
[$bytes:to-base64] -> string — Encode bytes as standard padded RFC 4648 base64.
[?lib 'cx-stdlib/bytes']
[$bytes:to-string-utf8 [$bytes:from-base64 [$bytes:to-base64 [$bytes:from-string-utf8 "hello"]]]]
'hello'
bytes:to-base64-url
[$bytes:to-base64-url] -> string — Encode bytes as URL-safe unpadded RFC 4648 base64.
[?lib 'cx-stdlib/bytes']
[$bytes:to-base64-url [$bytes:from-string-utf8 "hi"]]
'aGk'
bytes:from-base64
[$bytes:from-base64] -> bytes — Decode a standard base64 string to bytes, tolerating padded or unpadded input; raises on malformed input.
[?lib 'cx-stdlib/bytes']
[$bytes:to-string-utf8 [$bytes:from-base64 [$bytes:to-base64 [$bytes:from-string-utf8 "hello"]]]]
'hello'
bytes:from-base64-url
[$bytes:from-base64-url] -> bytes — Decode a URL-safe base64 string to bytes, tolerating padded or unpadded input; raises on malformed input.
[?lib 'cx-stdlib/bytes']
[$bytes:to-string-utf8 [$bytes:from-base64-url [$bytes:to-base64-url [$bytes:from-string-utf8 "hello"]]]]
'hello'
bytes:to-base32
[$bytes:to-base32] -> string — Encode bytes as uppercase padded RFC 4648 base32.
[?lib 'cx-stdlib/bytes']
[$bytes:to-string-utf8 [$bytes:from-base32 [$bytes:to-base32 [$bytes:from-string-utf8 "hello"]]]]
'hello'
bytes:from-base32
[$bytes:from-base32] -> bytes — Decode an RFC 4648 base32 string to bytes.
[?lib 'cx-stdlib/bytes']
[$bytes:to-string-utf8 [$bytes:from-base32 [$bytes:to-base32 [$bytes:from-string-utf8 "hello"]]]]
'hello'
bytes:to-base58
[$bytes:to-base58] -> string — Encode bytes as a base58btc string (Bitcoin alphabet), the multibase 'z' payload used for did:key.
bytes:from-base58
[$bytes:from-base58] -> bytes — Decode a base58btc string (Bitcoin alphabet) to bytes; raises on characters outside the alphabet.
bytes:gzip-compress
[$bytes:gzip-compress] -> bytes — Compress bytes into a gzip frame (RFC 1952, default level 6).
[?lib 'cx-stdlib/bytes']
[$bytes:length [$bytes:gzip-decompress [$bytes:gzip-compress [$bytes:from-hex ""]]]]
0
bytes:gzip-decompress
[$bytes:gzip-decompress] -> bytes — Decompress a gzip frame back to bytes; raises on malformed input.
[?lib 'cx-stdlib/bytes']
[$bytes:length [$bytes:gzip-decompress [$bytes:gzip-compress [$bytes:from-hex ""]]]]
0
bytes:zstd-compress
[$bytes:zstd-compress] -> bytes — Compress bytes with zstd (RFC 8478, default level 3).
[?lib 'cx-stdlib/bytes']
[$bytes:to-string-utf8 [$bytes:zstd-decompress [$bytes:zstd-compress [$bytes:from-string-utf8 "hello world"]]]]
'hello world'
bytes:zstd-decompress
[$bytes:zstd-decompress] -> bytes — Decompress zstd-compressed bytes; raises on malformed input.
[?lib 'cx-stdlib/bytes']
[$bytes:to-string-utf8 [$bytes:zstd-decompress [$bytes:zstd-compress [$bytes:from-string-utf8 "hello world"]]]]
'hello world'
bytes:zstd-compress-with-level
[$bytes:zstd-compress-with-level] -> bytes — Compress bytes with zstd at an explicit level from 1 to 22.
[?lib 'cx-stdlib/bytes']
[$bytes:to-string-utf8 [$bytes:zstd-decompress [$bytes:zstd-compress-with-level [$bytes:from-string-utf8 "hello world"] 22]]]
'hello world'
bytes:pack
[$bytes:pack] -> bytes — Pack values into bytes per a struct-style format string.
[?lib 'cx-stdlib/bytes']
[$nth [$bytes:unpack "
1234
bytes:unpack
[$bytes:unpack] -> [sequence any] — Unpack bytes into a sequence of values per a struct-style format string.
[?lib 'cx-stdlib/bytes']
[$nth [$bytes:unpack "
1234
bytes:from-string-utf8
[$bytes:from-string-utf8] -> bytes — Encode a string to its UTF-8 byte representation.
[?lib 'cx-stdlib/bytes']
[$bytes:to-hex [$bytes:from-string-utf8 "abc"]]
'616263'
bytes:to-string-utf8
[$bytes:to-string-utf8] -> string — Decode bytes as a UTF-8 string; raises on invalid UTF-8.
[?lib 'cx-stdlib/bytes']
[$bytes:to-string-utf8 [$nth [$bytes:split [$bytes:from-string-utf8 "a,b,c"] [$bytes:from-string-utf8 ","]] 3]]
'c'
bytes:to-string-utf8-lossy
[$bytes:to-string-utf8-lossy] -> string — Decode bytes as UTF-8, replacing each invalid run with U+FFFD; never raises.
[?lib 'cx-stdlib/bytes']
[$bytes:length [$bytes:from-string-utf8 [$bytes:to-string-utf8-lossy [$bytes:from-hex "ff"]]]]
3
bytes:from-string-latin1
[$bytes:from-string-latin1] -> bytes — Encode a string to Latin-1 bytes for byte-clean round-trips.
[?lib 'cx-stdlib/bytes']
[$bytes:to-hex [$bytes:from-string-latin1 [$bytes:to-string-latin1 [$bytes:from-hex "00ff80"]]]]
'00ff80'
bytes:to-string-latin1
[$bytes:to-string-latin1] -> string — Decode bytes as Latin-1, preserving every byte.
[?lib 'cx-stdlib/bytes']
[$bytes:to-hex [$bytes:from-string-latin1 [$bytes:to-string-latin1 [$bytes:from-hex "00ff80"]]]]
'00ff80'