Crate cowstr

source ·
Expand description

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

  • serde wrapping the default string (de)serialization.
  • nightly enable some nightly optimizations and extensions

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’.

Macros

  • format
    Creates a CowStr using interpolation of runtime expressions.

Structs

  • CowStr
    A shared string that is copy-on-write and can be either static or dynamic shared with a reference counter. When a CowStr is dynamically created it can be mutated until it becomes cloned, then mutation becomes copy-on-write as marked with copy-on-write below.
  • CowStrPushGuard
    The CowStrPushGuard implements the try_push* methods which allow to extend a CowStr in place.
  • SubStr
    Arbitrary immutable text as span from some shared string. SubStr holding a reference to the CowStr they lie within. This removes the need to pass lifetimes around as memory become reference counted.

Enums

  • Error
    The errors that the CowStr API may return.

Constants

  • EMPTY_SUBSTR
    A constant for an always empty SubStr.
  • RCSTRING_ALIGN
    The alignment/size granularity a CowStr allocated memory block. This is mostly a implementation detail. To avoid tiny allocations and memory fragmentation allocated lengths are a multiple of this alignment. Note that an allocation includes a header.
  • RCSTRING_HEADER_SIZE
    The size of the header of a CowStr allocated memory block. This is mostly a implementation detail but it is exported to give the user more control about memory allocations. CowStr::with_capacity(65536 - cowstr::RCSTRING_HEADER_SIZE) will allocate a CowStr that uses exactly 64kb memory.

Traits

  • ToCowStr
    A trait for converting a value to a CowStr.
  • ToSubStr
    A trait for converting a value to a SubStr.