Module Base.Bytes

OCaml's byte sequence type, semantically similar to a char array, but taking less space in memory.

A byte sequence is a mutable data structure that contains a fixed-length sequence of bytes (of type char). Each byte can be indexed in constant time for reading or writing.

type t = bytes
include sig ... end
val t_of_sexp : Sexp.t ‑> t
val sexp_of_t : t ‑> Sexp.t

Common Interfaces

include Blit.S with type t := t
type t
val blit : (t, t) Base__.Blit_intf.blit
val blito : (t, t) Base__.Blit_intf.blito
val unsafe_blit : (t, t) Base__.Blit_intf.blit
val sub : (t, t) Base__.Blit_intf.sub
val subo : (t, t) Base__.Blit_intf.subo
include Comparable.S with type t := t
include Base__.Comparable_intf.Polymorphic_compare
include Comparisons.Infix
type t
val (>=) : t ‑> t ‑> bool
val (<=) : t ‑> t ‑> bool
val (=) : t ‑> t ‑> bool
val (>) : t ‑> t ‑> bool
val (<) : t ‑> t ‑> bool
val (<>) : t ‑> t ‑> bool
val equal : t ‑> t ‑> bool
val compare : t ‑> t ‑> int

compare t1 t2 returns 0 if t1 is equal to t2, a negative integer if t1 is less than t2, and a positive integer if t1 is greater than t2.

val min : t ‑> t ‑> t
val max : t ‑> t ‑> t
val ascending : t ‑> t ‑> int

ascending is identical to compare. descending x y = ascending y x. These are intended to be mnemonic when used like List.sort ~compare:ascending and List.sort ~cmp:descending, since they cause the list to be sorted in ascending or descending order, respectively.

val descending : t ‑> t ‑> int
val between : t ‑> low:t ‑> high:t ‑> bool

between t ~low ~high means low <= t <= high

val clamp_exn : t ‑> min:t ‑> max:t ‑> t

clamp_exn t ~min ~max returns t', the closest value to t such that between t' ~low:min ~high:max is true.

Raises if not (min <= max).

val clamp : t ‑> min:t ‑> max:t ‑> t Or_error.t
include Comparator.S with type t := t
type t
type comparator_witness
include Base__.Comparable_intf.Validate with type t := t
type t
val validate_lbound : min:t Maybe_bound.t ‑> t Validate.check
val validate_ubound : max:t Maybe_bound.t ‑> t Validate.check
val validate_bound : min:t Maybe_bound.t ‑> max:t Maybe_bound.t ‑> t Validate.check
include Stringable.S with type t := t
type t
val of_string : string ‑> t
val to_string : t ‑> string

Note that pp allocates in order to preserve the state of the byte sequence it was initially called with.

include Pretty_printer.S with type t := t
type t
val pp : Formatter.t ‑> t ‑> unit
module To_string : sig ... end
module From_string : Blit.S_distinct with type src := string and type dst := t
val create : int ‑> t

create len returns a newly-allocated and uninitialized byte sequence of length len. No guarantees are made about the contents of the return value.

val make : int ‑> char ‑> t

make len c returns a newly-allocated byte sequence of length len filled with the byte c.

val copy : t ‑> t

copy t returns a newly-allocated byte sequence that contains the same bytes as t.

val init : int ‑> f:(int ‑> char) ‑> t

init len ~f returns a newly-allocated byte sequence of length len with index i in the sequence being initialized with the result of f i.

val of_char_list : char list ‑> t

of_char_list l returns a newly-alloated byte sequence where each byte in the sequence corresponds to the byte in l at the same index.

val length : t ‑> int

length t returns the number of bytes in t.

val get : t ‑> int ‑> char

get t i returns the ith byte of t.

external unsafe_get : t ‑> int ‑> char = "%bytes_unsafe_get"
val set : t ‑> int ‑> char ‑> unit

set t i c sets the ith byte of t to c.

external unsafe_set : t ‑> int ‑> char ‑> unit = "%bytes_unsafe_set"
val fill : t ‑> pos:int ‑> len:int ‑> char ‑> unit

fill t ~pos ~len c modifies t in place, replacing all the bytes from pos to pos + len with c.

val tr : target:char ‑> replacement:char ‑> t ‑> unit

tr ~target ~replacement t modifies t in place, replacing every instance of target in s with replacement.

val to_list : t ‑> char list

to_list t returns the bytes in t as a list of chars.

val contains : ?⁠pos:int ‑> ?⁠len:int ‑> t ‑> char ‑> bool

contains ?pos ?len t c returns true iff c appears in t between pos and pos + len.

val max_length : int

Maximum length of a byte sequence, which is architecture-dependent. Attempting to create a Bytes larger than this will raise an exception.

Unsafe conversions (for advanced users)

This section describes unsafe, low-level conversion functions between bytes and string. They might not copy the internal data; used improperly, they can break the immutability invariant on strings provided by the -safe-string option. They are available for expert library authors, but for most purposes you should use the always-correct Bytes.to_string and Bytes.of_string instead.

val unsafe_to_string : no_mutation_while_string_reachable:t ‑> string

Unsafely convert a byte sequence into a string.

To reason about the use of unsafe_to_string, it is convenient to consider an "ownership" discipline. A piece of code that manipulates some data "owns" it; there are several disjoint ownership modes, including:

Unique ownership is linear: passing the data to another piece of code means giving up ownership (we cannot access the data again). A unique owner may decide to make the data shared (giving up mutation rights on it), but shared data may not become uniquely-owned again. unsafe_to_string s can only be used when the caller owns the byte sequence s -- either uniquely or as shared immutable data. The caller gives up ownership of s, and gains (the same mode of) ownership of the returned string. There are two valid use-cases that respect this ownership discipline:

  1. The first is creating a string by initializing and mutating a byte sequence that is never changed after initialization is performed. 

          let string_init len f : string =
        let s = Bytes.create len in
        for i = 0 to len - 1 do Bytes.set s i (f i) done;
        Bytes.unsafe_to_string ~no_mutation_while_string_reachable:s

    This function is safe because the byte sequence s will never be accessed or mutated after unsafe_to_string is called. The string_init code gives up ownership of s, and returns the ownership of the resulting string to its caller.

    Note that it would be unsafe if s was passed as an additional parameter to the function f as it could escape this way and be mutated in the future -- string_init would give up ownership of s to pass it to f, and could not call unsafe_to_string safely.

    We have provided the String.init, String.map and String.mapi functions to cover most cases of building new strings. You should prefer those over to_string or unsafe_to_string whenever applicable.

  2. The second is temporarily giving ownership of a byte sequence to a function that expects a uniquely owned string and returns ownership back, so that we can mutate the sequence again after the call ended. 

          let bytes_length (s : bytes) =
        String.length
          (Bytes.unsafe_to_string ~no_mutation_while_string_reachable:s)

    In this use-case, we do not promise that s will never be mutated after the call to bytes_length s. The String.length function temporarily borrows unique ownership of the byte sequence (and sees it as a string), but returns this ownership back to the caller, which may assume that s is still a valid byte sequence after the call. Note that this is only correct because we know that String.length does not capture its argument -- it could escape by a side-channel such as a memoization combinator. The caller may not mutate s while the string is borrowed (it has temporarily given up ownership). This affects concurrent programs, but also higher-order functions: if String.length returned a closure to be called later, s should not be mutated until this closure is fully applied and returns ownership.

val unsafe_of_string_promise_no_mutation : string ‑> t

Unsafely convert a shared string to a byte sequence that should not be mutated.

The same ownership discipline that makes unsafe_to_string correct applies to unsafe_of_string_promise_no_mutation, however unique ownership of string values is extremely difficult to reason about correctly in practice. As such, one should always assume strings are shared, never uniquely owned (For example, string literals are implicitly shared by the compiler, so you never uniquely own them)

The only case we have reasonable confidence is safe is if the produced bytes is shared -- used as an immutable byte sequence. This is possibly useful for incremental migration of low-level programs that manipulate immutable sequences of bytes (for example Marshal.from_bytes) and previously used the string type for this purpose.