Module String.Cap

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.

module changed to accommodate the -safe-string transition. OCaml now uses two distinct types for mutable and immutable string, which is a good design but is not as expressive as the present Cap interface, and actually makes implementing Cap harder than it previously was. We are aware that current state is not optimal for heavy Cap users; if you are one of them, please get in touch (on the Batteries issue tracker for example) so that we can discuss code refactoring and improvements for this sub-module.

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 : _ t -> int
val is_empty : _ t -> bool
val get : [> `Read ] t -> int -> char
val set : [> `Write ] t -> int -> char -> unit
val create : int -> _ t
Constructors
val of_string : Bytes.t -> _ 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 : Bytes.t -> _ 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).

  • since 2.8.0
val to_string : [ `Read | `Write ] t -> 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] t. 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.

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 -> Bytes.t

Return a capability string as a regular byte sequence.

  • since 2.8.0
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 -> _ t
val init : int -> (int -> char) -> _ t
val enum : [> `Read ] t -> char BatEnum.t

Conversions

val of_enum : char BatEnum.t -> _ t
val backwards : [> `Read ] t -> char BatEnum.t
val of_backwards : char BatEnum.t -> _ t
val of_list : char list -> _ t
val to_list : [> `Read ] t -> char list
val of_int : int -> _ t
val of_float : float -> _ t
val of_char : char -> _ t
val to_int : [> `Read ] t -> int
val to_float : [> `Read ] t -> float
String traversals
val map : (char -> char) -> [> `Read ] t -> _ t
val mapi : (int -> char -> char) -> [> `Read ] t -> _ 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 -> _ t
val filter_map : (char -> char option) -> [> `Read ] t -> _ t
val iter : (char -> unit) -> [> `Read ] t -> unit
Finding
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
Transformations
val lchop : ?n:int -> [> `Read ] t -> _ t
val rchop : ?n:int -> [> `Read ] t -> _ t
val chop : ?l:int -> ?r:int -> [> `Read ] t -> _ t
val trim : [> `Read ] t -> _ t
val quote : [> `Read ] t -> string
val left : [> `Read ] t -> int -> _ t
val right : [> `Read ] t -> int -> _ t
val head : [> `Read ] t -> int -> _ t
val tail : [> `Read ] t -> int -> _ t
val strip : ?chars:[> `Read ] t -> [> `Read ] t -> _ t
val uppercase : [> `Read ] t -> _ t
val lowercase : [> `Read ] t -> _ t
val capitalize : [> `Read ] t -> _ t
val uncapitalize : [> `Read ] t -> _ t
val copy : [> `Read ] t -> _ t
val sub : [> `Read ] t -> int -> int -> _ 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 -> _ t
val escaped : [> `Read ] t -> _ t
val replace_chars : (char -> [> `Read ] t) -> [> `Read ] t -> _ t
val replace : str:[> `Read ] t -> sub:[> `Read ] t -> by:[> `Read ] t -> bool * _ t
val nreplace : str:[> `Read ] t -> sub:[> `Read ] t -> by:[> `Read ] t -> _ t
val repeat : [> `Read ] t -> int -> _ t
val split : [> `Read ] t -> by:[> `Read ] t -> _ t * _ t

Splitting around

val rsplit : [> `Read ] t -> by:[> `Read ] t -> _ t * _ t
val nsplit : [> `Read ] t -> by:[> `Read ] t -> _ t list
val splice : [ `Read | `Write ] t -> int -> int -> [> `Read ] t -> _ t
val join : [> `Read ] t -> [> `Read ] t list -> _ t
val slice : ?first:int -> ?last:int -> [> `Read ] t -> _ t
val explode : [> `Read ] t -> char list
val implode : char list -> _ t
Comparisons
val compare : [> `Read ] t -> [> `Read ] t -> int
val icompare : [> `Read ] t -> [> `Read ] t -> int
Printing
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