Incoming byte stream type.

Flatten bytes-oriented Bigarray buffer.

Note. The rationale for using bytes instead of BA is to transparently transfer memory between the OCaml runtime and external functions, which are necessary for working with input/output.

A byte chunk is a non-empty consecutive range of bytes in a buffer value.

make ?overlap_size reader

Construct incoming byte stream from reader.

• parameter reader

  This is a function that reads chunks from a source. It raises the End_of_file exception when the end of the source is reached.

• parameter ?overlap_size

  By default, a buffer of 0xFF bytes is allocated to resolve data gaps between chunks, which are used to provide linear memory buffers.

Note. The buffer within a chunk is made available to third parties for a limited period of time during which the chunk is considered valid for reading or writing (or both).

See also, the make' function allows you to return a subview of the buffer.

Example

This example illustrates the basic concept of chunking.

(* Queue as a byte chunk source. *)
let queue =
  let queue = Queue.create () in
  Queue.add "he" queue;
  (* ... *)
  Queue.add "d!" queue;
  queue
in

(* Reader function that returns chunks of text from the source. *)
let reader () =
  match Queue.take_opt queue with
  | None ->
    (** For close incoming byte stream, the reader
        should raise an End_of_file exception.  *)
    raise End_of_file
  | Some chunk -> Bstr.of_string chunk
in

Bytream.In.make reader

make_intf ?overlap_size reader

Same as the make function, but the reader returns chunks instead of buffers.

Example

match In_channel.input_bigarray ic buffer 0 io_buffer_size with
| (* ... *)
| length -> (~buffer, ~offset:0, ~length)

of_buffer buffer

Construct a byte stream from a previously prepared buffer.

Example

let buffer = mmap_file "bigfile.iso" in
let in_stream = Bytream.In.of_buffer buffer in
(* ... *)

of_string string

Same as of_buffer, but for string value.

• parameter string

  The string will be copied to transform it into the buffer value.

of_channel ?io_buffer_size ic

Construct an incoming byte stream from ic using the In_channel.input_bigarray function to get chunks from the source of the channel.

• parameter ?buffer_size

  by default is 4096 bytes

Example pattern for your modules

module Tar_archive = struct
  (* ... *)
  let of_channel ic =
    Bytream.In.of_channel ic
    |> Tar_reader.input_archive in_stream

available_to_read in_stream

• returns

  remaining bytes of current chunk that available to read.

consume_bytes in_stream len

Consume len bytes from incoming bytes stream with offset shifting.

• raises End_of_file

  if you try consume more bytes than a source provide.

ensure_chunk in_stream len

• returns

  buffer value that guarantee have len bytes.

• raises End_of_file

  if the in_stream was ended

See. ensure_chunk function that have most fast allocation.

ensure_chunk in_stream len

Same as the make function, but returns chunk.

Note. Maybe be most performance than ensure_buffer because buffer subbing is more expressive. Recommended to use.

position in_stream

• returns

  Total bytes number read from incoming byte stream.

input in_stream buffer off len

Input streams's bytes into buffer and return actually batched bytes. Similar to Stdlib.input channel's function.

Note. Try use ensure_ functions instead it for escape unnecessary allocations.

• parameter off

  The is buffer's offset.

• parameter len

  The is buffer's length.

• raises End_of_file

  if the in_stream was ended

input_bytes in_stream bytes off len s

Same as the Input function, but working with bytes value.

really_input in_stream buffer off len input streams's bytes into buffer and grantees fill it.

Example

let input_request in_stream =
  (* ... *)
  Bytream.In.really_input in_stream payload_buffer 0 payload_size

• raises End_of_file

  if in_stream not have enough bytes for input

really_input_bytes in_stream bytes off len same as really_input but for bytes.

input_string in_stream len

Input len-sized bytes value from incoming byte stream.

input_while ?max p in_stream

Input byte while p on the byte returns true.

• parameter ?max

  determined the maximum length of the input string

input_while ~max p in_stream

Same as the input_while function, but consuming remaining bytes until max. Ideal for input fixed-size C string field some binary formats.

take n input_value in_stream

Call input_value n-times and save the function's results in a list.

with_size f in_stream

• returns

  (value, size)

A value and a number of bytes were inputted by the f function.

Example

let section, section_size = Bytream.In.with_size input_section in_stream in
(* ... *)

input_char in_stream

input_int8 in_stream

input_uint8 in_stream

input_byte in_stream

input_int16_be in_stream

input_int16_ne in_stream

input_int16_le in_stream

input_uint16_be in_stream

input_uint16_ne in_stream

input_uint16_le in_stream

input_int32_be in_stream

input_int32_ne in_stream

input_int32_le in_stream

input_int64_be in_stream

input_int64_ne in_stream

input_int64_le in_stream