Crate soa_rs

Soars

Soars 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 Soars for your type:

#[derive(Soars, 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), ExampleRef { foo: &7, bar: &8 });
assert_eq!(
    soa.idx(1..3),
    soa![
        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(Soars)]
struct Example(u8);
let soa = soa![Example(5), Example(10)];
assert_eq!(soa.f0(), [5, 10]);

Serde

serde support is enabled by the serde feature flag.

#[derive(Soars, serde::Deserialize)]
#[soa_derive(include(Ref), serde::Serialize)]
struct Test(u32);

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

AsMutSlice

Similar to AsMut<Slice>, but returns a value type rather than a mutable reference.

AsSlice

Similar to AsRef<Slice>, but returns a value type rather than an reference.

AsSoaRef

Similar to AsRef, but for Soars::Ref.

SoaDeref

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

SoaIndex

A helper trait for indexing operations.

Soars

Provides Soa compatibility.

Derive Macros

Soars

Derive macro for the Soars trait.