#string #sso #cow

no-std ecow

Compact, clone-on-write vector and string

6 releases

0.2.2 Mar 23, 2024
0.2.1 Mar 6, 2024
0.2.0 Oct 9, 2023
0.1.2 Aug 19, 2023
0.1.0 Mar 1, 2023

#70 in Data structures

Download history 2273/week @ 2024-06-08 2294/week @ 2024-06-15 2096/week @ 2024-06-22 2305/week @ 2024-06-29 2387/week @ 2024-07-06 2457/week @ 2024-07-13 2568/week @ 2024-07-20 2432/week @ 2024-07-27 2434/week @ 2024-08-03 2598/week @ 2024-08-10 2686/week @ 2024-08-17 2804/week @ 2024-08-24 2889/week @ 2024-08-31 3235/week @ 2024-09-07 2971/week @ 2024-09-14 3147/week @ 2024-09-21

12,560 downloads per month
Used in 62 crates (21 directly)

MIT/Apache

73KB
1.5K SLoC

ecow

Crates.io Documentation

Compact, clone-on-write vector and string.

Types

  • An EcoVec is a reference-counted clone-on-write vector. It takes up two words of space (= 2 usize) and has the same memory layout as a &[T] slice. Within its allocation, it stores a reference count, its capacity and its elements.

  • An EcoString is a reference-counted clone-on-write string with inline storage. It takes up 16 bytes of space. It has 15 bytes of inline storage and starting from 16 bytes it becomes an EcoVec<u8>.

Example

// This is stored inline.
let small = ecow::EcoString::from("Welcome");

// This spills to the heap, but only once: `big` and `third` share the
// same underlying allocation. Vectors and spilled strings are only
// really cloned upon mutation.
let big = small + " to earth! 🌱";
let mut third = big.clone();

// This allocates again to mutate `third` without affecting `big`.
assert_eq!(third.pop(), Some('🌱'));
assert_eq!(third, "Welcome to earth! ");

Why should I use this instead of ...

Type Details
Vec<T> / String Normal vectors are a great general purpose data structure. But they have a quite big footprint (3 machine words) and are expensive to clone. The EcoVec has a bit of overhead for mutation, but is cheap to clone and only takes two words.
Arc<Vec<T>> / Arc<String> These require two allocations instead of one and are less convenient to mutate.
Arc<[T]> / Arc<str> While these require only one allocation, they aren't mutable.
Small vector Different trade-off. Great when there are few, small Ts, but expensive to clone when spilled to the heap.
Small string The EcoString combines different small string qualities into a very practical package: It has inline storage, a smaller footprint than a normal String, is efficient to clone even when spilled, and at the same time mutable.

License

This crate is dual-licensed under the MIT and Apache 2.0 licenses.

Dependencies

~0–24MB
~333K SLoC