Module Core_kernel__Bigstring

String type based on Bigarray, for use in I/O and C-bindings.

Types and exceptions

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

Type of bigstrings

include sig ... end
val bin_read_t : t Bin_prot.Read.reader
val __bin_read_t__ : (Core_kernel__.Import.int ‑> t) Bin_prot.Read.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.writer
val bin_writer_t : t Bin_prot.Type_class.writer
val bin_shape_t : Bin_prot.Shape.t
val compare : t ‑> t ‑> Core_kernel__.Import.int
val t_of_sexp : Sexplib.Sexp.t ‑> t
val sexp_of_t : t ‑> Sexplib.Sexp.t
type t_frozen = t

Type of bigstrings which support hashing. Note that mutation invalidates previous hashes.

include sig ... end
val bin_t_frozen : t_frozen Bin_prot.Type_class.t
val bin_read_t_frozen : t_frozen Bin_prot.Read.reader
val __bin_read_t_frozen__ : (Core_kernel__.Import.int ‑> t_frozen) Bin_prot.Read.reader
val bin_reader_t_frozen : t_frozen Bin_prot.Type_class.reader
val bin_size_t_frozen : t_frozen Bin_prot.Size.sizer
val bin_write_t_frozen : t_frozen Bin_prot.Write.writer
val bin_writer_t_frozen : t_frozen Bin_prot.Type_class.writer
val bin_shape_t_frozen : Bin_prot.Shape.t
val compare_t_frozen : t_frozen ‑> t_frozen ‑> Core_kernel__.Import.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 t_frozen_of_sexp : Sexplib.Sexp.t ‑> t_frozen
val sexp_of_t_frozen : t_frozen ‑> Sexplib.Sexp.t
include Core_kernel__.Import.Equal.S with type t := t
type t
include Core_kernel.Hexdump.S with type t := t
type t
module Hexdump : sig ... end

Creation and string conversion

val create : ?⁠max_mem_waiting_gc:Core_kernel.Byte_units.t ‑> Core_kernel__.Import.int ‑> t

create length

val init : Core_kernel__.Import.int ‑> f:(Core_kernel__.Import.int ‑> Core_kernel__.Import.char) ‑> t

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

val of_string : ?⁠pos:Core_kernel__.Import.int ‑> ?⁠len:Core_kernel__.Import.int ‑> Core_kernel__.Import.string ‑> t

of_string ?pos ?len str

val of_bytes : ?⁠pos:Core_kernel__.Import.int ‑> ?⁠len:Core_kernel__.Import.int ‑> Core_kernel__.Import.bytes ‑> t

of_bytes ?pos ?len str

val to_string : ?⁠pos:Core_kernel__.Import.int ‑> ?⁠len:Core_kernel__.Import.int ‑> t ‑> Core_kernel__.Import.string

to_string ?pos ?len bstr

val to_bytes : ?⁠pos:Core_kernel__.Import.int ‑> ?⁠len:Core_kernel__.Import.int ‑> t ‑> Core_kernel__.Import.bytes

to_bytes ?pos ?len bstr

val concat : ?⁠sep:t ‑> t Core_kernel__.Import.list ‑> t

concat ?sep list returns the concatenation of list with sep in between each.

Checking

val check_args : loc:Core_kernel__.Import.string ‑> pos:Core_kernel__.Import.int ‑> len:Core_kernel__.Import.int ‑> t ‑> Core_kernel__.Import.unit

check_args ~loc ~pos ~len bstr checks the position and length arguments pos and len for bigstrings bstr.

val get_opt_len : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int Core_kernel__.Import.option ‑> Core_kernel__.Import.int

get_opt_len bstr ~pos opt_len

Accessors

val length : t ‑> Core_kernel__.Import.int

length bstr

val sub_shared : ?⁠pos:Core_kernel__.Import.int ‑> ?⁠len:Core_kernel__.Import.int ‑> t ‑> t

sub_shared ?pos ?len bstr

external get : t ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.char = "%caml_ba_ref_1"

get t pos returns the character at pos

external set : t ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.char ‑> Core_kernel__.Import.unit = "%caml_ba_set_1"

set t pos sets the character at pos

external is_mmapped : t ‑> Core_kernel__.Import.bool = "bigstring_is_mmapped_stub"

is_mmapped bstr

Blitting

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.

include Core_kernel.Blit.S with type t := t
type t
val blit : (ttBase.Blit_intf.blit
val blito : (ttBase.Blit_intf.blito
val unsafe_blit : (ttBase.Blit_intf.blit
val sub : (ttBase.Blit_intf.sub
val subo : (ttBase.Blit_intf.subo
module To_string : sig ... end
module From_string : Core_kernel.Blit.S_distinct with type src := Core_kernel__.Import.string with type dst := t
module To_bytes : Core_kernel.Blit.S_distinct with type src := t with type dst := Core_kernel__.Import.bytes
module From_bytes : Core_kernel.Blit.S_distinct with type src := Core_kernel__.Import.bytes with type dst := t

Reading/writing bin-prot

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:Core_kernel__.Import.int ‑> 'a Bin_prot.Type_class.writer ‑> 'a ‑> Core_kernel__.Import.int

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:Core_kernel__.Import.int ‑> ?⁠len:Core_kernel__.Import.int ‑> 'a Bin_prot.Type_class.reader ‑> ('a * Core_kernel__.Import.int) Core_kernel.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:Core_kernel__.Import.int ‑> ?⁠len:Core_kernel__.Import.int ‑> 'a Bin_prot.Type_class.reader ‑> [ `Invalid_data of Core_kernel.Error.t | `Not_enough_data | `Ok of 'a * Core_kernel__.Import.int ]

Search

val find : ?⁠pos:Core_kernel__.Import.int ‑> ?⁠len:Core_kernel__.Import.int ‑> Core_kernel__.Import.char ‑> t ‑> Core_kernel__.Import.int Core_kernel__.Import.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.

external unsafe_find : t ‑> Core_kernel__.Import.char ‑> pos:Core_kernel__.Import.int ‑> len:Core_kernel__.Import.int ‑> Core_kernel__.Import.int = "bigstring_find"

Same as find, but does no bounds checking, and returns a negative value instead of None if char is not found.

Destruction

external unsafe_destroy : t ‑> Core_kernel__.Import.unit = "bigstring_destroy_stub"

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.

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

<accessor> ::= <unsafe><operation><type><endian> <unsafe> ::= unsafe_ | '' <operation> ::= get_ | set_ <type> ::= int8 | uint8 | int16 | uint16 | int32 | uint32 | int64 | uint64 <endian> ::= _le | _be | ''

The "unsafe_" prefix indicates that these functions do no bounds checking.

val get_int8 : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val set_int8 : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val get_uint8 : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val set_uint8 : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val unsafe_get_int8 : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val unsafe_set_int8 : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val unsafe_get_uint8 : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val unsafe_set_uint8 : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit

16-bit methods

val get_int16_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val get_int16_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val set_int16_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val set_int16_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val unsafe_get_int16_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val unsafe_get_int16_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val unsafe_set_int16_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val unsafe_set_int16_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val get_uint16_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val get_uint16_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val set_uint16_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val set_uint16_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val unsafe_get_uint16_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val unsafe_get_uint16_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val unsafe_set_uint16_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val unsafe_set_uint16_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit

32-bit methods

val get_int32_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val get_int32_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val set_int32_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val set_int32_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val unsafe_get_int32_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val unsafe_get_int32_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val unsafe_set_int32_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val unsafe_set_int32_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val get_uint32_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val get_uint32_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val set_uint32_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val set_uint32_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val unsafe_get_uint32_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val unsafe_get_uint32_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val unsafe_set_uint32_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val unsafe_set_uint32_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit

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:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val get_int64_be_exn : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val get_int64_le_trunc : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val get_int64_be_trunc : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val set_int64_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val set_int64_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val unsafe_get_int64_le_exn : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val unsafe_get_int64_be_exn : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val unsafe_get_int64_le_trunc : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val unsafe_get_int64_be_trunc : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val unsafe_set_int64_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val unsafe_set_int64_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit

64-bit unsigned values

val get_uint64_be_exn : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val get_uint64_le_exn : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val set_uint64_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val set_uint64_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val unsafe_get_uint64_be_exn : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val unsafe_get_uint64_le_exn : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int
val unsafe_set_uint64_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit
val unsafe_set_uint64_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel__.Import.int ‑> Core_kernel__.Import.unit

32-bit methods with full precision

val get_int32_t_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel.Int32.t
val get_int32_t_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel.Int32.t
val set_int32_t_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel.Int32.t ‑> Core_kernel__.Import.unit
val set_int32_t_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel.Int32.t ‑> Core_kernel__.Import.unit
val unsafe_get_int32_t_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel.Int32.t
val unsafe_get_int32_t_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel.Int32.t
val unsafe_set_int32_t_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel.Int32.t ‑> Core_kernel__.Import.unit
val unsafe_set_int32_t_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel.Int32.t ‑> Core_kernel__.Import.unit

64-bit methods with full precision

val get_int64_t_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel.Int64.t
val get_int64_t_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel.Int64.t
val set_int64_t_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel.Int64.t ‑> Core_kernel__.Import.unit
val set_int64_t_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel.Int64.t ‑> Core_kernel__.Import.unit
val unsafe_get_int64_t_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel.Int64.t
val unsafe_get_int64_t_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel.Int64.t
val unsafe_set_int64_t_le : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel.Int64.t ‑> Core_kernel__.Import.unit
val unsafe_set_int64_t_be : t ‑> pos:Core_kernel__.Import.int ‑> Core_kernel.Int64.t ‑> Core_kernel__.Import.unit
val get_tail_padded_fixed_string : padding:Core_kernel__.Import.char ‑> t ‑> pos:Core_kernel__.Import.int ‑> len:Core_kernel__.Import.int ‑> Core_kernel__.Import.unit ‑> Core_kernel__.Import.string

Similar to Binary_packing.unpack_tail_padded_fixed_string and .pack_tail_padded_fixed_string.

val set_tail_padded_fixed_string : padding:Core_kernel__.Import.char ‑> t ‑> pos:Core_kernel__.Import.int ‑> len:Core_kernel__.Import.int ‑> Core_kernel__.Import.string ‑> Core_kernel__.Import.unit
val get_head_padded_fixed_string : padding:Core_kernel__.Import.char ‑> t ‑> pos:Core_kernel__.Import.int ‑> len:Core_kernel__.Import.int ‑> Core_kernel__.Import.unit ‑> Core_kernel__.Import.string
val set_head_padded_fixed_string : padding:Core_kernel__.Import.char ‑> t ‑> pos:Core_kernel__.Import.int ‑> len:Core_kernel__.Import.int ‑> Core_kernel__.Import.string ‑> Core_kernel__.Import.unit