Module Core_kernel.Bigstring

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

Types and exceptions

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
val compare : t -> t -> Base.int
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
val equal : t Base.Equal.equal
val init : Base.int -> f:(Base.int -> Base.char) -> t
val of_string : ?pos:Base.int -> ?len:Base.int -> Base.string -> t
val of_bytes : ?pos:Base.int -> ?len:Base.int -> Base.bytes -> t
val to_string : ?pos:Base.int -> ?len:Base.int -> t -> Base.string
val to_bytes : ?pos:Base.int -> ?len:Base.int -> t -> Base.bytes
val concat : ?sep:t -> t Base.list -> t
val check_args : loc:Base.string -> pos:Base.int -> len:Base.int -> t -> Base.unit
val get_opt_len : t -> pos:Base.int -> Base.int Base.option -> Base.int
val length : t -> Base.int
val get : t -> Base.int -> Base.char
val set : t -> Base.int -> Base.char -> Base.unit
val is_mmapped : t -> Base.bool
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
val copy : t -> t
module To_string : sig ... end
module From_string : sig ... end
module To_bytes : sig ... end
module From_bytes : sig ... end
val memset : t -> pos:Base.int -> len:Base.int -> Base.char -> Base.unit
val memcmp : t -> pos1:Base.int -> t -> pos2:Base.int -> len:Base.int -> Base.int
val find : ?pos:Base.int -> ?len:Base.int -> Base.char -> t -> Base.int Base.option
val unsafe_find : t -> Base.char -> pos:Base.int -> len:Base.int -> Base.int
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
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
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
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
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
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
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
include Hexdump.S with type t := t
module Hexdump : 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 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 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.

  • parameter pos

    default = 0

  • parameter len

    default = Bigstring.length bstr - pos

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:Base.Int.t -> 'a Bin_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 -> 'a Bin_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 -> '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 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.

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