6.2. kink/BIN

Companion mod for bin vals.

6.2.1. type bin

`bin` is a finite length immutable byte array.

Elements of `bin` are int `num` vals in the range [0x00, 0xff].

Example

:BIN.require_from('kink/')
:Magic <- BIN.of(0xca 0xfe 0xba 0xbe)
:Slice <- Magic.take_front(2)
stdout.print_line(Slice.repr) # => (bin 0xca 0xfe)

6.2.1.1. Bin.size

`size` returns a `num` of the number of elements of `Bin`.

6.2.1.2. Bin.any?

`any?` returns whether the size of `Bin` is greater than or equal to 1.

6.2.1.3. Bin.get(Ind)

`get` returns the element at the index `Ind` in `Bin`.

The result is an int `num` in the range [0, 0xff].

Precondition

`Ind` must be an int `num` in the range [0, Bin.size).

6.2.1.4. Bin.slice(From To)

`slice` returns a `bin` of the slice in the range [From, To).

Preconditions

`From` and `To` must be integer `num` values.

0 <= From <= To <= Bin.size

Example

:BIN.require_from('kink/')

:Magic <- BIN.of(0xca 0xfe 0xba 0xbe)
:Slice <- Magic.slice(1 3)
stdout.print_line(Slice.repr) # => (bin 0xfe 0xba)

6.2.1.5. Bin.take_front(N)

`take_front` returns a `bin` that is a slice of the first `N` elements of `Bin`.

Precondition

`N` must be an int `num` in the range [0, Bin.size].

Example

:BIN.require_from('kink/')
:Pdf_signature <- BIN.of(0x25 0x50 0x44 0x46 0x2d)
:Slice <- Pdf_signature.take_front(2)
stdout.print_line(Slice.repr) # => (bin 0x25 0x50)

6.2.1.6. Bin.take_back(N)

`take_back` returns a `bin` that is a slice of the last `N` elements of `Bin`.

Precondition

`N` must be an int `num` in the range [0, Bin.size].

Example

:BIN.require_from('kink/')
:Pdf_signature <- BIN.of(0x25 0x50 0x44 0x46 0x2d)
:Slice <- Pdf_signature.take_back(2)
stdout.print_line(Slice.repr) # => (bin 0x46 0x2d)

6.2.1.7. Bin.drop_front(N)

`drop_front` returns a `bin` that is a slice excluding the first `N` elements of `Bin`.

Precondition

`N` must be an int `num` in the range [0, Bin.size].

Example

:BIN.require_from('kink/')
:Pdf_signature <- BIN.of(0x25 0x50 0x44 0x46 0x2d)
:Slice <- Pdf_signature.drop_front(2)
stdout.print_line(Slice.repr) # => (bin 0x44 0x46 0x2d)

6.2.1.8. Bin.drop_back(N)

`drop_back` returns a `bin` that is a slice excluding the last `N` elements of `Bin`.

Precondition

`N` must be an int `num` in the range [0, Bin.size].

Example

:BIN.require_from('kink/')
:Pdf_signature <- BIN.of(0x25 0x50 0x44 0x46 0x2d)
:Slice <- Pdf_signature.drop_back(2)
stdout.print_line(Slice.repr) # => (bin 0x25 0x50 0x44)

6.2.1.9. Bin1 + Bin2

`+` operator, or `op_add` method, returns a `bin` containing the elements of `Bin1` on the front, and the elements of `Bin2` on the back.

Precondition

`Bin2` must be a `bin`.

Example

:BIN.require_from('kink/')
:Cafe <- BIN.of(0xca 0xfe)
:Babe <- BIN.of(0xba 0xbe)
:Cafe_babe <- Cafe + Babe
stdout.print_line(Cafe_babe.repr) # => (bin 0xca 0xfe 0xba 0xbe)

6.2.1.10. Bin * N

`*` operator, or `op_mul` method, returns a `bin` repeating the elements of `Bin`, `N` times.

Precondition

`N` must be an int `num`.

Example

:BIN.require_from('kink/')
:Babe <- BIN.of(0xba 0xbe)
:Babe_babe_babe <- Babe * 3
stdout.print_line(Babe_babe_babe.repr) # => (bin 0xba 0xbe 0xba 0xbe 0xba 0xbe)

6.2.1.11. Bin1 == Bin2

`==` operator, or `op_eq` method, returns whether `Bin1` and `Bin2` contain the same sequence of elements.

Precondition

`Bin1` and `Bin2` must be `bin` type.

Example

:BIN.require_from('kink/')
:Bin <- BIN.of(1 2 3)

stdout.print_line((Bin == BIN.of(1 2 3)).repr)  # => true
stdout.print_line((Bin != BIN.of(1 2 3)).repr)  # => false

stdout.print_line((Bin == BIN.of(3 2 1)).repr)  # => false
stdout.print_line((Bin != BIN.of(3 2 1)).repr)  # => true

6.2.1.12. Bin1 <= Bin2

`<=` operator, or `op_le` method, returns whether `Bin1` is smaller than or equal to `Bin2` lexicographically.

Precondition

`Bin1` and `Bin2` must be `bin` values.

Example

:BIN.require_from('kink/')

:compare <- {(:Bin :Arg_bin)
  [:Lt? :Le? :Gt? :Ge?] = [
    Bin < Arg_bin
    Bin <= Arg_bin
    Bin > Arg_bin
    Bin >= Arg_bin
  ]
  stdout.print_line(
    'Lt?={} Le?={} Gt?={} Ge?={}'.format(Lt?.repr Le?.repr Gt?.repr Ge?.repr))
}

compare(BIN.of(1 2 3) BIN.of(1 2 3))    # => Lt?=false Le?=true Gt?=false Ge?=true
compare(BIN.of(1 2 3) BIN.of(1 2 3 4))  # => Lt?=true Le?=true Gt?=false Ge?=false
compare(BIN.of(1 2 3) BIN.of(1 2))      # => Lt?=false Le?=false Gt?=true Ge?=true

6.2.1.13. Bin.repr

`repr` returns a str like "(bin 0xca 0xfe 0xba 0xbe)", or "(bin 0x01 0x02 0x03 ,,, size=999 ,,, 0xfd 0xfe 0xff)"

6.2.2. BIN.is?(Val)

`is?` returns whether `Val` is a `bin`.

Example

:BIN.require_from('kink/')
:Bin <- BIN.of(1 2 3)
stdout.print_line(BIN.is?(Bin).repr) # => true
stdout.print_line(BIN.is?(42).repr)  # => false

6.2.3. BIN.of(... Nums)

`of` returns a `bin` containing `Nums` as the elements.

Precondition

Each element of `Nums` must be an int `num` in the range [0, 0xff].

Example

:BIN.require_from('kink/')

:Bin <- BIN.of(0 1 254 255)
stdout.print_line(Bin.repr) # => (bin 0x00 0x01 0xfe 0xff)

6.2.4. BIN.from_each(Eacher)

`from_each` returns a `bin` containing elements of `Eacher`.

Preconditions

`Eacher` must support .each($consume) method like vectors and iters.

Each element of `Eacher` must be an int `num` in the range [0, 0xff].

Example

:BIN.require_from('kink/')

:Bin <- BIN.from_each([0 1 254 255])
stdout.print_line(Bin.repr) # => (bin 0x00 0x01 0xfe 0xff)