Slice (bytesrw.Bytesrw.Bytes.Slice)

Validity

The bytes in the range of a slice is made available to a third-party for a limited amount of time during which the slice is said to be valid for reading or writing (or both). Third parties are only allowed to access the bytes in the range and in the mode specified while it is valid.

Slice lengths

type length = int

The type for slice lengths. A positive integer.

val default_length : length

default_length is io_buffer_size.

val io_buffer_size : length

io_buffer_size is 65536 it should correspond to the value of OCaml's IO_BUFFER_SIZE. See here.

val unix_io_buffer_size : length

unix_io_buffer_size is 65536 it should correspond to the value of OCaml's UNIX_BUFFER_SIZE. See here.

val check_length : int -> length

check_length l is l if l > 0 and raises Invalid_argument otherwise.

Slices

type t

The type for byte slices.

val make : bytes -> first:int -> length:length -> t

make b ~first ~length are the bytes of b in the range [first; first+length-1].

This function does not allow the creation of the empty Slice.eod which is a feature. See also make_or_eod, of_bytes and of_bytes_or_eod.

Raises Invalid_argument if length is not positive, larger than the length of b or if first is out of bounds.

val make_or_eod : bytes -> first:int -> length:int -> t

make_or_eod is like make but returns eod instead of raising Invalid_argument if length is not zero.

val bytes : t -> bytes

bytes s are the underlying bytes of the slice s.

val first : t -> int

first s is the index of the first byte of s.

val length : t -> int

length s is the byte length of s. This returns 0 (only on) eod.

val copy : tight:bool -> t -> t

copy ~tight s is a copy of s. If tight is true, the copy contains only the bytes in the range of s. If not the whole bytes s is copied.

End of data

val eod : t

eod is a slice to denote the end of data. It is the only slice with length d = 0. Its bytes are Bytes.empty.

val is_eod : t -> bool

is_eod s is true iff s == eod.

Breaking slices

Warning. In these operations index specification are in slice space which starts at 0 at the slice's first byte.

val take : int -> t -> t option

take n s is the slice made of the first n bytes starting at first in slice space. This is None if the operation results in eod, including if s is eod or if n < 0.

val drop : int -> t -> t option

drop n s is the slice made of the bytes of s without its first n bytes. This is None if the operation results in eod, including if s is eod or if n < 0.

val break : int -> t -> (t * t) option

break n s is (take n s, drop n s) but returns None if any result is None.

val sub : t -> first:int -> length:int -> t

sub s ~first ~length is the slice made of the consecutive bytes of the range b whose indices exist in the non-empty slice space range [first;first + length - 1]. Raises Invalid_argument if the interval is empty or out of bounds. See also sub_or_eod.

val sub_or_eod : t -> first:int -> length:int -> t

sub_or_eod is like sub except that if the interval is empty, eod is returned.

val subrange : ?first:int -> ?last:int -> t -> t

subrange ~first ~last s is the slice made of the consecutive bytes of the range of s whose indices exist in the non-empty slice space range [first;last] in slice space.

first defaults to 0 and last to Slice.length s - 1. Note that both first and last can be any integer. If s is eod or if first > last the interval is empty and Invalid_argument is raised. See also subrange_or_eod.

val subrange_or_eod : ?first:int -> ?last:int -> t -> t

subrange_or_eod is like of_bytes except that if the bytes are empty or if first > last, eod is returned.

Converting

val of_bytes : ?first:int -> ?last:int -> bytes -> t

of_bytes ~first ~last b is the slice made of the consecutive bytes of b whose indices exist in the non-empty range [first;last].

first defaults to 0 and last to Bytes.length s - 1. Note that both first and last can be any integer. If b is empty or if first > last the interval is empty and Invalid_argument is raised. See also of_bytes_or_eod.

val of_bytes_or_eod : ?first:int -> ?last:int -> bytes -> t

of_bytes_or_eod is like of_bytes except that if the bytes are empty or if first > last, eod is returned.

val of_string : string -> t

of_string is of_bytes (String.of_bytes s). Warning. This creates a copy of s.

val to_bytes : t -> bytes

to_bytes t copies the range of s to a new bytes value.

val to_string : t -> string

to_string s copies the range of s as a string value.

val add_to_buffer : Stdlib.Buffer.t -> t -> unit

add_to_buffer b s adds the byte range of s to b.

val output_to_out_channel : Stdlib.Out_channel.t -> t -> unit

output_to_out_channel oc s outputs the byte range of s to oc. Warning. Make sure the channel is in binary mode, e.g. stdout is not by default.

Formatting and inspecting

val pp : Stdlib.Format.formatter -> t -> unit

pp formats a slice for inspection. This formats the range specification and at most the first four bytes of the buffer in hex.

val pp' : 
  ?head:int ->
  ?hex:bool ->
  unit ->
  Stdlib.Format.formatter ->
  t ->
  unit

pp' is like pp but prints raw bytes if hex is false (defaults to true) and prints at most head initial bytes (defaults to 4, use (-1) to format all the bytes).

val tracer : 
  ?pp:(Stdlib.Format.formatter -> t -> unit) ->
  ?ppf:Stdlib.Format.formatter ->
  id:string ->
  t ->
  unit

tracer ~pp ~ppf ~id is a function that formats slices on ppf (defaults to Format.err_formatter) with pp (defaults to pp) and the identifier id. Use with Reader.trace_reads or Writer.trace_writes.