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"

Class Methods

`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"

`unpack value -> Array[Int]`

Unpacks any value that can be converted to binary into an array of byte values.

Example

assert_eq (bin.unpack b"hello") [104, 101, 108, 108, 111]

Methods

`(index) index`

Binary data accepts Range values for slicing by byte position:

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"

This returns a new binary value. Slice boundaries must be in bounds. Omitted start means 0, omitted end means the binary length, and negative endpoints count from the end. Negative steps reverse the slice.

Indexes the value.

`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.

Example

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

Iter.chomp lifts this over an iterator — it is exactly .map do |x| x.chomp(), with the mapping done inline. Distinct from trim_end, which strips whitespace generally.

`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"

`len() -> Int`

Returns the byte length of the binary data.

Example

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

`rsplit delimiter … -> Iter[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 … -> Iter[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() -> Array[Int]`

Unpacks binary data into an array of byte values (integers from 0-255).

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"