Module Bytes.Slice

Byte slices.

A byte slice is a non-empty consecutive range of bytes in a Bytes.t value. The unique, distinguished, empty slice Slice.eod is used to indicate end of data.

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 is a slice referencing 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. It raises Invalid_argument if length is not positive, larger than the length of b or if first is out of bounds.

See also make_or_eod and of_bytes.

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

make_or_eod b ~first ~length is like make but returns eod instead of raising Invalid_argument if length is zero. first must be a valid position of b, see Bytes.sub.

val bytes : t -> bytes

bytes s are the underlying bytes of the slice s.

val first : t -> int

first s is the index, in bytes s, of the first byte of the byte range of s.

val last : t -> int

last s is the index, in bytes s, of the last byte of the byte range of s.

val length : t -> int

length s is the byte length of the byte range 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.

Predicates and comparisons

val equal : t -> t -> bool

equal s0 s1 is true iff the bytes in the slice ranges of s0 and s1 are equal.

val compare : t -> t -> int

compare s0 s1 sorts the bytes in the slice ranges of s0 and s1 in lexicographic order.

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. 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 in the range of s without the first n bytes starting at first. This is None if the operation results in eod, including if s is eod or if n < 0.

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

break n s is (take n s, drop n s).

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 s ~first ~length is like sub except that if the interval is empty, eod is returned. first must be a valid position of s, see Bytes.sub.

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].

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 and make.

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]. The bytes are not copied.

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_bigbytes : ?first:int -> ?last:int -> (int, Stdlib.Bigarray.int8_unsigned_elt, Stdlib.Bigarray.c_layout) Stdlib.Bigarray.Array1.t -> t

of_bigbytes is like of_bytes but copies data from a bigbytes value.

val of_bigbytes_or_eod : ?first:int -> ?last:int -> (int, Stdlib.Bigarray.int8_unsigned_elt, Stdlib.Bigarray.c_layout) Stdlib.Bigarray.Array1.t -> t

of_bytes_or_eod is like of_bytes_or_eod but copies data from a bigbytes value.

val of_string : ?first:int -> ?last:int -> string -> t

of_string s is of_bytes (Bytes.of_string s).

val of_string_or_eod : ?first:int -> ?last:int -> string -> t

of_string_or_eod is of_bytes_or_eod (Bytes.of_string s).

val to_bytes : t -> bytes

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

val to_bigbytes : t -> (int, Stdlib.Bigarray.int8_unsigned_elt, Stdlib.Bigarray.c_layout) Stdlib.Bigarray.Array1.t

to_bigbytes t copies the range of s to a new bigbytes value.

val to_string : t -> string

to_string s copies the range of s to a new 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. For example by default stdout is not.

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.tap or Writer.tap.