Module Gz.Inf

type decoder

The type for decoders.

type src = [
| `Channel of in_channel
| `String of string
| `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 = [
| `Await of decoder
| `Flush of decoder
| `End of decoder
| `Malformed of string
]
val decoder : src -> o:bigstring -> decoder

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

Output buffer.

gz, 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.

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.

  • raises Invalid_argument

    when j and l do not correspond to a valid range.

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.

val filename : decoder -> string option

filename d returns the filename of the flow if it exists. This can be called anytime but should be called when the `End case appears (and ensure that the GZIP header was computed).

val comment : decoder -> string option

comment d returns the comment of the flow if it exists. This can be called anytime but should be called when the `End case appears (and ensure that the GZIP header was computed).

val os : decoder -> os

os d returns the os where the flow was compressed. It should be called when the `End case appears (and ensure that the GZIP header was computed).

val extra : key:string -> decoder -> string option

extra ~key d returns extra field key if it exists. This can be called anytime but should be called when the `End case appears (and ensure that the GZIP header was computed).

  • raises Invalid_argument

    if the length of the given key is not equal to 2.