orx-split-vec

A split vector, SplitVec, is a vector represented as a sequence of multiple contagious data fragments.

It provides the following features:

• Flexible in growth strategies; custom strategies can be defined.
• Growth does not cause any memory copies.
• Capacity of an already created fragment is never changed.
• The above feature allows the data to stay pinned in place. Memory location of an item added to the split vector will never change unless it is removed from the vector or the vector is dropped.

Why - Actually

The main feature of SplitVec is that it guarantees that the memory locations of its elements will never change.

Together with rust's ownership model, this turns out to be a useful property and makes SplitVec the underlying model of other useful data structures.

See orx-imp-vec for an example.

Why - Also

SplitVec is certainly not a replacement for std::vec::Vec, and not preferable over it in most of the cases since it adds one level of abstraction.

It is useful, however, for building a collection where:

• there is a large uncertainty in the expected ultimate length, and
• copies are expensive.

In this case, SplitVec provides a detailed control on how the memory should grow. Further, it avoids copies while growing. Instead, every time the vector needs to grow, it allocates a new chunk of memory as a separate fragment.

Finally, it provides an api similar to standard vec for convenience and makes it easy to convert between these types.

```rust use orxsplitvec::{FragmentGrowth, SplitVec};

fn main() { // the capacity will be expanded in chunks of 10 items // see 'FragmentGrowth::exponential' and 'FragmentGrowth::byfunction' // for alternative flexible growth strategies. let growth = FragmentGrowth::constant(10); let mut splitvec = SplitVec::with_growth(growth);

// below insertions will lead to 7 expansions,
// creating 7 contagious fragments with capacity of 10.
// no memory copies will happen during the building.
for i in 0..70 {
    split_vec.push(i);
}

// this vector can be used as a split vector due to
// its standard vector like api.
// alternatively, it can be collected into a vec with
// a contagious layout once build-up is complete.
let vec: Vec<_> = split_vec.to_vec();
assert_eq!(70, vec.len());

} ```