This library defines strings with copy-on-write semantics.
# CowStr
Is a String that can be initialized to a static string or be build dynamically. Its contents
can then be immutably shared and reference counted. When mutation is required the string will
be copied first.
This resembles a improved `Arc<Cow<'static, str>>` with some differences:
- No double dereference going from `Arc` to `String` to the actual data.
- There are no `Weak` references.
- `CowStr` can be interior-mutable extended (append at the end).
- Improved `AllocationStrategy`
`CowStr` implements many of the `std::String` methods. Missing methods will be added as required,
PR's are welcome.
# SubStr
Refers to an immutable slice inside of a `CowStr`. This somewhat resembles the `String`/`&str`
relationship while `SubStr` keeping a strong reference to its orgin `CowStr` and thus don't
need lifetimes.
# Features
* **multithreaded** using 'threadcell' and atomics for synchronization. This is the default.
* **serde** wrapping the default string (de)serialization.
When multithreaded is explicitly disabled a ligher Cell based reference counting is used. This
singlethreaded variant should only be used for applications that are designed to be single
threaded on architectures where atomics are expensive.
# Implementation Notes
`CowStr` is made for sharing immutable strings, a short single `CowStr` will occupy slightly
more memory than a std `String`. But as soon a `CowStr` is cloned or `SubStr`'s are used
it pays back. Especially since `SubStr` don't need lifetimes as they use reference counting
memory management becomes significantly easier.
Because rust has yet incomplete support for DST's `CowStr` needs some unsafe code. This is
liberally chosen, when possible contracts are enforced by `debug_assert`'s.
# Testing
`CowStr` commes with an extensive test suite. 'cargo-mutants' is used to detect missing
tests. Releases must pass testing under 'miri'.