Previous  Up  Next

Module Bigstring

module Bigstring: sig .. end
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
Returns a new bigstring having length. Content is undefined.
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.
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
Raises Invalid_argument if the string would exceed runtime limits.
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

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 Bigstring.check_args for that purpose.

Accessors

val length : t -> int
length bstr
Returns the length of bigstring bstr.
val sub : ?pos:int -> ?len:int -> t -> t
sub ?pos ?len bstr
Returns the sub-bigstring in bstr that starts at position pos and has length len. The sub-bigstring is a unique copy of the memory region, i.e. modifying it will not modify the original bigstring. Note that this is different than the behavior of the standard OCaml Array1.sub, which shares the memory.
pos : default = 0
len : default = Bigstring.length bstr - pos
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
val get : t -> int -> char
get t pos returns the character at pos
val set : t -> int -> char -> unit
set t pos sets the character at pos
val is_mmapped : t -> bool
is_mmapped bstr
Returns whether the bigstring bstr is memory-mapped.

Blitting

type ('src, 'dst) blit = src:'src ->
       ?src_pos:int -> ?src_len:int -> dst:'dst -> ?dst_pos:int -> unit -> unit
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.
val blit : (t, t) blit
val blit_string_bigstring : (string, t) blit
val blit_bigstring_string : (t, string) blit

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.

Unsafe functions

val unsafe_blit : src:t ->
       src_pos:int -> dst:t -> dst_pos:int -> len:int -> unit
unsafe_blit ~src ~src_pos ~dst ~dst_pos ~len similar to Bigstring.blit, but does not perform any bounds checks. Will crash on bounds errors! Owing to special handling for very large copies, bigstring_blit_stub may call Caml runtime functions, and hence cannot be flagged as noalloc.
val unsafe_blit_string_bigstring : src:string ->
       src_pos:int -> dst:t -> dst_pos:int -> len:int -> unit
unsafe_blit_string_bigstring ~src ~src_pos ~dst ~dst_pos ~len similar to Bigstring.blit_string_bigstring, but does not perform any bounds checks. Will crash on bounds errors!
val unsafe_blit_bigstring_string : src:t ->
       src_pos:int -> dst:string -> dst_pos:int -> len:int -> unit
unsafe_blit_bigstring_string ~src ~src_pos ~dst ~dst_pos ~len similar to Bigstring.blit_bigstring_string, but does not perform any bounds checks. Will crash on bounds errors!


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

val unsafe_destroy : t -> unit
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_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_ml.reader
val bin_read_t_ : t Bin_prot.Unsafe_read_c.reader
val bin_read_t__ : (int -> t) Bin_prot.Unsafe_read_c.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_ml.writer
val bin_write_t_ : t Bin_prot.Unsafe_write_c.writer
val bin_writer_t : t Bin_prot.Type_class.writer

Creation and string conversion


create length

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

of_string ?pos ?len str

to_string ?pos ?len bstr

Checking


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

get_opt_len bstr ~pos opt_len

Accessors


length bstr

sub ?pos ?len bstr

sub_shared ?pos ?len bstr

get t pos returns the character at pos

set t pos sets the character at pos

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.

Memory mapping


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.

Unsafe functions


unsafe_blit ~src ~src_pos ~dst ~dst_pos ~len similar to Bigstring.blit, but does not perform any bounds checks. Will crash on bounds errors! Owing to special handling for very large copies, bigstring_blit_stub may call Caml runtime functions, and hence cannot be flagged as noalloc.

unsafe_blit_string_bigstring ~src ~src_pos ~dst ~dst_pos ~len similar to Bigstring.blit_string_bigstring, but does not perform any bounds checks. Will crash on bounds errors!

unsafe_blit_bigstring_string ~src ~src_pos ~dst ~dst_pos ~len similar to Bigstring.blit_bigstring_string, but does not perform any bounds checks. Will crash on bounds errors!



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.

Destruction


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.