include module type of struct include Core_kernel.Bigstring end
Types and exceptions
Type of bigstrings
val compare : t -> t -> Base.Int.t
val sexp_of_t : t -> Ppx_sexp_conv_lib.Sexp.t
type t_frozen = t
Type of bigstrings which support hashing. Note that mutation invalidates previous hashes.
val compare_t_frozen : t_frozen -> t_frozen -> Base.Int.t
val hash_fold_t_frozen : Base.Hash.state -> t_frozen -> Base.Hash.state
val hash_t_frozen : t_frozen -> Base.Hash.hash_value
val sexp_of_t_frozen : t_frozen -> Ppx_sexp_conv_lib.Sexp.t
include module type of Base_bigstring with type t := t and type t_frozen := t_frozen
Types and exceptions
include Ppx_sexp_conv_lib.Sexpable.S with type t := t
val t_of_sexp : Sexplib0.Sexp.t -> t
val sexp_of_t : t -> Sexplib0.Sexp.t
val hash_fold_t_frozen : Base.Hash.state -> t_frozen -> Base.Hash.state
val hash_t_frozen : t_frozen -> Base.Hash.hash_value
val sexp_of_t_frozen : t_frozen -> Ppx_sexp_conv_lib.Sexp.t
val t_frozen_of_sexp : Ppx_sexp_conv_lib.Sexp.t -> t_frozen
include Base.Equal.S with type t := t
val equal : t Base.Equal.equal
Creation and string conversion
create length
- parameter max_mem_waiting_gc
default = 256 M in OCaml <= 3.12, 1 G otherwise. As the total allocation of calls to
create
approachmax_mem_waiting_gc_in_bytes
, the pressure in the garbage collector to be more agressive will increase.
- returns
a new bigstring having
length
. Content is undefined.
init n ~f
creates a bigstring t
of length n
, with t.{i} = f i
.
val of_string : ?pos:Base.int -> ?len:Base.int -> Base.string -> t
of_string ?pos ?len str
- returns
a new bigstring that is equivalent to the substring of length
len
instr
starting at positionpos
.
- parameter pos
default = 0
- parameter len
default =
String.length str - pos
val of_bytes : ?pos:Base.int -> ?len:Base.int -> Base.bytes -> t
of_bytes ?pos ?len str
- returns
a new bigstring that is equivalent to the subbytes of length
len
instr
starting at positionpos
.
- parameter pos
default = 0
- parameter len
default =
Bytes.length str - pos
val to_string : ?pos:Base.int -> ?len:Base.int -> t -> Base.string
to_string ?pos ?len bstr
- returns
a new string that is equivalent to the substring of length
len
inbstr
starting at positionpos
.
- parameter pos
default = 0
- parameter len
default =
length bstr - pos
- raises Invalid_argument
if the string would exceed runtime limits.
val to_bytes : ?pos:Base.int -> ?len:Base.int -> t -> Base.bytes
to_bytes ?pos ?len bstr
- returns
a new byte sequence that is equivalent to the substring of length
len
inbstr
starting at positionpos
.
- parameter pos
default = 0
- parameter len
default =
length bstr - pos
- raises Invalid_argument
if the bytes would exceed runtime limits.
concat ?sep list
returns the concatenation of list
with sep
in between each.
Checking
val check_args : loc:Base.string -> pos:Base.int -> len:Base.int -> t -> Base.unit
check_args ~loc ~pos ~len bstr
checks the position and length arguments pos
and len
for bigstrings bstr
.
- raises
Invalid_argument if these arguments are illegal for the given bigstring using
loc
to indicate the calling context.
val get_opt_len : t -> pos:Base.int -> Base.int Base.option -> Base.int
get_opt_len bstr ~pos opt_len
- returns
the length of a subbigstring in
bstr
starting at positionpos
and given optional lengthopt_len
. This function does not check the validity of its arguments. Usecheck_args
for that purpose.
Accessors
Blitting
include Base.Blit.S with type t := t
module To_string : sig ... end
module From_string : Base.Blit.S_distinct with type src := Base.string with type dst := t
module To_bytes : Base.Blit.S_distinct with type src := t with type dst := Base.bytes
module From_bytes : Base.Blit.S_distinct with type src := Base.bytes with type dst := t
memset t ~pos ~len c
fills t
with c
within the range [pos, pos + len)
.
memcmp t1 ~pos1 t2 ~pos2 ~len
is like compare t1 t2
except performs the comparison on the subregions of t1
and t2
defined by pos1
, pos2
, and len
.
Search
find ?pos ?len char t
returns Some i
for the smallest i >= pos
such that t.{i} = char
, or None
if there is no such i
.
- parameter pos
default = 0
- parameter len
default =
length bstr - pos
Same as find
, but does no bounds checking, and returns a negative value instead of None
if char
is not found.
Accessors for parsing binary values, analogous to Binary_packing
16-bit methods
32-bit methods
64-bit signed values
64-bit unsigned values
32-bit methods with full precision
val get_int32_t_le : t -> pos:Base.int -> Base.Int32.t
val get_int32_t_be : t -> pos:Base.int -> Base.Int32.t
val set_int32_t_le : t -> pos:Base.int -> Base.Int32.t -> Base.unit
val set_int32_t_be : t -> pos:Base.int -> Base.Int32.t -> Base.unit
val unsafe_get_int32_t_le : t -> pos:Base.int -> Base.Int32.t
val unsafe_get_int32_t_be : t -> pos:Base.int -> Base.Int32.t
val unsafe_set_int32_t_le : t -> pos:Base.int -> Base.Int32.t -> Base.unit
val unsafe_set_int32_t_be : t -> pos:Base.int -> Base.Int32.t -> Base.unit
64-bit methods with full precision
val get_int64_t_le : t -> pos:Base.int -> Base.Int64.t
val get_int64_t_be : t -> pos:Base.int -> Base.Int64.t
val set_int64_t_le : t -> pos:Base.int -> Base.Int64.t -> Base.unit
val set_int64_t_be : t -> pos:Base.int -> Base.Int64.t -> Base.unit
val unsafe_get_int64_t_le : t -> pos:Base.int -> Base.Int64.t
val unsafe_get_int64_t_be : t -> pos:Base.int -> Base.Int64.t
val unsafe_set_int64_t_le : t -> pos:Base.int -> Base.Int64.t -> Base.unit
val unsafe_set_int64_t_be : t -> pos:Base.int -> Base.Int64.t -> Base.unit
module Private : sig ... end
include Core_kernel.Hexdump.S with type t := t
module Hexdump : sig ... end
Creation and string conversion
val create : ?max_mem_waiting_gc:Core_kernel.Byte_units.t -> Base.Int.t -> t
create length
- parameter max_mem_waiting_gc
default = 256 M in OCaml <= 3.12, 1 G otherwise. As the total allocation of calls to
create
approachmax_mem_waiting_gc
, the pressure in the garbage collector to be more agressive will increase.
- returns
a new bigstring having
length
. Content is undefined.
sub_shared ?pos ?len bstr
- returns
the sub-bigstring in
bstr
that starts at positionpos
and has lengthlen
. The sub-bigstring shares the same memory region, i.e. modifying it will modify the original bigstring. Holding on to the sub-bigstring will also keep the (usually bigger) original one around.
- parameter pos
default = 0
- parameter len
default =
Bigstring.length bstr - pos
Reading/writing bin-prot
val write_bin_prot : t -> ?pos:Base.Int.t -> 'a Bin_prot.Type_class.writer -> 'a -> Base.Int.t
write_bin_prot t writer a
writes a
to t
starting at pos
, and returns the index in t
immediately after the last byte written. It raises if pos < 0
or if a
doesn't fit in t
.
val read_bin_prot : t -> ?pos:Base.Int.t -> ?len:Base.Int.t -> 'a Bin_prot.Type_class.reader -> ('a * Base.Int.t) Core_kernel.Or_error.t
The read_bin_prot*
functions read from the region of t
starting at pos
of length len
. They return the index in t
immediately after the last byte read. They raise if pos
and len
don't describe a region of t
.
val read_bin_prot_verbose_errors : t -> ?pos:Base.Int.t -> ?len:Base.Int.t -> 'a Bin_prot.Type_class.reader -> [ `Invalid_data of Core_kernel.Error.t | `Not_enough_data | `Ok of 'a * Base.Int.t ]
Destruction
val unsafe_destroy : t -> Base.Unit.t
unsafe_destroy bstr
destroys the bigstring by deallocating its associated data or, if memory-mapped, unmapping the corresponding file, and setting all dimensions to zero. This effectively frees the associated memory or address-space resources instantaneously. This feature helps working around a bug in the current OCaml runtime, which does not correctly estimate how aggressively to reclaim such resources.
This operation is safe unless you have passed the bigstring to another thread that is performing operations on it at the same time. Access to the bigstring after this operation will yield array bounds exceptions.
- raises Failure
if the bigstring has already been deallocated (or deemed "external", which is treated equivalently), or if it has proxies, i.e. other bigstrings referring to the same data.
val unsafe_destroy_and_resize : t -> len:Base.Int.t -> t
unsafe_destroy_and_resize bstr ~len
reallocates the memory backing bstr
and returns a new bigstring that starts at position 0 and has length len
. If len
is greater than length bstr
then the newly allocated memory will not be initialized.
Similar to unsafe_destroy
, this operation is safe unless you have passed the bigstring to another thread that is performing operations on it at the same time. Access to bstr
after this operation will yield array bounds exceptions.
- raises Failure
if the bigstring has already been deallocated (or deemed "external", which is treated equivalently), if it is backed by a memory map, or if it has proxies, i.e. other bigstrings referring to the same data.
val get_tail_padded_fixed_string : padding:Base.Char.t -> t -> pos:Base.Int.t -> len:Base.Int.t -> Base.Unit.t -> Base.String.t
Similar to Binary_packing.unpack_tail_padded_fixed_string
and .pack_tail_padded_fixed_string
.
val set_tail_padded_fixed_string : padding:Base.Char.t -> t -> pos:Base.Int.t -> len:Base.Int.t -> Base.String.t -> Base.Unit.t
val get_head_padded_fixed_string : padding:Base.Char.t -> t -> pos:Base.Int.t -> len:Base.Int.t -> Base.Unit.t -> Base.String.t
val set_head_padded_fixed_string : padding:Base.Char.t -> t -> pos:Base.Int.t -> len:Base.Int.t -> Base.String.t -> Base.Unit.t
module Unstable : sig ... end
module Stable : sig ... end
Type of I/O errors.
In IOError (n, exn)
, n
is the number of bytes successfully read/written before the error and exn
is the exception that occurred (e.g., Unix_error
, End_of_file
)
Input functions
val read : ?min_len:int -> Unix.file_descr -> ?pos:int -> ?len:int -> t -> int
read ?min_len fd ?pos ?len bstr
reads at least min_len
(must be >= 0
) and at most len
(must be >= min_len
) bytes from file descriptor fd
, and writes them to bigstring bstr
starting at position pos
. Returns the number of bytes actually read.
read
returns zero only if len = 0
. If len > 0
and there's nothing left to read, read
raises to indicate EOF even if min_len = 0
.
NOTE: Even if len
is zero, there may still be errors when reading from the descriptor!
Raises Invalid_argument
if the designated ranges are out of bounds. Raises IOError
in the case of input errors, or on EOF if the minimum length could not be read.
val really_read : Unix.file_descr -> ?pos:int -> ?len:int -> t -> unit
really_read fd ?pos ?len bstr
reads len
bytes from file descriptor fd
, and writes them to bigstring bstr
starting at position pos
.
Raises Invalid_argument
if the designated range is out of bounds. Raises IOError
in the case of input errors, or on EOF.
val really_recv : Unix.file_descr -> ?pos:int -> ?len:int -> t -> unit
really_recv sock ?pos ?len bstr
receives len
bytes from socket sock
, and writes them to bigstring bstr
starting at position pos
. If len
is zero, the function returns immediately without performing the underlying system call.
Raises Invalid_argument
if the designated range is out of bounds. Raises IOError
in the case of input errors, or on EOF.
val recvfrom_assume_fd_is_nonblocking : Unix.file_descr -> ?pos:int -> ?len:int -> t -> int * Unix.sockaddr
recvfrom_assume_fd_is_nonblocking sock ?pos ?len bstr
reads up to len
bytes into bigstring bstr
starting at position pos
from socket sock
without yielding to other OCaml-threads.
Returns the number of bytes actually read and the socket address of the client.
Raises Unix_error
in the case of input errors. Raises Invalid_argument
if the designated range is out of bounds.
val read_assume_fd_is_nonblocking : Unix.file_descr -> ?pos:int -> ?len:int -> t -> Core__Syscall_result.Int.t
read_assume_fd_is_nonblocking fd ?pos ?len bstr
reads up to len
bytes into bigstring bstr
starting at position pos
from file descriptor fd
without yielding to other OCaml-threads. Returns the number of bytes actually read.
Raises Invalid_argument
if the designated range is out of bounds.
val pread_assume_fd_is_nonblocking : Unix.file_descr -> offset:int -> ?pos:int -> ?len:int -> t -> int
pread_assume_fd_is_nonblocking fd ~offset ?pos ?len bstr
reads up to len
bytes from file descriptor fd
at offset offset
, and writes them to bigstring bstr
starting at position pos
. The fd
must be capable of seeking, and the current file offset used for a regular read()
is unchanged. Please see man pread
for more information. Returns the number of bytes actually read.
Raises Invalid_argument
if the designated range is out of bounds. Raises Unix_error
in the case of input errors.
val input : ?min_len:int -> Stdio.In_channel.t -> ?pos:int -> ?len:int -> t -> int
input ?min_len ic ?pos ?len bstr
tries to read len
bytes (guarantees to read at least min_len
bytes, which must be >= 0
and <= len
), if possible, before returning, from input channel ic
, and writes them to bigstring bstr
starting at position pos
. Returns the number of bytes actually read.
NOTE: Even if len
is zero, there may still be errors when reading from the descriptor, which will be done if the internal buffer is empty!
NOTE: If at least len
characters are available in the input channel buffer and if len
is not zero, data will only be fetched from the channel buffer. Otherwise data will be read until at least min_len
characters are available.
Raises Invalid_argument
if the designated range is out of bounds. Raises IOError
in the case of input errors, or on premature EOF.
val really_input : Stdio.In_channel.t -> ?pos:int -> ?len:int -> t -> unit
really_input ic ?pos ?len bstr
reads exactly len
bytes from input channel ic
, and writes them to bigstring bstr
starting at position pos
.
Raises Invalid_argument
if the designated range is out of bounds. Raises IOError
in the case of input errors, or on premature EOF.
Output functions
val really_write : Unix.file_descr -> ?pos:int -> ?len:int -> t -> unit
really_write fd ?pos ?len bstr
writes len
bytes in bigstring bstr
starting at position pos
to file descriptor fd
.
Raises Invalid_argument
if the designated range is out of bounds. Raises IOError
in the case of output errors.
val really_send_no_sigpipe : (Unix.file_descr -> ?pos:int -> ?len:int -> t -> unit) Core_kernel.Or_error.t
really_send_no_sigpipe sock ?pos ?len bstr
sends len
bytes in bigstring bstr
starting at position pos
to socket sock
without blocking and ignoring SIGPIPE
.
Raises Invalid_argument
if the designated range is out of bounds. Raises IOError
in the case of output errors.
really_send_no_sigpipe
is not implemented on some platforms, in which case it returns an Error
value indicating that it is unimplemented.
val send_nonblocking_no_sigpipe : (Unix.file_descr -> ?pos:int -> ?len:int -> t -> Core__Syscall_result.Int.t) Core_kernel.Or_error.t
send_nonblocking_no_sigpipe sock ?pos ?len bstr
tries to send len
bytes in bigstring bstr
starting at position pos
to socket sock
. Returns bytes_written
.
Raises Invalid_argument
if the designated range is out of bounds.
val sendto_nonblocking_no_sigpipe : (Unix.file_descr -> ?pos:int -> ?len:int -> t -> Unix.sockaddr -> Core__Syscall_result.Int.t) Core_kernel.Or_error.t
sendto_nonblocking_no_sigpipe sock ?pos ?len bstr sockaddr
tries to send len
bytes in bigstring bstr
starting at position pos
to socket sock
using address addr
. Returns bytes_written
.
Raises Invalid_argument
if the designated range is out of bounds.
val write : Unix.file_descr -> ?pos:int -> ?len:int -> t -> int
write fd ?pos ?len bstr
writes len
bytes in bigstring bstr
starting at position pos
to file descriptor fd
. Returns the number of bytes actually written.
Raises Invalid_argument
if the designated range is out of bounds. Raises Unix_error
in the case of output errors.
val pwrite_assume_fd_is_nonblocking : Unix.file_descr -> offset:int -> ?pos:int -> ?len:int -> t -> int
pwrite_assume_fd_is_nonblocking fd ~offset ?pos ?len bstr
writes up to len
bytes of bigstring bstr
starting at position pos
to file descriptor fd
at position offset
. The fd
must be capable of seeking, and the current file offset used for non-positional read()
/write()
calls is unchanged. Returns the number of bytes written.
Raises Invalid_argument
if the designated range is out of bounds. Raises Unix_error
in the case of output errors.
val write_assume_fd_is_nonblocking : Unix.file_descr -> ?pos:int -> ?len:int -> t -> int
write_assume_fd_is_nonblocking fd ?pos ?len bstr
writes len
bytes in bigstring bstr
starting at position pos
to file descriptor fd
without yielding to other OCaml-threads. Returns the number of bytes actually written.
Raises Invalid_argument
if the designated range is out of bounds. Raises Unix_error
in the case of output errors.
val writev : Unix.file_descr -> ?count:int -> t Core__Core_unix.IOVec.t array -> int
writev fd ?count iovecs
writes count
iovecs
of bigstrings to file descriptor fd
. Returns the number of bytes written.
Raises Invalid_argument
if count
is out of range. Raises Unix_error
in the case of output errors.
val writev_assume_fd_is_nonblocking : Unix.file_descr -> ?count:int -> t Core__Core_unix.IOVec.t array -> int
writev_assume_fd_is_nonblocking fd ?count iovecs
writes count
iovecs
of bigstrings to file descriptor fd
without yielding to other OCaml-threads. Returns the number of bytes actually written.
Raises Invalid_argument
if the designated range is out of bounds. Raises Unix_error
in the case of output errors.
val recvmmsg_assume_fd_is_nonblocking : (Unix.file_descr -> ?count:int -> ?srcs:Unix.sockaddr array -> t Core__Core_unix.IOVec.t array -> lens:int array -> int) Core_kernel.Or_error.t
val unsafe_recvmmsg_assume_fd_is_nonblocking : (Unix.file_descr -> t Core__Core_unix.IOVec.t array -> int -> Unix.sockaddr array option -> int array -> int) Core_kernel.Or_error.t
val sendmsg_nonblocking_no_sigpipe : (Unix.file_descr -> ?count:int -> t Core__Core_unix.IOVec.t array -> int option) Core_kernel.Or_error.t
sendmsg_nonblocking_no_sigpipe sock ?count iovecs
sends count
iovecs
of bigstrings to socket sock
. Returns Some bytes_written
, or None
if the operation would have blocked. This system call will not cause signal SIGPIPE
if an attempt is made to write to a socket that was closed by the other side.
Raises Invalid_argument
if count
is out of range. Raises Unix_error
in the case of output errors.
val output : ?min_len:int -> Stdio.Out_channel.t -> ?pos:int -> ?len:int -> t -> int
output ?min_len oc ?pos ?len bstr
tries to output len
bytes (guarantees to write at least min_len
bytes, which must be >= 0
), if possible, before returning, from bigstring bstr
starting at position pos
to output channel oc
. Returns the number of bytes actually written.
NOTE: You may need to flush oc
to make sure that the data is actually sent.
NOTE: If len
characters fit into the channel buffer completely, they will be buffered. Otherwise writes will be attempted until at least min_len
characters have been sent.
Raises Invalid_argument
if the designated range is out of bounds.
Raises IOError
in the case of output errors. The IOError
argument counting the number of successful bytes includes those that have been transferred to the channel buffer before the error.
val really_output : Stdio.Out_channel.t -> ?pos:int -> ?len:int -> t -> unit
really_output oc ?pos ?len bstr
outputs exactly len
bytes from bigstring bstr
starting at position pos
to output channel oc
.
Raises Invalid_argument
if the designated range is out of bounds.
Raises IOError
in the case of output errors. The IOError
argument counting the number of successful bytes includes those that have been transferred to the channel buffer before the error.
Unsafe functions
val unsafe_read_assume_fd_is_nonblocking : Unix.file_descr -> pos:int -> len:int -> t -> Core__Syscall_result.Int.t
unsafe_read_assume_fd_is_nonblocking fd ~pos ~len bstr
is similar to Bigstring.read_assume_fd_is_nonblocking
, but does not perform any bounds checks. Will crash on bounds errors!
val unsafe_write : Unix.file_descr -> pos:int -> len:int -> t -> int
unsafe_write fd ~pos ~len bstr
is similar to Bigstring.write
, but does not perform any bounds checks. Will crash on bounds errors!
val unsafe_write_assume_fd_is_nonblocking : Unix.file_descr -> pos:int -> len:int -> t -> int
unsafe_write_assume_fd_is_nonblocking fd ~pos ~len bstr
is similar to Bigstring.write_assume_fd_is_nonblocking
, but does not perform any bounds checks. Will crash on bounds errors!
val unsafe_read : min_len:int -> Unix.file_descr -> pos:int -> len:int -> t -> int
unsafe_read ~min_len fd ~pos ~len bstr
is similar to Bigstring.read
, but does not perform any bounds checks. Will crash on bounds errors!
val unsafe_really_recv : Unix.file_descr -> pos:int -> len:int -> t -> unit
unsafe_really_recv sock ~pos ~len bstr
is similar to Bigstring.really_recv
, but does not perform any bounds checks. Will crash on bounds errors!
val unsafe_really_write : Unix.file_descr -> pos:int -> len:int -> t -> unit
unsafe_really_write fd ~pos ~len bstr
is similar to Bigstring.write
, but does not perform any bounds checks. Will crash on bounds errors!
val unsafe_really_send_no_sigpipe : (Unix.file_descr -> pos:int -> len:int -> t -> unit) Core_kernel.Or_error.t
unsafe_really_send_no_sigpipe sock ~pos ~len bstr
is similar to Bigstring
.send, but does not perform any bounds checks. Will crash on bounds errors!
val unsafe_send_nonblocking_no_sigpipe : (Unix.file_descr -> pos:int -> len:int -> t -> Core__Syscall_result.Int.t) Core_kernel.Or_error.t
unsafe_send_nonblocking_no_sigpipe sock ~pos ~len bstr
is similar to Bigstring.send_nonblocking_no_sigpipe
, but does not perform any bounds checks. Will crash on bounds errors!
val unsafe_writev : Unix.file_descr -> t Core__Core_unix.IOVec.t array -> int -> int
unsafe_writev fd iovecs count
is similar to Bigstring.writev
, but does not perform any bounds checks. Will crash on bounds errors!
val unsafe_sendmsg_nonblocking_no_sigpipe : (Unix.file_descr -> t Core__Core_unix.IOVec.t array -> int -> int option) Core_kernel.Or_error.t
unsafe_sendmsg_nonblocking_no_sigpipe fd iovecs count
is similar to Bigstring.sendmsg_nonblocking_no_sigpipe
, but does not perform any bounds checks. Will crash on bounds errors!
val unsafe_input : min_len:int -> Stdio.In_channel.t -> pos:int -> len:int -> t -> int
unsafe_input ~min_len ic ~pos ~len bstr
is similar to Bigstring.input
, but does not perform any bounds checks. Will crash on bounds errors!
val unsafe_output : min_len:int -> Stdio.Out_channel.t -> pos:int -> len:int -> t -> int
unsafe_output ~min_len oc ~pos ~len bstr
is similar to Bigstring.output
, but does not perform any bounds checks. Will crash on bounds errors!
Memory mapping
val map_file : shared:bool -> Unix.file_descr -> int -> t
map_file shared fd n
memory-maps n
characters of the data associated with descriptor fd
to a bigstring. Iff shared
is true
, all changes to the bigstring will be reflected in the file.
Users must keep in mind that operations on the resulting bigstring may result in disk operations which block the runtime. This is true for pure OCaml operations (such as t.{1} <- 1
), and for calls to blit
. While some I/O operations may release the OCaml lock, users should not expect this to be done for all operations on a bigstring returned from map_file
.