val create : ?max_mem_waiting_gc:Byte_units.t->Base.Int.t ->t
create length
parametermax_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.
val init : Base.Int.t ->f:(Base.Int.t ->Base.Char.t)->t
init n ~f creates a bigstring t of length n, with t.{i} = f i
val of_string : ?pos:Base.Int.t ->?len:Base.Int.t ->Base.String.t ->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.
parameterpos
default = 0
parameterlen
default = String.length str - pos
val of_bytes : ?pos:Base.Int.t ->?len:Base.Int.t ->Base.Bytes.t ->t
of_bytes ?pos ?len str
returns
a new bigstring that is equivalent to the subbytes of length len in str starting at position pos.
parameterpos
default = 0
parameterlen
default = Bytes.length str - pos
val to_string : ?pos:Base.Int.t ->?len:Base.Int.t ->t->Base.String.t
to_string ?pos ?len bstr
returns
a new string that is equivalent to the substring of length len in bstr starting at position pos.
parameterpos
default = 0
parameterlen
default = length bstr - pos
raisesInvalid_argument
if the string would exceed runtime limits.
val to_bytes : ?pos:Base.Int.t ->?len:Base.Int.t ->t->Base.Bytes.t
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.
concat ?sep list returns the concatenation of list with sep in between each.
Checking
val check_args :
loc:Base.String.t ->pos:Base.Int.t ->len:Base.Int.t ->t->Base.Unit.t
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.t ->Base.Int.t Base.Option.t->Base.Int.t
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.
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.
raisesFailure
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 sub_shared : ?pos:Base.Int.t ->?len:Base.Int.t ->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.
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.
val write_bin_prot :
t->?pos:Base.Int.t ->'aBin_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 ->'aBin_prot.Type_class.reader->('a * Base.Int.t)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 ->'aBin_prot.Type_class.reader->[ `Invalid_data of Error.t| `Not_enough_data| `Ok of 'a * Base.Int.t ]
Search
val find :
?pos:Base.Int.t ->?len:Base.Int.t ->Base.Char.t ->t->Base.Int.t Base.Option.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.
parameterpos
default = 0
parameterlen
default = length bstr - pos
val unsafe_find :
t->Base.Char.t ->pos:Base.Int.t ->len:Base.Int.t ->Base.Int.t
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.
raisesFailure
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.
Accessors for parsing binary values, analogous to binary_packing
These are in Bigstring rather than a separate module because:
1) Existing binary_packing requires copies and does not work with bigstrings 2) The accessors rely on the implementation of bigstring, and hence should change should the implementation of bigstring move away from Bigarray. 3) Bigstring already has some external C functions, so it didn't require many changes to the OMakefile ^_^.
In a departure from Binary_packing, the naming conventions are chosen to be close to C99 stdint types, as it's a more standard description and it is somewhat useful in making compact macros for the implementations. The accessor names contain endian-ness to allow for branch-free implementations
val set_int32_le : t->pos:Base.Int.t ->Base.Int.t ->Base.Unit.t
val set_int32_be : t->pos:Base.Int.t ->Base.Int.t ->Base.Unit.t
val unsafe_get_int32_le : t->pos:Base.Int.t ->Base.Int.t
val unsafe_get_int32_be : t->pos:Base.Int.t ->Base.Int.t
val unsafe_set_int32_le : t->pos:Base.Int.t ->Base.Int.t ->Base.Unit.t
val unsafe_set_int32_be : t->pos:Base.Int.t ->Base.Int.t ->Base.Unit.t
val get_uint32_le : t->pos:Base.Int.t ->Base.Int.t
val get_uint32_be : t->pos:Base.Int.t ->Base.Int.t
val set_uint32_le : t->pos:Base.Int.t ->Base.Int.t ->Base.Unit.t
val set_uint32_be : t->pos:Base.Int.t ->Base.Int.t ->Base.Unit.t
val unsafe_get_uint32_le : t->pos:Base.Int.t ->Base.Int.t
val unsafe_get_uint32_be : t->pos:Base.Int.t ->Base.Int.t
val unsafe_set_uint32_le : t->pos:Base.Int.t ->Base.Int.t ->Base.Unit.t
val unsafe_set_uint32_be : t->pos:Base.Int.t ->Base.Int.t ->Base.Unit.t
Similar to the usage in binary_packing, the below methods are treating the value being read (or written), as an ocaml immediate integer, as such it is actually 63 bits. If the user is confident that the range of values used in practice will not require 64-bit precision (i.e. Less than Max_Long), then we can avoid allocation and use an immediate. If the user is wrong, an exception will be thrown (for get).
64-bit signed values
val get_int64_le_exn : t->pos:Base.Int.t ->Base.Int.t
val get_int64_be_exn : t->pos:Base.Int.t ->Base.Int.t
val get_int64_le_trunc : t->pos:Base.Int.t ->Base.Int.t
val get_int64_be_trunc : t->pos:Base.Int.t ->Base.Int.t
val set_int64_le : t->pos:Base.Int.t ->Base.Int.t ->Base.Unit.t
val set_int64_be : t->pos:Base.Int.t ->Base.Int.t ->Base.Unit.t
val unsafe_get_int64_le_exn : t->pos:Base.Int.t ->Base.Int.t
val unsafe_get_int64_be_exn : t->pos:Base.Int.t ->Base.Int.t
val unsafe_get_int64_le_trunc : t->pos:Base.Int.t ->Base.Int.t
val unsafe_get_int64_be_trunc : t->pos:Base.Int.t ->Base.Int.t
val unsafe_set_int64_le : t->pos:Base.Int.t ->Base.Int.t ->Base.Unit.t
val unsafe_set_int64_be : t->pos:Base.Int.t ->Base.Int.t ->Base.Unit.t
64-bit unsigned values
val get_uint64_be_exn : t->pos:Base.Int.t ->Base.Int.t
val get_uint64_le_exn : t->pos:Base.Int.t ->Base.Int.t
val set_uint64_le : t->pos:Base.Int.t ->Base.Int.t ->Base.Unit.t
val set_uint64_be : t->pos:Base.Int.t ->Base.Int.t ->Base.Unit.t
val unsafe_get_uint64_be_exn : t->pos:Base.Int.t ->Base.Int.t
val unsafe_get_uint64_le_exn : t->pos:Base.Int.t ->Base.Int.t
val unsafe_set_uint64_le : t->pos:Base.Int.t ->Base.Int.t ->Base.Unit.t
val unsafe_set_uint64_be : t->pos:Base.Int.t ->Base.Int.t ->Base.Unit.t