ecow
| Crates.io | ecow |
| lib.rs | ecow |
| version | 0.2.3 |
| source | src |
| created_at | 2023-03-01 10:24:13.851101 |
| updated_at | 2024-10-30 14:33:08.479567 |
| description | Compact, clone-on-write vector and string. |
| homepage | |
| repository | https://github.com/typst/ecow |
| max_upload_size | |
| id | 797921 |
| size | 103,398 |
Laurenz (laurmaedje)
documentation
README
ecow
Compact, clone-on-write vector and string.
Types
-
An
EcoVecis 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
EcoStringis 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 anEcoVec<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.