Bytes.Slice
Byte slices.
A byte slice is a non-empty consecutive range of bytes in a Bytes.t
value. The sole distinguished empty slice Slice.eod
is used to indicate end of data.
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.
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.
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
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
.
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.
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
.
Warning. In these operations index specification are in slice space which starts at 0 at the slice's first
byte.
break n s
is (take n s, drop n s)
but returns None
if any result is None
.
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
.
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 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
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.
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
.