6.2. kink/BIN¶
6.2.1. type bin¶
`bin` is a finite length immutable byte array.
Elements of `bin` are integer `num` values 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`.
Example
:BIN.require_from('kink/')
stdout.print_line(BIN.of(0x00 0x01 0xff).size.repr) # => 3
6.2.1.2. Bin.any?¶
`any?` returns whether the size of `Bin` is greater than or equal to 1.
Example
:BIN.require_from('kink/')
stdout.print_line(BIN.of().any?.repr) # => false
stdout.print_line(BIN.of(0x00).any?.repr) # => true
6.2.1.3. Bin.get(Ind)¶
`get` returns the element at the index `Ind` in `Bin`.
The result is an integer `num` in the range [0x00, 0xff].
Precondition
`Ind` must be an integer `num` in the range [0, Bin.size).
Example
:BIN.require_from('kink/')
:Magic <- BIN.of(0xca 0xfe 0xba 0xbe)
stdout.print_line(Magic.get(1).repr) # => 254
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 integer `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 integer `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 integer `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 integer `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 a non-negative integer `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
`Bin2` must be a `bin` value.
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
`Bin2` must be a `bin` value.
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` representation of `Bin`.
The representation contains the elements as hexadecimal numbers, like `(bin 0x00 0x01 0xfe 0xff)`.
If the size of `Bin` is greater than 128, the representation is abbreviated by the first and the last 32 elements, with the total size between them.
Example
:BIN.require_from('kink/')
stdout.print_line(BIN.of(0 1 254 255).repr) # => (bin 0x00 0x01 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 its elements.
Precondition
Each element of `Nums` must be an integer `num` in the range [0x00, 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 the elements of `Eacher`.
Preconditions
`Eacher` must support the `.each($consume)` method, like vectors and iters.
Each element of `Eacher` must be an integer `num` in the range [0x00, 0xff].
Example
:BIN.require_from('kink/')
:Bin <- BIN.from_each([0 1 254 255])
stdout.print_line(Bin.repr) # => (bin 0x00 0x01 0xfe 0xff)