Bin

Binary data; an immutable sequence of bytes.

Implements: Index[Range[Int], Bin]

Constructor

Bin value

Accepts binary data or copies the UTF-8 bytes of a string.

Parameters

Name	Type	Description
value	(Bin | Str)	source bytes

Example

let data = Bin "hello"
assert_eq $data b"hello"

Fields

len @ Int ^[get]

Returns the byte length of the binary data.

Example

assert_eq (b"hello".len) 5
assert_eq (b"".len) 0

Methods

(index) range -> Bin

Returns the bytes in a range as a new binary value.

assert_eq (b"abcd"[1..3]) b"bc"
assert_eq (b"abcd"[..2]) b"ab"
assert_eq (b"abcd"[2..]) b"cd"
assert_eq (b"abcd"[..]) b"abcd"
assert_eq (b"foobar"[-3..]) b"bar"
assert_eq (b"abcd"[Range 0 4 2]) b"ac"
assert_eq (b"abcd"[Range nil nil -1]) b"dcba"

The range must lie within the value. Omitted start means 0, omitted end means the binary length, and negative endpoints count from the end. Negative steps reverse the slice.

Parameters

Name	Type	Description
range	Range[Int]

chomp() -> Bin

Removes one trailing line terminator.

One complete terminator — \r\n or \n, never a lone \r — and nothing else. Data without one is returned unchanged. Distinct from trim_end, which strips whitespace generally. Iterable.chomp does the same to each item of an iterable.

Example

assert_eq (b"line\n".chomp()) b"line"
assert_eq (b"line\r\n".chomp()) b"line"

contains needle -> Bool

Tests whether the binary data contains the given bytes.

Parameters

Name	Type	Description
needle	Bin	the bytes to find

Example

assert (b"hello".contains b"ell")
assert (b"hello".contains b"lo")
assert (!(b"hello".contains b"world"))
assert (b"hello".contains b"")

ends_with suffix -> Bool

Tests whether the binary data ends with the given suffix.

Parameters

Name	Type	Description
suffix	Bin	the suffix bytes

Example

assert (b"hello".ends_with b"lo")

join … -> Bin

Joins values from an input source using this binary data as a separator.

Parameters

Name	Type	Description
iter?	Iterable[Str | Bin]	iterable to join; uses the default input when omitted

Example

assert_eq (b",".join [b"a", b"b", b"c"]) b"a,b,c"

pack array -> Bin

Packs an array of integers (0-255) into binary data.

Parameters

Name	Type	Description
array	Array[Int]	array of integers (0-255)

Example

let bytes = Bin.pack [104, 101, 108, 108, 111]
assert_eq $bytes b"hello"

rsplit delimiter … -> UnpackIter[Bin]

Like split, but yields segments in right-to-left order. Mirrors str.rsplit.

Parameters

Name	Type	Description
delimiter	Bin	the delimiter bytes
:limit?	Int	max splits; negative means split from left

Example

assert_eq [...b"a,b,c".rsplit b","] [b"c", b"b", b"a"]
assert_eq [...b"a,b,c".rsplit b"," limit: 1] [b"c", b"a,b"]

split delimiter … -> UnpackIter[Bin]

Splits the binary data by the delimiter, returning an iterator that yields segments in left-to-right order.

The optional limit works identically to str.split: positive splits from the left, negative splits from the right (but still yields left-to-right).

Parameters

Name	Type	Description
delimiter	Bin	the delimiter bytes
:limit?	Int	max splits; negative means split from right

Example

assert_eq [...b"a,b,c".split b","] [b"a", b"b", b"c"]
assert_eq [...b"a,b,c".split b"," limit: 1] [b"a", b"b,c"]
let base ext = b"archive.tar.gz".split b"." limit: -1
assert_eq $base b"archive.tar"
assert_eq $ext b"gz"

starts_with prefix -> Bool

Tests whether the binary data starts with the given prefix.

Parameters

Name	Type	Description
prefix	Bin	the prefix bytes

Example

assert (b"hello".starts_with b"he")
assert (!(b"hello".starts_with b"lo"))

trim … -> Bin

Removes bytes (or specified characters) from both ends.

Parameters

Name	Type	Description
chars?	(Bin | Iterable[Bin])

Example

assert_eq (b"  hello  ".trim()) b"hello"
assert_eq (b"xxhelloxx".trim b"x") b"hello"
assert_eq (b"xyhelloyx".trim [b"x", b"y"]) b"hello"
assert_eq (b"\x00\xffdata\xff\x00".trim b"\x00\xff") b"data"

trim_end … -> Bin

Removes bytes (or specified characters) from the end.

Parameters

Name	Type	Description
chars?	(Bin | Iterable[Bin])

Example

assert_eq (b"  hello  ".trim_end()) b"  hello"
assert_eq (b"xxhelloxx".trim_end b"x") b"xxhello"

trim_start … -> Bin

Removes bytes (or specified characters) from the start.

Parameters

Name	Type	Description
chars?	(Bin | Iterable[Bin])

Example

assert_eq (b"  hello  ".trim_start()) b"hello  "
assert_eq (b"xxhelloxx".trim_start b"x") b"helloxx"

unpack() -> Seq[Int]

Returns an immutable view of the binary data's byte values.

The view retains the binary data without copying it. It supports len, positive and negative integer indexing, iteration, spreading, and positional destructuring. Elements are integers from 0 to 255. Range slices materialize independent, mutable arrays of integers. Use [...bytes.unpack()] to copy the whole view into a mutable array.

Example

let bytes = b"hello"
assert_eq [...bytes.unpack()] [104, 101, 108, 108, 111]

without_prefix prefix -> Bin

Returns the binary data with the prefix removed if it matches, otherwise returns the original data.

Parameters

Name	Type	Description
prefix	Bin	the prefix to remove

Example

assert_eq (b"hello".without_prefix b"he") b"llo"
assert_eq (b"hello".without_prefix b"xx") b"hello"

without_suffix suffix -> Bin

Returns the binary data with the suffix removed if it matches, otherwise returns the original data.

Parameters

Name	Type	Description
suffix	Bin	the suffix to remove

Example

assert_eq (b"hello".without_suffix b"lo") b"hel"