Module Base__.Bytes
include Base.Sexpable.S with type t := t
val t_of_sexp : Sexplib0.Sexp.t -> t
val sexp_of_t : t -> Sexplib0.Sexp.t
val t_sexp_grammar : Base.Sexp.Private.Raw_grammar.t
Common Interfaces
include Base.Blit.S with type t := 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 Base.Comparable.S with type t := t
include Base__.Comparable_intf.Polymorphic_compare
val ascending : t -> t -> int
ascending
is identical tocompare
.descending x y = ascending y x
. These are intended to be mnemonic when used likeList.sort ~compare:ascending
andList.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
meanslow <= t <= high
val clamp_exn : t -> min:t -> max:t -> t
clamp_exn t ~min ~max
returnst'
, the closest value tot
such thatbetween t' ~low:min ~high:max
is true.Raises if
not (min <= max)
.
val clamp : t -> min:t -> max:t -> t Base.Or_error.t
include Base.Comparator.S with type t := t
val comparator : (t, comparator_witness) Base.Comparator.comparator
include Base__.Comparable_intf.Validate with type t := t
val validate_lbound : min:t Base.Maybe_bound.t -> t Base.Validate.check
val validate_ubound : max:t Base.Maybe_bound.t -> t Base.Validate.check
val validate_bound : min:t Base.Maybe_bound.t -> max:t Base.Maybe_bound.t -> t Base.Validate.check
include Base.Stringable.S with type t := t
Note that pp
allocates in order to preserve the state of the byte sequence it was initially called with.
module To_string : sig ... end
module From_string : Base.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 lengthlen
. 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 lengthlen
filled with the bytec
.
val map : t -> f:(char -> char) -> t
map f t
applies functionf
to every byte, in order, and builds the byte sequence with the results returned byf
.
val mapi : t -> f:(int -> char -> char) -> t
Like
map
, but passes each character's index tof
along with the char.
val init : int -> f:(int -> char) -> t
init len ~f
returns a newly-allocated byte sequence of lengthlen
with indexi
in the sequence being initialized with the result off i
.
val of_char_list : char list -> t
of_char_list l
returns a newly-allocated byte sequence where each byte in the sequence corresponds to the byte inl
at the same index.
val length : t -> int
length t
returns the number of bytes int
.
val get : t -> int -> char
get t i
returns thei
th byte oft
.
val unsafe_get : t -> int -> char
val set : t -> int -> char -> unit
set t i c
sets thei
th byte oft
toc
.
val unsafe_set : t -> int -> char -> unit
val fill : t -> pos:int -> len:int -> char -> unit
fill t ~pos ~len c
modifiest
in place, replacing all the bytes frompos
topos + len
withc
.
val tr : target:char -> replacement:char -> t -> unit
tr ~target ~replacement t
modifiest
in place, replacing every instance oftarget
ins
withreplacement
.
val tr_multi : target:string -> replacement:string -> (t -> unit) Base.Staged.t
tr_multi ~target ~replacement
returns an in-place function that replaces every instance of a character intarget
with the corresponding character inreplacement
.If
replacement
is shorter thantarget
, it is lengthened by repeating its last character. Emptyreplacement
is illegal unlesstarget
also is.If
target
contains multiple copies of the same character, the last correspondingreplacement
character is used. Note that character ranges are not supported, so~target:"a-z"
means the literal characters'a'
,'-'
, and'z'
.
val to_list : t -> char list
to_list t
returns the bytes int
as a list of chars.
val to_array : t -> char array
to_array t
returns the bytes int
as an array of chars.
val fold : t -> init:'a -> f:('a -> char -> 'a) -> 'a
fold a ~f ~init:b
isf a1 (f a2 (...))
val foldi : t -> init:'a -> f:(int -> 'a -> char -> 'a) -> 'a
foldi
works similarly tofold
, but also passes the index of each character tof
.
val contains : ?pos:int -> ?len:int -> t -> char -> bool
contains ?pos ?len t c
returnstrue
iffc
appears int
betweenpos
andpos + 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: the data may be accessed and mutated
- Shared ownership: the data has several owners, that may only access it, not mutate it.
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 sequences
-- either uniquely or as shared immutable data. The caller gives up ownership ofs
, and gains (the same mode of) ownership of the returned string. There are two valid use-cases that respect this ownership discipline: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 afterunsafe_to_string
is called. Thestring_init
code gives up ownership ofs
, 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 functionf
as it could escape this way and be mutated in the future --string_init
would give up ownership ofs
to pass it tof
, and could not callunsafe_to_string
safely.We have provided the
String.init
,String.map
andString.mapi
functions to cover most cases of building new strings. You should prefer those overto_string
orunsafe_to_string
whenever applicable.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 tobytes_length s
. TheString.length
function temporarily borrows unique ownership of the byte sequence (and sees it as astring
), but returns this ownership back to the caller, which may assume thats
is still a valid byte sequence after the call. Note that this is only correct because we know thatString.length
does not capture its argument -- it could escape by a side-channel such as a memoization combinator. The caller may not mutates
while the string is borrowed (it has temporarily given up ownership). This affects concurrent programs, but also higher-order functions: ifString.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 tounsafe_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 exampleMarshal
.from_bytes) and previously used thestring
type for this purpose.