module Cap:sig
..end
Capabilities for strings.
This modules provides the same set of features as String
, but
with the added twist that strings can be made read-only or write-only.
Read-only strings may then be safely shared and distributed.
type 'a
t
The type of capability strings.
If 'a
contains [`Read]
, the contents of the string may be read.
If 'a
contains [`Write]
, the contents of the string may be written.
Other (user-defined) capabilities may be added without loss of
performance or features. For instance, a string could be labelled
[`Read | `UTF8]
to state that it contains UTF-8 encoded data and
may be used only for reading. Conversely, a string labelled with
[]
(i.e. nothing) can neither be read nor written. It can only
be compared for textual equality using OCaml's built-in compare
or for physical equality using OCaml's built-in ==
.
val length : 'a t -> int
val is_empty : 'a t -> bool
val get : [> `Read ] t -> int -> char
val set : [> `Write ] t -> int -> char -> unit
val create : int -> 'a t
val of_string : Stdlib.Bytes.t -> 'a t
Adopt a regular byte sequence.
One could give a perfectly safe semantics to
an of_string : string -> _ t
function, but this
requires making a copy of the string. Previous
versions of this interface advertised the absence
of performance overhead, so it's better to warn
the user and let them decide (through the use of
either Bytes.of_string or Bytes.unsafe_of_string)
whether they can safely avoid a copy or need to
insert one.
val of_bytes : Stdlib.Bytes.t -> 'a t
Adopt a regular byte sequence.
Note that adopting a byte sequence, even at the restrictive
`Read
type, does not make a copy. Having a `Read
string
prevents you (and anyone you pass it to) from writing it, but
your parent may have knowledge of the string at a more permissive
type and perform writes on it.
If you want to use a `Read
string and assume it will not get
written to, you should either properly "adopt" it by ensuring
unique ownership (this cannot be guaranteed by the type system),
or make a copy of it at adoption time: Cap.of_bytes
.
(Bytes.copy buf)
val to_string : [ `Read | `Write ] t -> Stdlib.Bytes.t
Return a capability string as a regular byte sequence.
We cannot return a string
here, and it would be incorrect to
do so even if we required [< `Read] t
as input. Indeed, one
can start from a writeable byte sequence, and then use the
read_only
function below to cast it into a [`Read]
. Capabilities are used to enforce local protocol (only reads,
only writes, both reads and writes...), they don't guarantee
that other users of the same (shared) value all follow the same
protocol. To safely reason about mutability one needs stronger
ownership guarantees.
t
If you want to obtain an immutable string
out of a capability
string, you should first convert it to a mutable byte sequence
and then copy it into an immutable string. If you have extra
knowledge about the ownership of the value, you may use unsafe
conversion functions to avoid the copy, see the documentation of
unsafe conversion functions.
val to_bytes : [ `Read | `Write ] t -> Stdlib.Bytes.t
Return a capability string as a regular byte sequence.
val read_only : [> `Read ] t -> [ `Read ] t
Drop capabilities to read only.
val write_only : [> `Write ] t -> [ `Write ] t
Drop capabilities to write only.
val make : int -> char -> 'a t
val init : int -> (int -> char) -> 'a t
val enum : [> `Read ] t -> char BatEnum.t
val of_enum : char BatEnum.t -> 'a t
val backwards : [> `Read ] t -> char BatEnum.t
val of_backwards : char BatEnum.t -> 'a t
val of_list : char list -> 'a t
val to_list : [> `Read ] t -> char list
val of_int : int -> 'a t
val of_float : float -> 'a t
val of_char : char -> 'a t
val to_int : [> `Read ] t -> int
val to_float : [> `Read ] t -> float
val map : (char -> char) -> [> `Read ] t -> 'a t
val mapi : (int -> char -> char) -> [> `Read ] t -> 'a t
val fold_left : ('a -> char -> 'a) -> 'a -> [> `Read ] t -> 'a
val fold_lefti : ('a -> int -> char -> 'a) -> 'a -> [> `Read ] t -> 'a
val fold_right : (char -> 'a -> 'a) -> [> `Read ] t -> 'a -> 'a
val fold_righti : (int -> char -> 'a -> 'a) -> [> `Read ] t -> 'a -> 'a
val filter : (char -> bool) -> [> `Read ] t -> 'a t
val filter_map : (char -> char option) -> [> `Read ] t -> 'a t
val iter : (char -> unit) -> [> `Read ] t -> unit
val index : [> `Read ] t -> char -> int
val rindex : [> `Read ] t -> char -> int
val index_from : [> `Read ] t -> int -> char -> int
val rindex_from : [> `Read ] t -> int -> char -> int
val contains : [> `Read ] t -> char -> bool
val contains_from : [> `Read ] t -> int -> char -> bool
val rcontains_from : [> `Read ] t -> int -> char -> bool
val find : [> `Read ] t -> [> `Read ] t -> int
val find_from : [> `Read ] t -> int -> [> `Read ] t -> int
val rfind : [> `Read ] t -> [> `Read ] t -> int
val rfind_from : [> `Read ] t -> int -> [> `Read ] t -> int
val ends_with : [> `Read ] t -> [> `Read ] t -> bool
val starts_with : [> `Read ] t -> [> `Read ] t -> bool
val exists : [> `Read ] t -> [> `Read ] t -> bool
val count_char : [> `Read ] t -> char -> int
val lchop : ?n:int -> [> `Read ] t -> 'a t
val rchop : ?n:int -> [> `Read ] t -> 'a t
val chop : ?l:int -> ?r:int -> [> `Read ] t -> 'a t
val trim : [> `Read ] t -> 'a t
val quote : [> `Read ] t -> string
val left : [> `Read ] t -> int -> 'a t
val right : [> `Read ] t -> int -> 'a t
val head : [> `Read ] t -> int -> 'a t
val tail : [> `Read ] t -> int -> 'a t
val strip : ?chars:[> `Read ] t ->
[> `Read ] t -> 'a t
val uppercase : [> `Read ] t -> 'a t
val lowercase : [> `Read ] t -> 'a t
val capitalize : [> `Read ] t -> 'a t
val uncapitalize : [> `Read ] t -> 'a t
val copy : [> `Read ] t -> 'a t
val sub : [> `Read ] t -> int -> int -> 'a t
val fill : [> `Write ] t -> int -> int -> char -> unit
val blit : [> `Read ] t ->
int -> [> `Write ] t -> int -> int -> unit
val concat : [> `Read ] t ->
[> `Read ] t list -> 'a t
val escaped : [> `Read ] t -> 'a t
val replace_chars : (char -> [> `Read ] t) ->
[> `Read ] t -> 'a t
val replace : str:[> `Read ] t ->
sub:[> `Read ] t ->
by:[> `Read ] t -> bool * 'a t
val nreplace : str:[> `Read ] t ->
sub:[> `Read ] t ->
by:[> `Read ] t -> 'a t
val repeat : [> `Read ] t -> int -> 'a t
val split : [> `Read ] t ->
by:[> `Read ] t -> 'a t * 'b t
val rsplit : [> `Read ] t ->
by:[> `Read ] t -> 'a t * 'b t
val nsplit : [> `Read ] t ->
by:[> `Read ] t -> 'a t list
val splice : [ `Read | `Write ] t ->
int -> int -> [> `Read ] t -> 'a t
val join : [> `Read ] t ->
[> `Read ] t list -> 'a t
val slice : ?first:int -> ?last:int -> [> `Read ] t -> 'a t
val explode : [> `Read ] t -> char list
val implode : char list -> 'a t
val compare : [> `Read ] t -> [> `Read ] t -> int
val icompare : [> `Read ] t -> [> `Read ] t -> int
val print : 'a BatInnerIO.output -> [> `Read ] t -> unit
val println : 'a BatInnerIO.output -> [> `Read ] t -> unit
val print_quoted : 'a BatInnerIO.output -> [> `Read ] t -> unit
module Exceptionless:sig
..end
Exceptionless counterparts for error-raising operations