3.1. kink/BIN

Companion mod for bin vals.

3.1.1. type bin

A bin is a finite immutable byte array.

Elements of the bin are int nums 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.of(0xca 0xfe)

Bin.empty?

Bin.empty? returns whether the size of the Bin is zero.

Bin.nonempty?

Bin.nonempty? returns whether the size of the Bin is not zero.

Bin.size

Bin.size returns the number of elements of the Bin.

Bin.get(Ind)

Bin.get returns the specified element of the Bin.

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

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

Bin.slice(From_pos To_pos)

Bin.slice returns the specified slice of the Bin.

From_pos and To_pos must be int nums in the range [0, Bin.size]. From_pos must be less than or equal to To_pos.

The result is a bin the elements of which are copied from the slice of the Bin.

Example:

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

Bin.take_front(N)

Bin.take_front makes a bin containing the first N elements of the Bin.

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.of(0x25 0x50)

Bin.take_back(N)

Bin.take_back makes a bin containing the last N elements of the Bin.

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.of(0x46 0x2d)

Bin.drop_front(N)

Bin.drop_front makes a bin dropping the first N elements from the Bin.

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.of(0x44 0x46 0x2d)

Bin.drop_back(N)

Bin.drop_back makes a bin dropping the last N elements from the Bin.

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.of(0x25 0x50 0x44)

Bin.op_add(Arg_bin)

Bin.op_add makes a bin containing the elements of the Bin on the front, and the elements of the Arg_bin on the back.

Arg_bin 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.of(0xca 0xfe 0xba 0xbe)

Bin.op_mul(N)

Bin.op_mul makes a bin repeating the elements of the Bin N times.

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.of(0xba 0xbe 0xba 0xbe 0xba 0xbe)

Bin.decode(Encoding_name)

Bin.decode makes a str decoding the Bin using the character encoding.

Encoding_name must be a str of a valid character encoding on the runtime.

Example:

:BIN.require_from('kink/')
:Bin <- BIN.of(0x78 0x79 0x7a)
:Str <- Bin.decode('UTF-8')
stdout.print_line(Str.repr) # => "xyz"

Bin.op_eq(Arg_bin) Bin.op_ne(Arg_bin)

Bin.op_eq returns whether Bin and Arg_bin contain the same sequence of elements, and Bin.op_ne returns whether Bin and Arg_bin do not contain the same sequence of elements.

Arg_bin must be a bin.

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

Bin.op_lt(Arg_bin) Bin.op_le(Arg_bin) Bin.op_gt(Arg_bin) Bin.op_ge(Arg_bin)

The methods compare the two bins lexicographically, then return true or false.

Arg_bin must be a bin.

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

Bin.repr

Bin.repr returns a str such as "BIN.of(0xca 0xfe 0xba 0xbe)".

3.1.2. BIN.bin?(Val)

Returns whether the Val is a bin.

Example:

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

3.1.3. BIN.of(... Elems)

BIN.of makes a bin containing Elems as the elements.

Elems must be int nums in the range [0, 0xff].

Example:

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