Module Core.Bigstring

String type based on Bigarray, for use in I/O and C-bindings, extending Core_kernel.Bigstring.

include module type of sig ... end
type t = (Core_kernel__.Import.char, Stdlib.Bigarray.int8_unsigned_elt, Stdlib.Bigarray.c_layout) Stdlib.Bigarray.Array1.t
type t_frozen = t
val compare : t -> t -> Base.int
val t_of_sexp : Sexplib0.Sexp.t -> t
val sexp_of_t : t -> Sexplib0.Sexp.t
val compare_t_frozen : t_frozen -> t_frozen -> Base.int
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
val equal : t Base.Equal.equal
val init : Base.int -> f:(Base.int -> Base.char) -> t
val of_string : ?⁠pos:Base.int -> ?⁠len:Base.int -> Base.string -> t
val of_bytes : ?⁠pos:Base.int -> ?⁠len:Base.int -> Base.bytes -> t
val to_string : ?⁠pos:Base.int -> ?⁠len:Base.int -> t -> Base.string
val to_bytes : ?⁠pos:Base.int -> ?⁠len:Base.int -> t -> Base.bytes
val concat : ?⁠sep:t -> t Base.list -> t
val check_args : loc:Base.string -> pos:Base.int -> len:Base.int -> t -> Base.unit
val get_opt_len : t -> pos:Base.int -> Base.int Base.option -> Base.int
val length : t -> Base.int
val get : t -> Base.int -> Base.char
val set : t -> Base.int -> Base.char -> Base.unit
val is_mmapped : t -> Base.bool
val blit : (tt) Base__.Blit_intf.blit
val blito : (tt) Base__.Blit_intf.blito
val unsafe_blit : (tt) Base__.Blit_intf.blit
val sub : (tt) Base__.Blit_intf.sub
val subo : (tt) Base__.Blit_intf.subo
val copy : t -> t
val memset : t -> pos:Base.int -> len:Base.int -> Base.char -> Base.unit
val memcmp : t -> pos1:Base.int -> t -> pos2:Base.int -> len:Base.int -> Base.int
val find : ?⁠pos:Base.int -> ?⁠len:Base.int -> Base.char -> t -> Base.int Base.option
val unsafe_find : t -> Base.char -> pos:Base.int -> len:Base.int -> Base.int
val get_int8 : t -> pos:Base.int -> Base.int
val set_int8_exn : t -> pos:Base.int -> Base.int -> Base.unit
val get_uint8 : t -> pos:Base.int -> Base.int
val set_uint8_exn : t -> pos:Base.int -> Base.int -> Base.unit
val unsafe_get_int8 : t -> pos:Base.int -> Base.int
val unsafe_set_int8 : t -> pos:Base.int -> Base.int -> Base.unit
val unsafe_get_uint8 : t -> pos:Base.int -> Base.int
val unsafe_set_uint8 : t -> pos:Base.int -> Base.int -> Base.unit
val get_int16_le : t -> pos:Base.int -> Base.int
val get_int16_be : t -> pos:Base.int -> Base.int
val set_int16_le_exn : t -> pos:Base.int -> Base.int -> Base.unit
val set_int16_be_exn : t -> pos:Base.int -> Base.int -> Base.unit
val unsafe_get_int16_le : t -> pos:Base.int -> Base.int
val unsafe_get_int16_be : t -> pos:Base.int -> Base.int
val unsafe_set_int16_le : t -> pos:Base.int -> Base.int -> Base.unit
val unsafe_set_int16_be : t -> pos:Base.int -> Base.int -> Base.unit
val get_uint16_le : t -> pos:Base.int -> Base.int
val get_uint16_be : t -> pos:Base.int -> Base.int
val set_uint16_le_exn : t -> pos:Base.int -> Base.int -> Base.unit
val set_uint16_be_exn : t -> pos:Base.int -> Base.int -> Base.unit
val unsafe_get_uint16_le : t -> pos:Base.int -> Base.int
val unsafe_get_uint16_be : t -> pos:Base.int -> Base.int
val unsafe_set_uint16_le : t -> pos:Base.int -> Base.int -> Base.unit
val unsafe_set_uint16_be : t -> pos:Base.int -> Base.int -> Base.unit
val get_int32_le : t -> pos:Base.int -> Base.int
val get_int32_be : t -> pos:Base.int -> Base.int
val set_int32_le_exn : t -> pos:Base.int -> Base.int -> Base.unit
val set_int32_be_exn : t -> pos:Base.int -> Base.int -> Base.unit
val unsafe_get_int32_le : t -> pos:Base.int -> Base.int
val unsafe_get_int32_be : t -> pos:Base.int -> Base.int
val unsafe_set_int32_le : t -> pos:Base.int -> Base.int -> Base.unit
val unsafe_set_int32_be : t -> pos:Base.int -> Base.int -> Base.unit
val get_uint32_le : t -> pos:Base.int -> Base.int
val get_uint32_be : t -> pos:Base.int -> Base.int
val set_uint32_le_exn : t -> pos:Base.int -> Base.int -> Base.unit
val set_uint32_be_exn : t -> pos:Base.int -> Base.int -> Base.unit
val unsafe_get_uint32_le : t -> pos:Base.int -> Base.int
val unsafe_get_uint32_be : t -> pos:Base.int -> Base.int
val unsafe_set_uint32_le : t -> pos:Base.int -> Base.int -> Base.unit
val unsafe_set_uint32_be : t -> pos:Base.int -> Base.int -> Base.unit
val get_int64_le_exn : t -> pos:Base.int -> Base.int
val get_int64_be_exn : t -> pos:Base.int -> Base.int
val get_int64_le_trunc : t -> pos:Base.int -> Base.int
val get_int64_be_trunc : t -> pos:Base.int -> Base.int
val set_int64_le : t -> pos:Base.int -> Base.int -> Base.unit
val set_int64_be : t -> pos:Base.int -> Base.int -> Base.unit
val unsafe_get_int64_le_exn : t -> pos:Base.int -> Base.int
val unsafe_get_int64_be_exn : t -> pos:Base.int -> Base.int
val unsafe_get_int64_le_trunc : t -> pos:Base.int -> Base.int
val unsafe_get_int64_be_trunc : t -> pos:Base.int -> Base.int
val unsafe_set_int64_le : t -> pos:Base.int -> Base.int -> Base.unit
val unsafe_set_int64_be : t -> pos:Base.int -> Base.int -> Base.unit
val get_uint64_be_exn : t -> pos:Base.int -> Base.int
val get_uint64_le_exn : t -> pos:Base.int -> Base.int
val set_uint64_le_exn : t -> pos:Base.int -> Base.int -> Base.unit
val set_uint64_be_exn : t -> pos:Base.int -> Base.int -> Base.unit
val unsafe_get_uint64_be_exn : t -> pos:Base.int -> Base.int
val unsafe_get_uint64_le_exn : t -> pos:Base.int -> Base.int
val unsafe_set_uint64_le : t -> pos:Base.int -> Base.int -> Base.unit
val unsafe_set_uint64_be : t -> pos:Base.int -> Base.int -> Base.unit
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
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
val create : ?⁠max_mem_waiting_gc:Core_kernel.Byte_units.t -> Core_kernel__.Import.int -> t
val sub_shared : ?⁠pos:Core_kernel__.Import.int -> ?⁠len:Core_kernel__.Import.int -> t -> t
val write_bin_prot : t -> ?⁠pos:Core_kernel__.Import.int -> 'a Bin_prot.Type_class.writer -> 'a -> Core_kernel__.Import.int
val read_bin_prot : t -> ?⁠pos:Core_kernel__.Import.int -> ?⁠len:Core_kernel__.Import.int -> 'a Bin_prot.Type_class.reader -> ('a * Core_kernel__.Import.int) Core_kernel.Or_error.t
val read_bin_prot_verbose_errors : t -> ?⁠pos:Core_kernel__.Import.int -> ?⁠len:Core_kernel__.Import.int -> 'a Bin_prot.Type_class.reader -> [ `Invalid_data of Core_kernel.Error.t | `Not_enough_data | `Ok of 'a * Core_kernel__.Import.int ]
val unsafe_destroy : t -> Core_kernel__.Import.unit
val unsafe_destroy_and_resize : t -> len:Core_kernel__.Import.int -> t
val get_tail_padded_fixed_string : padding:Core_kernel__.Import.char -> t -> pos:Core_kernel__.Import.int -> len:Core_kernel__.Import.int -> Core_kernel__.Import.unit -> Core_kernel__.Import.string
val set_tail_padded_fixed_string : padding:Core_kernel__.Import.char -> t -> pos:Core_kernel__.Import.int -> len:Core_kernel__.Import.int -> Core_kernel__.Import.string -> Core_kernel__.Import.unit
val get_head_padded_fixed_string : padding:Core_kernel__.Import.char -> t -> pos:Core_kernel__.Import.int -> len:Core_kernel__.Import.int -> Core_kernel__.Import.unit -> Core_kernel__.Import.string
val set_head_padded_fixed_string : padding:Core_kernel__.Import.char -> t -> pos:Core_kernel__.Import.int -> len:Core_kernel__.Import.int -> Core_kernel__.Import.string -> Core_kernel__.Import.unit
exception IOError of int * exn

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 -> Core__.Import.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 : Core__.Import.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__.Import.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__.Import.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__.Import.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__.Import.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__.Import.Or_error.t
val sendmsg_nonblocking_no_sigpipe : (Unix.file_descr -> ?⁠count:int -> t Core__.Core_unix.IOVec.t array -> int option) Core__.Import.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 -> Core__.Import.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 : Core__.Import.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__.Import.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__.Import.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__.Import.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 -> Core__.Import.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 -> Core__.Import.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.