# 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 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)
```