Crate soapy

source ·
Expand description

§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§

Traits§

Derive Macros§