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.