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.
since 2.8.0 the interface and implementation of the Cap
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.
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 ==.
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.
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).
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.