Up

module Bigstring

: sig

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

Types and exceptions
#
type t = (char, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t

Type of bigstrings

Creation and string conversion
#
val create : ?max_mem_waiting_gc:Byte_units.t -> int -> t

create length

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 init : int -> f:(int -> char) -> t

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

#
val of_string : ?pos:int -> ?len:int -> string -> 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.
pos default = 0
len default = String.length str - pos
#
val to_string : ?pos:int -> ?len:int -> t -> string

to_string ?pos ?len bstr

Returns a new string that is equivalent to the substring of length len in bstr starting at position pos.
pos default = 0
len default = length bstr - pos
Raises Invalid_argument if the string would exceed runtime limits.
Checking
#
val check_args : loc:string -> pos:int -> len:int -> t -> unit

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:int -> int option -> int

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.
Accessors
#
val length : t -> int

length bstr

Returns the length of bigstring bstr.
#
val sub_shared : ?pos:int -> ?len:int -> 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.
pos default = 0
len default = Bigstring.length bstr - pos
#
external get : t -> int -> char = "%caml_ba_ref_1"

get t pos returns the character at pos

#
external set : t -> int -> char -> unit = "%caml_ba_set_1"

set t pos sets the character at pos

#
external is_mmapped : t -> bool = "bigstring_is_mmapped_stub" "noalloc"

is_mmapped bstr

Returns whether the bigstring bstr is memory-mapped.
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.

Raises Invalid_argument if the designated ranges are out of bounds.
include Blit.S with type t := t
#
module To_string : Blit.S_distinct with type src := t and type dst := string
#
module From_string : Blit.S_distinct with type src := string and type dst := t

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 bin_prot_size_header_length : int

The length of the size prefix is always 8 bytes at present. This is exposed so your program does not have to know this fact too.

#
val write_bin_prot : t -> ?pos:int -> 'a Bin_prot.Type_class.writer -> 'a -> 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:int -> ?len:int -> 'a Bin_prot.Type_class.reader -> ('a * int) 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:int -> ?len:int -> 'a Bin_prot.Type_class.reader -> [
| `Invalid_data of Error.t
| `Not_enough_data
| `Ok of 'a * int
]
Memory mapping
#
val map_file : shared:bool -> Unix.file_descr -> int -> t

map_file shared fd n memory-maps n characters of the data associated with descriptor fd to a bigstring. Iff shared is true, all changes to the bigstring will be reflected in the file.

Users must keep in mind that operations on the resulting bigstring may result in disk operations which block the runtime. This is true for pure OCaml operations (such as t.

<- 1), and for calls to blit. While some I/O operations may release the OCaml lock, users should not expect this to be done for all operations on a bigstring returned from map_file.

Search
#
val find : ?pos:int -> ?len:int -> char -> t -> int 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.

pos default = 0
len default = length bstr - pos
Destruction
#
external unsafe_destroy : t -> 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.

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_get_int8 : t -> pos:int -> int
#
val unsafe_set_int8 : t -> pos:int -> int -> unit
#
val unsafe_get_uint8 : t -> pos:int -> int
#
val unsafe_set_uint8 : t -> pos:int -> int -> unit
#
val unsafe_get_int16_le : t -> pos:int -> int
#
val unsafe_get_int16_be : t -> pos:int -> int
#
val unsafe_set_int16_le : t -> pos:int -> int -> unit
#
val unsafe_set_int16_be : t -> pos:int -> int -> unit
#
val unsafe_get_uint16_le : t -> pos:int -> int
#
val unsafe_get_uint16_be : t -> pos:int -> int
#
val unsafe_set_uint16_le : t -> pos:int -> int -> unit
#
val unsafe_set_uint16_be : t -> pos:int -> int -> unit
#
val unsafe_get_int32_le : t -> pos:int -> int
#
val unsafe_get_int32_be : t -> pos:int -> int
#
val unsafe_set_int32_le : t -> pos:int -> int -> unit
#
val unsafe_set_int32_be : t -> pos:int -> int -> unit
#
val unsafe_get_uint32_le : t -> pos:int -> int
#
val unsafe_get_uint32_be : t -> pos:int -> int
#
val unsafe_set_uint32_le : t -> pos:int -> int -> unit
#
val unsafe_set_uint32_be : t -> pos:int -> int -> unit
#
val unsafe_get_int64_le_exn : t -> pos:int -> int
#
val unsafe_get_int64_be_exn : t -> pos:int -> int
#
val unsafe_set_int64_le : t -> pos:int -> int -> unit
#
val unsafe_set_int64_be : t -> pos:int -> int -> unit
#
val unsafe_get_int64_le_trunc : t -> pos:int -> int
#
val unsafe_get_int64_be_trunc : t -> pos:int -> int
#
val unsafe_get_int32_t_le : t -> pos:int -> Int32.t
#
val unsafe_get_int32_t_be : t -> pos:int -> Int32.t
#
val unsafe_set_int32_t_le : t -> pos:int -> Int32.t -> unit
#
val unsafe_set_int32_t_be : t -> pos:int -> Int32.t -> unit
#
val unsafe_get_int64_t_le : t -> pos:int -> Int64.t
#
val unsafe_get_int64_t_be : t -> pos:int -> Int64.t
#
val unsafe_set_int64_t_le : t -> pos:int -> Int64.t -> unit
#
val unsafe_set_int64_t_be : t -> pos:int -> Int64.t -> unit
#
val get_padded_fixed_string : padding:char -> t -> pos:int -> len:int -> unit -> string
#
val set_padded_fixed_string : padding:char -> t -> pos:int -> len:int -> string -> unit
#
val t_of_sexp : Sexplib.Sexp.t -> t
#
val sexp_of_t : t -> Sexplib.Sexp.t
#
val bin_t : t Bin_prot.Type_class.t
#
val bin_read_t : t Bin_prot.Read.reader
#
val __bin_read_t__ : (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
end