## Bzip2 interface

The module `Bz` provides a basic interface to the `bzip2` compression library.

### Datatypes & exceptions

`type in_channel`
`type out_channel`
`exception IO_error of string`

Exception `IO_error` is raised when there is an error reading or writing on a compressed channel ; the string argument is the message reported by the OS.

`exception Data_error`

Exception `Data_error` is raised when a data integrity error is detected during decompression.

`exception Unexpected_EOF`

Exception `Unexpected_EOF` is raised when an `in_channel` finishes before the logical end of stream is detected.

When any of these exception is raised, the channel is automatically closed (but you still have to close the Stdlib channel).

`val version : string`

Version of the underlying `bzip2` library.

### File I/O

#### File input

`val open_in : ?small:bool -> ?unused:bytes -> Stdlib.in_channel -> in_channel`

`open_in ic` opens a compressed stream reading from the `Stdlib` input channel `ic`.

- parameter small

  when `true` requests usage of a different method for decompressing that is slower but uses less memory. Defaults: `false`

`val read : in_channel -> bytes -> int -> int -> int`

`read buf pos len` reads up to `len` characters and store them in the string buffer `buf`, starting at position `pos`.

- returns

  number of bytes actually read, (a value strictly less than `len` means end of stream).

- raises `End_of_file`

  if end of stream was already reached.

`val read_get_unused : in_channel -> bytes`

If there's some data after the compressed stream that you want to read from the same `Stdlib` `in_channel`, use `read_get_unused`.

`val close_in : in_channel -> unit`

#### File output

`val open_out : ?block:int -> Stdlib.out_channel -> out_channel`

`open_out oc` creates an `out_channel` writing to the `Stdlib` output channel `oc`. Once the write operations are finished and the compressed channel is closed, it is possible to continue writing on the `Stdlib` channel. However, reading back requires special care (cf. above).

- parameter block

  block size to use for compresion. It is a value between 1 and 9 inclusive. 9 is the default and provides best compression but takes most memory.

`val write : out_channel -> bytes -> int -> int -> unit`

`write oc buf pos len` writes `len` characters, coming from `buf` and starting at position `pos`, to `oc`

`val close_out : out_channel -> unit`

### In-memory compression

These functions compress to/decompress from string buffers.

`val compress : ?block:int -> bytes -> int -> int -> bytes`

`compress buf pos len` compress a data chunk coming from `buf`, `len` character long, and starting at `pos`.

- returns

  compressed data chunk as string

`val uncompress : ?small:bool -> bytes -> int -> int -> bytes`

`uncompress buf pos len` uncompress a data chunk comfing from `buf`, `len` character long, and starting at `pos`.

- parameter small

  see `Bz2.open_in` above

- returns

  uncompressed data chunk as string