String type based on Bigarray, for use in I/O and C-bindings
create length
create approach max_mem_waiting_gc,
the pressure in the garbage collector to be more agressive will increase.
length.
Content is undefined.
init n ~f creates a bigstring t of length n, with t.{i} = f i
of_string ?pos ?len str
len in str starting at position pos.
String.length str - pos
to_string ?pos ?len bstr
len in bstr starting at position pos.
length bstr - pos
Invalid_argument if the string would exceed runtime limits.
check_args ~loc ~pos ~len bstr checks the position and length
arguments pos and len for bigstrings bstr.
Invalid_argument if these arguments are illegal for the given
bigstring using loc to indicate the calling context.
get_opt_len bstr ~pos opt_len
bstr starting at position pos and given optional length
opt_len. This function does not check the validity of its
arguments. Use check_args for that purpose.
is_mmapped bstr
bstr is
memory-mapped.
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.
Invalid_argument if the designated ranges are out of bounds.
These functions write the "size-prefixed" bin-prot format that is used by, e.g.,
async's Writer.write_bin_prot, Reader.read_bin_prot and
Unpack_buffer.Unpack_one.create_bin_prot.
The length of the size prefix is always 8 bytes at present. This is exposed so your program does not have to know this fact too.
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.
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.
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), 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.
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.
length bstr - pos
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.
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.