package bytesrw

  1. Overview
  2. Docs

Module Bytes.SliceSource

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

Sourcetype length = int

The type for slice lengths. A positive integer.

Sourceval default_length : length

default_length is io_buffer_size.

Sourceval io_buffer_size : length

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

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

Sourceval check_length : int -> length

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

Slices

Sourcetype t

The type for byte slices.

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

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

Sourceval bytes : t -> bytes

bytes s are the underlying bytes of the slice s.

Sourceval first : t -> int

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

Sourceval length : t -> int

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

Sourceval 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

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

Sourceval is_eod : t -> bool

is_eod s is true iff s == eod.

Predicates and comparisons

Sourceval equal : t -> t -> bool

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

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

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

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

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

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

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

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

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

Sourceval 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

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

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

Sourceval of_bigbytes : ?first:int -> ?last:int -> (int, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t -> t

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

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

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

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

of_string s is of_bytes (Bytes.of_string s).

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

of_string_or_eod is of_bytes_or_eod (Bytes.of_string s).

Sourceval to_bytes : t -> bytes

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

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

Sourceval to_string : t -> string

to_string s copies the range of s to a new string value.

Sourceval add_to_buffer : Buffer.t -> t -> unit

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

Sourceval output_to_out_channel : 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

Sourceval pp : 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.

Sourceval pp' : ?head:int -> ?hex:bool -> unit -> 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).

Sourceval tracer : ?pp:(Format.formatter -> t -> unit) -> ?ppf: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.