package decompress

  1. Overview
  2. Docs
Legend:
Library
Module
Module type
Parameter
Class
Class type
type decoder

The type for decoders.

type src = [
  1. | `Channel of in_channel
  2. | `String of string
  3. | `Manual
]

The type for input sources. With a `Manual source the client must provide input with src. With `String or `Channel source the client can safely discard `Await case (with assert false).

type signal = [
  1. | `Await of decoder
  2. | `Flush of decoder
  3. | `End of decoder
  4. | `Malformed of string
]
val decoder : src -> o:bigstring -> allocate:(int -> window) -> decoder

decoder src ~o ~allocate is a decoder that inputs from src.

Output buffer.

zl, as de, uses o buffer as internal buffer to store output. We recommend to allocate an io_buffer_size buffer as output buffer. Then, dst_rem decoder tells you how many unused bytes remain in o.

Window.

ZLIB has a header to specify the window size needed to inflate a given input. When zl knows that, it calls allocate with a number bits so that 1 lsl bits is the size of the window. bits can not be larger than 15 nor lower than 8. allocate can be fun bits -> De.make_window ~bits or a previously allocated window. decoder will take the ownership on it!

Ownership in our case means that decode will mutate it in-place and expect it to remain unchanged between invocations.

val decode : decoder -> signal

decode d0 is:

  • `Await d1 if d0 has a `Manual input source and awaits for more input. The client must use a src with d1 to provide it.
  • `Flush d1 if given output buffer o (see decoder) needs to be drained before work can be resumed. The client must use flush with d1 to completely flush o. Usually o will be full and consist fully of bytes that need to be copied from the buffer, but sometimes only the first part of the buffer is used. In those cases dst_rem will give you the amount of free/unused bytes remain in o. These should not be copied since their contents are not part of the output. Instead, the first bigstring_length o - Inf.dst_rem d1 bytes should be copied when flushing o.
  • `Malformed err if given input is malformed. err is a human-readable error message.
  • `End d1 if given input notify end of flow. o is possibly not empty (it can be check with dst_rem).
val reset : decoder -> decoder

reset d is a d in its original state, as it was initialized by decoder.

val src : decoder -> bigstring -> int -> int -> decoder

src d s j l provides d with l bytes to read, starting at j in s. This byte range is read by calls to decode with d until `Await is returned. To signal the end of input call the function with l = 0.

val dst_rem : decoder -> int

dst_rem d is how many unused bytes remain in the output buffer of d.

val src_rem : decoder -> int

src_rem d is how many unprocessed bytes remain in the input buffer of d.

val write : decoder -> int

write d is how many bytes d emitted since it was created.

val flush : decoder -> decoder

flush d is a decoder where internal output buffer o is completely free to store bytes.

OCaml

Innovation. Community. Security.