base_bigstring

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

Types and exceptions

include Ppx_compare_lib.Comparable.S with type t := t
val compare : t -> t -> int
include Sexplib0.Sexpable.S with type t := t
val t_of_sexp : Sexplib0.Sexp.t -> t
val sexp_of_t : t -> Sexplib0.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
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 -> Sexplib0.Sexp.t
val t_frozen_of_sexp : Sexplib0.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 approach max_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 bigstring t of length n, with t.{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 in str starting at position pos.

  • 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 in str starting at position pos.

  • 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 in bstr starting at position pos.

  • 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 in bstr starting at position pos.

  • 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 of list with sep 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 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: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 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 -> Base.int

length bstr

  • returns

    the length of bigstring bstr.

val get : t -> Base.int -> Base.char

get t pos returns the character at pos

val set : t -> Base.int -> Base.char -> Base.unit

set t pos sets the character at pos

val is_mmapped : t -> Base.bool

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 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
val copy : 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 fills t with c within the range [pos, pos + len).

Memcmp

val memcmp : t -> pos1:Base.int -> t -> pos2:Base.int -> len:Base.int -> Base.int

memcmp t1 ~pos1 t2 ~pos2 ~len is like compare t1 t2 except performs the comparison on the subregions of t1 and t2 defined by pos1, pos2, and len.

val memcmp_bytes : t -> pos1:Base.int -> Base.Bytes.t -> pos2:Base.int -> len:Base.int -> Base.int

memcmp_bytes, for efficient memcmp between Bigstring and Bytes data.

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

  • 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 of None if char is not found.

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 jbuild ^_^.

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 and silently truncate out-of-range numeric arguments.

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

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: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 Int_repr : sig ... end
module Private : sig ... end