Crate soapy

Soapy

Soapy makes it simple to work with the structure-of-arrays memory layout. What Vec is to array-of-structures, Soa is to structure-of-arrays.

Examples

First, derive Soapy for your type:

#[derive(Soapy, Debug, Clone, Copy, PartialEq)]
#[soa_derive(Debug, PartialEq)]
struct Example {
    foo: u8,
    bar: u16,
}

You can create an Soa explicitly:

let mut soa: Soa<Example> = Soa::new();
soa.push(Example { foo: 1, bar: 2 });

…or by using the soa! macro.

let mut soa = soa![Example { foo: 1, bar: 2 }, Example { foo: 3, bar: 4 }];

An SoA can be indexed and sliced just like a &[T]. Use idx in lieu of the index operator.

let mut soa = soa![
    Example { foo: 1, bar: 2 },
    Example { foo: 3, bar: 4 },
    Example { foo: 5, bar: 6 },
    Example { foo: 7, bar: 8 }
];
assert_eq!(soa.idx(3), Example { foo: 7, bar: 8 });
assert_eq!(soa.idx(1..3), [Example { foo: 3, bar: 4 }, Example { foo: 5, bar: 6 }]);

The usual Vec APIs work normally.

let mut soa = Soa::<Example>::new();
soa.push(Example { foo: 1, bar: 2 });
soa.push(Example { foo: 3, bar: 4 });
soa.insert(0, Example { foo: 5, bar: 6 });
assert_eq!(soa.pop(), Some(Example { foo: 3, bar: 4 }));
for mut el in &mut soa {
    *el.bar += 10;
}
assert_eq!(soa.bar(), [16, 12]);

Field getters

You can access the fields as slices.

let mut soa = soa![
    Example { foo: 1, bar: 2 },
    Example { foo: 3, bar: 4 },
];
assert_eq!(soa.foo(), [1, 3]);

Postpend _mut for mutable slices.

for foo in soa.foo_mut() {
    *foo += 10;
}
assert_eq!(soa.foo(), [11, 13]);

For tuple structs, prepend the field number with f:

#[derive(Soapy)]
struct Example(u8);
let soa = soa![Example(5), Example(10)];
assert_eq!(soa.f0(), [5, 10]);

Macros

soa

Creates a Soa containing the arguments.

Structs

ChunksExact

An iterator over a Slice in (non-overlapping) chunks of chunk_size elements.

IntoIter

An iterator that moves out of a Soa.

Iter

Immutable Slice iterator.

IterMut

Mutable Slice iterator.

Slice

A dynamically-sized view into the contents of a Soa.

SliceMut

An mutably borrowed Slice.

SliceRef

An immutably borrowed Slice.

Soa

A growable array type that stores the values for each field of T contiguously.

Traits

AsSoaRef

Similar to AsRef, but for Soapy::Ref.

SoaArray

A compile-time, fixed-size SoA array.

SoaDeref

Slice dereferences to this type to provide getters for the individual fields as slices.

SoaIndex

A helper trait for indexing operations.

Soapy

Provides Soa compatibility.

Derive Macros

Soapy

Derive macro for the Soapy trait.