`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 : Stdlib.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.

- deprecated Use Cap.of_bytes instead

`val of_bytes : Stdlib.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 -> 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] 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.

- deprecated Use Cap.to_bytes instead

`val to_bytes : [ `Read | `Write ] t -> Stdlib.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 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