pub unsafe trait Join {
type Type;
type Value;
type Mask: BitSetLike;
// Required methods
unsafe fn open(self) -> (Self::Mask, Self::Value);
unsafe fn get(value: &mut Self::Value, id: Index) -> Self::Type;
// Provided methods
fn join(self) -> JoinIter<Self> ⓘ
where Self: Sized { ... }
fn is_unconstrained() -> bool { ... }
}Expand description
The purpose of the Join trait is to provide a way
to access multiple storages at the same time with
the merged bit set.
Joining component storages means that you’ll only get values where for a given entity every storage has an associated component.
Example
let mut world = World::new();
world.register::<Pos>();
world.register::<Vel>();
{
let pos = world.read_storage::<Pos>();
let vel = world.read_storage::<Vel>();
// There are no entities yet, so no pair will be returned.
let joined: Vec<_> = (&pos, &vel).join().collect();
assert_eq!(joined, vec![]);
}
world.create_entity().with(Pos).build();
{
let pos = world.read_storage::<Pos>();
let vel = world.read_storage::<Vel>();
// Although there is an entity, it only has `Pos`.
let joined: Vec<_> = (&pos, &vel).join().collect();
assert_eq!(joined, vec![]);
}
let ent = world.create_entity().with(Pos).with(Vel).build();
{
let pos = world.read_storage::<Pos>();
let vel = world.read_storage::<Vel>();
// Now there is one entity that has both a `Vel` and a `Pos`.
let joined: Vec<_> = (&pos, &vel).join().collect();
assert_eq!(joined, vec![(&Pos, &Vel)]);
// If we want to get the entity the components are associated to,
// we need to join over `Entities`:
let entities = world.read_resource::<EntitiesRes>();
// note: `EntitiesRes` is the fetched resource; we get back
// `Read<EntitiesRes>`.
// `Read<EntitiesRes>` can also be referred to by `Entities` which
// is a shorthand type definition to the former type.
let joined: Vec<_> = (&entities, &pos, &vel).join().collect();
assert_eq!(joined, vec![(ent, &Pos, &Vel)]);
}Iterating over a single storage
Join can also be used to iterate over a single
storage, just by writing (&storage).join().
Safety
The Self::Mask value returned with the Self::Value must correspond such
that it is safe to retrieve items from Self::Value whose presence is
indicated in the mask. As part of this, BitSetLike::iter must not produce
an iterator that repeats an Index value.
Required Associated Types§
sourcetype Mask: BitSetLike
type Mask: BitSetLike
Type of joined bit mask.
Required Methods§
sourceunsafe fn open(self) -> (Self::Mask, Self::Value)
unsafe fn open(self) -> (Self::Mask, Self::Value)
Open this join by returning the mask and the storages.
Safety
This is unsafe because implementations of this trait can permit the
Value to be mutated independently of the Mask. If the Mask does
not correctly report the status of the Value then illegal memory
access can occur.
Provided Methods§
sourcefn join(self) -> JoinIter<Self> ⓘwhere
Self: Sized,
fn join(self) -> JoinIter<Self> ⓘwhere Self: Sized,
Create a joined iterator over the contents.
sourcefn is_unconstrained() -> bool
fn is_unconstrained() -> bool
If this Join typically returns all indices in the mask, then iterating
over only it or combined with other joins that are also dangerous will
cause the JoinIter to go through all indices which is usually not what
is wanted and will kill performance.