bytes
Byte-level operations on the CX bytes scalar kind. Covers inspection and slicing, search, hex/base64/base32 encoding, gzip, zstd and bzip2 (decompress-only) 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:octets
[$bytes:octets] (b::bytes) -> [sequence int] — Every byte value, 0-255, as a sequence of ints in order (Python's list(b)); the empty value answers ().
[?lib 'cx-stdlib/bytes']
[$bytes:octets [$bytes:from-string-utf8 'abc']]
(97, 98, 99)
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 CXER2301 on non-hex input and on an odd number of hex digits.
[?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:deflate-raw
[$bytes:deflate-raw] -> bytes — Compress bytes to a raw RFC 1951 DEFLATE stream — no zlib header, no gzip frame, no checksum. This is the encoding the SAML HTTP-Redirect binding is defined over; gzip-decompress cannot read it.
[?lib 'cx-stdlib/bytes']
[$bytes:to-string-utf8 [$bytes:inflate-raw [$bytes:deflate-raw [$bytes:from-string-utf8 "hello world"]] {}]]
'hello world'
bytes:inflate-raw
[$bytes:inflate-raw] -> bytes — Decompress a raw RFC 1951 DEFLATE stream, BOUNDED by opts.max-bytes (1 MiB by default): a stream that would inflate past the bound raises CXER2307, and trailing bytes after the stream raise CXER2304. The bound is the caller's, because a compression ratio is not a size the sender gets to choose.
[?lib 'cx-stdlib/bytes']
[$bytes:to-string-utf8 [$bytes:inflate-raw [$bytes:deflate-raw [$bytes:from-string-utf8 "hello world"]] {}]]
'hello world'
bytes:bzip2-decompress
[$bytes:bzip2-decompress] -> bytes — Decompress a bzip2 stream, BOUNDED by opts.max-bytes (16 MiB by default): the stream's magic, its block-size marker, every block CRC and the stream CRC are checked, so a truncated or corrupted stream raises CXER2304 rather than answering partial output, and a stream that decompresses past the bound raises CXER2307 naming the bound in force. DECOMPRESS ONLY — there is no bzip2-compress, because a compressor whose output only this decoder has read back is not a claim worth shipping.
[?lib 'cx-stdlib/bytes']
[$bytes:to-string-utf8 [$bytes:bzip2-decompress [$bytes:from-hex "425a683931415926535944f7137800000191804000064490802000220334843021b68154278bb9229c2848227b89bc00"] {}]]
'hello world'
bytes:pack
[$bytes:pack] -> bytes — Pack values into bytes per a struct-style format string. A value outside its integer field's range (or a float with no integer value in it) raises CXER2306 naming the field and the value; it is never wrapped modulo the width.
[?lib 'cx-stdlib/bytes']
[$nth [$bytes:unpack "<I" [$bytes:pack "<I" (1234)]] 1]
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 "<I" [$bytes:pack "<I" (1234)]] 1]
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; a character past U+00FF raises CXER2303 naming it, never its code point's low byte.
[?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'