Module Bigstring

module Bigstring: Bigstring

Types and exceptions

type t = (char, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t

Type of bigstrings

exception IOError of int * exn

Type of I/O errors

The occurred exception (e.g. Unix_error, End_of_file)

Creation and string conversion

val create : ?max_mem_waiting_gc:Byte_units.t -> int -> t

create length
Returns a new bigstring having length. Content is undefined.

max_mem_waiting_gc : default = 256 M in OCaml <= 3.12, 1 G otherwise. As the total allocation of calls to create approach max_mem_waiting_gc, the pressure in the garbage collector to be more agressive will increase.

val init : int -> f:(int -> char) -> t

init n ~f creates a bigstring t of length n, with t.{i} = f i

val of_string : ?pos:int -> ?len:int -> string -> t

of_string ?pos ?len str
Returns a new bigstring that is equivalent to the substring of length len in str starting at position pos.

pos : default = 0

len : default = String.length str - pos

val to_string : ?pos:int -> ?len:int -> t -> string

to_string ?pos ?len bstr
Raises Invalid_argument if the string would exceed runtime limits.
Returns a new string that is equivalent to the substring of length len in bstr starting at position pos.

pos : default = 0

len : default = length bstr - pos

Checking

val check_args : loc:string -> pos:int -> len:int -> t -> 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:int -> int option -> int

get_opt_len bstr ~pos opt_len
Returns the length of a subbigstring in bstr starting at position pos and given optional length opt_len. This function does not check the validity of its arguments. Use Bigstring.check_args for that purpose.

Accessors

val length : t -> int

length bstr
Returns the length of bigstring bstr.

val sub : ?pos:int -> ?len:int -> t -> t

sub ?pos ?len bstr
Returns the sub-bigstring in bstr that starts at position pos and has length len. The sub-bigstring is a unique copy of the memory region, i.e. modifying it will not modify the original bigstring. Note that this is different than the behavior of the standard OCaml Array1.sub, which shares the memory.

pos : default = 0

len : default = Bigstring.length bstr - pos

val sub_shared : ?pos:int -> ?len:int -> t -> t

sub_shared ?pos ?len bstr
Returns the sub-bigstring in bstr that starts at position pos and has length len. 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.

pos : default = 0

len : default = Bigstring.length bstr - pos

val get : t -> int -> char

get t pos returns the character at pos

val set : t -> int -> char -> unit

set t pos sets the character at pos

val is_mmapped : t -> bool

is_mmapped bstr
Returns whether the bigstring bstr is memory-mapped.

Blitting

type ('src, 'dst) blit = src:'src ->
       ?src_pos:int -> ?src_len:int -> dst:'dst -> ?dst_pos:int -> unit -> unit

blit ~src ?src_pos ?src_len ~dst ?dst_pos () blits src_len characters from src starting at position src_pos to dst at position dst_pos.
Raises Invalid_argument if the designated ranges are out of bounds.

val blit : (t, t) blit

val blit_string_bigstring : (string, t) blit

val blit_bigstring_string : (t, string) blit

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 greater than or equal zero) and at most len (must be greater than or equal to min_len) bytes from file descriptor fd, and writes them to bigstring bstr starting at position pos.
Raises

Invalid_argument if the designated ranges are out of bounds.
IOError in the case of input errors, or on EOF if the minimum length could not be read.

Returns the number of bytes actually read.

NOTE: even if len is zero, there may still be errors when reading from the descriptor!

min_len : default = 0

pos : default = 0

len : default = length bstr - pos

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.
IOError in the case of input errors, or on EOF.

pos : default = 0

len : default = length bstr - pos

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.
IOError in the case of input errors, or on EOF.

pos : default = 0

len : default = length bstr - pos

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

Unix_error in the case of input errors.
Invalid_argument if the designated range is out of bounds.

Returns the number of bytes actually read and the socket address of the client.

pos : default = 0

len : default = length bstr - pos

val read_assume_fd_is_nonblocking : Unix.file_descr -> ?pos:int -> ?len:int -> t -> int

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

Unix_error in the case of input errors.
Invalid_argument if the designated range is out of bounds.

Returns the number of bytes actually read.

pos : default = 0

len : default = length bstr - pos

val input : ?min_len:int ->
       Pervasives.in_channel -> ?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 (must be greater than or equal to zero and smaller or equal to len), if possible, before returning) 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.
IOError in the case of input errors, or on premature EOF.

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.

min_len : default = 0

pos : default = 0

len : default = length bstr - pos

val really_input : Pervasives.in_channel -> ?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.
IOError in the case of input errors, or on premature EOF.

pos : default = 0

len : default = length bstr - pos

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.
IOError in the case of output errors.

pos : default = 0

len : default = length bstr - pos

val really_send_no_sigpipe : (Unix.file_descr -> ?pos:int -> ?len:int -> t -> unit) 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.
IOError in the case of output errors.

val send_nonblocking_no_sigpipe : (Unix.file_descr -> ?pos:int -> ?len:int -> t -> int option)
       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.
Raises

Invalid_argument if the designated range is out of bounds.
Unix_error in the case of output errors.

Returns Some bytes_written, or None if the operation would have blocked.

val sendto_nonblocking_no_sigpipe : (Unix.file_descr ->
        ?pos:int -> ?len:int -> t -> Unix.sockaddr -> int option)
       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.
Raises

Invalid_argument if the designated range is out of bounds.
Unix_error in the case of output errors.

Returns Some bytes_written, or None if the operation would have blocked.

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

Unix_error in the case of output errors.
Invalid_argument if the designated range is out of bounds.

Returns the number of bytes actually written.

pos : default = 0

len : default = length bstr - pos

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

Unix_error in the case of output errors.
Invalid_argument if the designated range is out of bounds.

Returns the number of bytes actually written.

pos : default = 0

len : default = length bstr - pos

val writev : Unix.file_descr -> ?count:int -> t Unix.IOVec.t array -> int

writev fd ?count iovecs writes count iovecs of bigstrings to file descriptor fd.
Raises

Unix_error in the case of output errors.
Invalid_argument if count is out of range.

Returns the number of bytes written.

count : default = Array.length iovecs

val writev_assume_fd_is_nonblocking : Unix.file_descr -> ?count:int -> t 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.
Raises

Unix_error in the case of output errors.
Invalid_argument if the designated range is out of bounds.

Returns the number of bytes actually written.

count : default = Array.length iovecs

val sendmsg_nonblocking_no_sigpipe : (Unix.file_descr ->
        ?count:int -> t Unix.IOVec.t array -> int option)
       Or_error.t

sendmsg_nonblocking_no_sigpipe sock ?count iovecs sends count iovecs of bigstrings to socket sock.
Raises

Unix_error in the case of output errors.
Invalid_argument if count is out of range.

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.

val output : ?min_len:int ->
       Pervasives.out_channel -> ?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 (must be equal to or greater than zero), if possible, before returning) from bigstring bstr starting at position pos to output channel oc.
Raises

Invalid_argument if the designated range is out of bounds.
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.

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.

min_len : default = 0

pos : default = 0

len : default = length bstr - pos

val really_output : Pervasives.out_channel -> ?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.
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.

pos : default = 0

len : default = length bstr - pos

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.

Unsafe functions

val unsafe_blit : src:t ->
       src_pos:int -> dst:t -> dst_pos:int -> len:int -> unit

unsafe_blit ~src ~src_pos ~dst ~dst_pos ~len similar to Bigstring.blit, but does not perform any bounds checks. Will crash on bounds errors! Owing to special handling for very large copies, bigstring_blit_stub may call Caml runtime functions, and hence cannot be flagged as noalloc.

val unsafe_blit_string_bigstring : src:string ->
       src_pos:int -> dst:t -> dst_pos:int -> len:int -> unit

unsafe_blit_string_bigstring ~src ~src_pos ~dst ~dst_pos ~len similar to Bigstring.blit_string_bigstring, but does not perform any bounds checks. Will crash on bounds errors!

val unsafe_blit_bigstring_string : src:t ->
       src_pos:int -> dst:string -> dst_pos:int -> len:int -> unit

unsafe_blit_bigstring_string ~src ~src_pos ~dst ~dst_pos ~len similar to Bigstring.blit_bigstring_string, but does not perform any bounds checks. Will crash on bounds errors!

val unsafe_read_assume_fd_is_nonblocking : Unix.file_descr -> pos:int -> len:int -> t -> int

unsafe_read_assume_fd_is_nonblocking fd ~pos ~len bstr 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 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 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 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 similar to Bigstring.really_recv, but does not perform any bounds checks. Will crash on bounds errors!

val unsafe_input : min_len:int ->
       Pervasives.in_channel -> pos:int -> len:int -> t -> int

unsafe_input ~min_len ic ~pos ~len bstr similar to Bigstring.input, 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 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) Or_error.t

unsafe_really_send_no_sigpipe sock ~pos ~len bstr 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 -> int option)
       Or_error.t

unsafe_send_nonblocking_no_sigpipe sock ~pos ~len bstr similar to Bigstring.send_nonblocking_no_sigpipe, but does not perform any bounds checks. Will crash on bounds errors!

val unsafe_output : min_len:int ->
       Pervasives.out_channel -> pos:int -> len:int -> t -> int

unsafe_output ~min_len oc ~pos ~len bstr similar to Bigstring.output, but does not perform any bounds checks. Will crash on bounds errors!

val unsafe_writev : Unix.file_descr -> t Unix.IOVec.t array -> int -> int

unsafe_writev fd iovecs count 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 Unix.IOVec.t array -> int -> int option)
       Or_error.t

unsafe_sendmsg_nonblocking_no_sigpipe fd iovecs count similar to Bigstring.sendmsg_nonblocking_no_sigpipe, but does not perform any bounds checks. Will crash on bounds errors!

Search

val find : ?pos:int -> ?len:int -> char -> t -> int option

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.

pos : default = 0

len : default = length bstr - pos

Destruction

val unsafe_destroy : t -> unit

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_get_int16_le : t -> pos:int -> int

val unsafe_get_int16_be : t -> pos:int -> int

val unsafe_set_int16_le : t -> pos:int -> int -> unit

val unsafe_set_int16_be : t -> pos:int -> int -> unit

val unsafe_get_uint16_le : t -> pos:int -> int

val unsafe_get_uint16_be : t -> pos:int -> int

val unsafe_set_uint16_le : t -> pos:int -> int -> unit

val unsafe_set_uint16_be : t -> pos:int -> int -> unit

val unsafe_get_int32_le : t -> pos:int -> int

val unsafe_get_int32_be : t -> pos:int -> int

val unsafe_set_int32_le : t -> pos:int -> int -> unit

val unsafe_set_int32_be : t -> pos:int -> int -> unit

val unsafe_get_int64_le_exn : t -> pos:int -> int

val unsafe_get_int64_be_exn : t -> pos:int -> int

val unsafe_set_int64_le : t -> pos:int -> int -> unit

val unsafe_set_int64_be : t -> pos:int -> int -> unit

val unsafe_get_int32_t_le : t -> pos:int -> Int32.t

val unsafe_get_int32_t_be : t -> pos:int -> Int32.t

val unsafe_set_int32_t_le : t -> pos:int -> Int32.t -> unit

val unsafe_set_int32_t_be : t -> pos:int -> Int32.t -> unit

val unsafe_get_int64_t_le : t -> pos:int -> Int64.t

val unsafe_get_int64_t_be : t -> pos:int -> Int64.t

val unsafe_set_int64_t_le : t -> pos:int -> Int64.t -> unit

val unsafe_set_int64_t_be : t -> pos:int -> Int64.t -> unit

val t_of_sexp : Sexplib.Sexp.t -> t

val sexp_of_t : t -> Sexplib.Sexp.t

val bin_t : t Bin_prot.Type_class.t

val bin_read_t : t Bin_prot.Read_ml.reader

val bin_read_t_ : t Bin_prot.Unsafe_read_c.reader

val bin_read_t__ : (int -> t) Bin_prot.Unsafe_read_c.reader

val bin_reader_t : t Bin_prot.Type_class.reader

val bin_size_t : t Bin_prot.Size.sizer

val bin_write_t : t Bin_prot.Write_ml.writer

val bin_write_t_ : t Bin_prot.Unsafe_write_c.writer

val bin_writer_t : t Bin_prot.Type_class.writer