Types and exceptions
type t = (Base.Char.t, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t
Type of bigstrings
val compare : t -> t -> Base.Int.t
val sexp_of_t : t -> Ppx_sexp_conv_lib.Sexp.t
type t_frozen = t
Type of bigstrings which support hashing. Note that mutation invalidates previous hashes.
val compare_t_frozen : t_frozen -> t_frozen -> Base.Int.t
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
include module type of Base_bigstring with type t := t and type t_frozen := t_frozen
Types and exceptions
include Ppx_sexp_conv_lib.Sexpable.S with type t := t
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
include Base.Equal.S with type t := t
val equal : t Base.Equal.equal
Creation and string conversion
val create : ?max_mem_waiting_gc_in_bytes:Base.int -> Base.int -> t
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
approachmax_mem_waiting_gc_in_bytes
, 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 -> f:(Base.int -> Base.char) -> t
init n ~f
creates a bigstringt
of lengthn
, witht.{i} = f i
.
val of_string : ?pos:Base.int -> ?len:Base.int -> Base.string -> t
of_string ?pos ?len str
- returns
a new bigstring that is equivalent to the substring of length
len
instr
starting at positionpos
.
- parameter pos
default = 0
- parameter len
default =
String.length str - pos
val of_bytes : ?pos:Base.int -> ?len:Base.int -> Base.bytes -> t
of_bytes ?pos ?len str
- returns
a new bigstring that is equivalent to the subbytes of length
len
instr
starting at positionpos
.
- parameter pos
default = 0
- parameter len
default =
Bytes.length str - pos
val to_string : ?pos:Base.int -> ?len:Base.int -> t -> Base.string
to_string ?pos ?len bstr
- returns
a new string that is equivalent to the substring of length
len
inbstr
starting at positionpos
.
- parameter pos
default = 0
- parameter len
default =
length bstr - pos
- raises Invalid_argument
if the string would exceed runtime limits.
val to_bytes : ?pos:Base.int -> ?len:Base.int -> t -> Base.bytes
to_bytes ?pos ?len bstr
- returns
a new byte sequence that is equivalent to the substring of length
len
inbstr
starting at positionpos
.
- parameter pos
default = 0
- parameter len
default =
length bstr - pos
- raises Invalid_argument
if the bytes would exceed runtime limits.
val concat : ?sep:t -> t Base.list -> t
concat ?sep list
returns the concatenation oflist
withsep
in between each.
Checking
val check_args : loc:Base.string -> pos:Base.int -> len:Base.int -> t -> Base.unit
check_args ~loc ~pos ~len bstr
checks the position and length argumentspos
andlen
for bigstringsbstr
.- 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 -> Base.int Base.option -> Base.int
get_opt_len bstr ~pos opt_len
- returns
the length of a subbigstring in
bstr
starting at positionpos
and given optional lengthopt_len
. This function does not check the validity of its arguments. Usecheck_args
for that purpose.
Accessors
Blitting
include Base.Blit.S with type t := t
val blit : src:t -> src_pos:int -> dst:t -> dst_pos:int -> len:int -> unit
val blito : src:t -> ?src_pos:int -> ?src_len:int -> dst:t -> ?dst_pos:int -> unit -> unit
val unsafe_blit : src:t -> src_pos:int -> dst:t -> dst_pos:int -> len:int -> unit
val sub : t -> pos:int -> len:int -> t
val subo : ?pos:int -> ?len:int -> t -> t
module To_string : sig ... end
module From_string : Base.Blit.S_distinct with type src := Base.string with type dst := t
module To_bytes : Base.Blit.S_distinct with type src := t with type dst := Base.bytes
module From_bytes : Base.Blit.S_distinct with type src := Base.bytes with type dst := t
val memset : t -> pos:Base.int -> len:Base.int -> Base.char -> Base.unit
memset t ~pos ~len c
fillst
withc
within the range[pos, pos + len)
.
val memcmp : t -> pos1:Base.int -> t -> pos2:Base.int -> len:Base.int -> Base.int
memcmp t1 ~pos1 t2 ~pos2 ~len
is likecompare t1 t2
except performs the comparison on the subregions oft1
andt2
defined bypos1
,pos2
, andlen
.
Search
val find : ?pos:Base.int -> ?len:Base.int -> Base.char -> t -> Base.int Base.option
find ?pos ?len char t
returnsSome i
for the smallesti >= pos
such thatt.{i} = char
, orNone
if there is no suchi
.- parameter pos
default = 0
- parameter len
default =
length bstr - pos
val unsafe_find : t -> Base.char -> pos:Base.int -> len:Base.int -> Base.int
Same as
find
, but does no bounds checking, and returns a negative value instead ofNone
ifchar
is not found.
Accessors for parsing binary values, analogous to Binary_packing
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
16-bit methods
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
32-bit methods
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
64-bit signed values
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
64-bit unsigned values
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
32-bit methods with full precision
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
64-bit methods with full precision
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
module Private : sig ... end
Creation and string conversion
val create : ?max_mem_waiting_gc:Core_kernel__Byte_units0.t -> Base.Int.t -> t
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
approachmax_mem_waiting_gc
, the pressure in the garbage collector to be more agressive will increase.
- returns
a new bigstring having
length
. Content is undefined.
sub_shared ?pos ?len bstr
- returns
the sub-bigstring in
bstr
that starts at positionpos
and has lengthlen
. 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
Reading/writing bin-prot
val write_bin_prot : t -> ?pos:Base.Int.t -> 'a Bin_prot.Type_class.writer -> 'a -> Base.Int.t
write_bin_prot t writer a
writesa
tot
starting atpos
, and returns the index int
immediately after the last byte written. It raises ifpos < 0
or ifa
doesn't fit int
.
val read_bin_prot : t -> ?pos:Base.Int.t -> ?len:Base.Int.t -> 'a Bin_prot.Type_class.reader -> ('a * Base.Int.t) Or_error.t
The
read_bin_prot*
functions read from the region oft
starting atpos
of lengthlen
. They return the index int
immediately after the last byte read. They raise ifpos
andlen
don't describe a region oft
.
val read_bin_prot_verbose_errors : t -> ?pos:Base.Int.t -> ?len:Base.Int.t -> 'a Bin_prot.Type_class.reader -> [ `Invalid_data of Error.t | `Not_enough_data | `Ok of 'a * Base.Int.t ]
Destruction
val unsafe_destroy : t -> Base.Unit.t
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_destroy_and_resize : t -> len:Base.Int.t -> t
unsafe_destroy_and_resize bstr ~len
reallocates the memory backingbstr
and returns a new bigstring that starts at position 0 and has lengthlen
. Iflen
is greater thanlength 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 tobstr
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.
val get_tail_padded_fixed_string : padding:Base.Char.t -> t -> pos:Base.Int.t -> len:Base.Int.t -> Base.Unit.t -> Base.String.t
Similar to
Binary_packing.unpack_tail_padded_fixed_string
and.pack_tail_padded_fixed_string
.
val set_tail_padded_fixed_string : padding:Base.Char.t -> t -> pos:Base.Int.t -> len:Base.Int.t -> Base.String.t -> Base.Unit.t
val get_head_padded_fixed_string : padding:Base.Char.t -> t -> pos:Base.Int.t -> len:Base.Int.t -> Base.Unit.t -> Base.String.t
val set_head_padded_fixed_string : padding:Base.Char.t -> t -> pos:Base.Int.t -> len:Base.Int.t -> Base.String.t -> Base.Unit.t
module Unstable : sig ... end
module Stable : sig ... end