Module Core_kernel.Bigstring

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 approach max_mem_waiting_gc, 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

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

• Parameter pos: default = 0
• Parameter len: default = String.length str - pos

of_bytes ?pos ?len str returns a new bigstring that is equivalent to the subbytes of length len in str starting at position pos.

• Parameter pos: default = 0
• Parameter len: default = Bytes.length str - pos

to_string ?pos ?len bstr returns a new string that is equivalent to the substring of length len in bstr starting at position pos.

• Parameter pos: default = 0
• Parameter len: default = length bstr - pos
• Raises Invalid_argument: if the string would exceed runtime limits.

to_bytes ?pos ?len bstr returns a new byte sequence that is equivalent to the substring of length len in bstr starting at position pos.

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

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.

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 check_args for that purpose.

length bstr returns the length of bigstring bstr.

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.

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.

• Parameter pos: default = 0
• Parameter len: default = Bigstring.length bstr - pos

get t pos returns the character at pos

set t pos sets the character at pos

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

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.

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.

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.

Similar to Binary_packing.unpack_tail_padded_fixed_string and .pack_tail_padded_fixed_string.