Module xecs::query

Expand description

The query functions

Queryable

Queryable is trait that somethings can be queried in world. &T or &mut T where T : Component and T is registered in world can simply be Queryable. The tuple of combination of them like (&A,&mut B) is also Queryable.

QueryIterator

The result of query is a boxed QueryIterator. This trait is an extension of Iterator. So it can be treat as an Iterator.

With Id

Sometime we don’t only need the borrow of components data, but we also interest in the ID of entity. The with_id method from WithId will be helpful.

// query with id
use xecs::query::WithId; // we need use this trait before using with_id
for (id,data) in world.query::<&A>().with_id() {
    // do sth with id and data
}

Without

Sometime we want to query all entities with component A but B.The Without can be useful in this situation.

for data in world.query::<(&A,Without<&B>)>() {
   // do sth with data
}

Safety

Query Iterator internal has a lot of *const _or*mut _ to avoid borrow-checker warnings like this

pub struct IterRef<'a,T> {
    index : usize,
    sparse_set : *const SparseSet<EntityId,T>,
    borrow : RwLockReadGuard<'a,Box<dyn ComponentStorage>>
}

This struct is NOT a Self-Reference struct! Moving this struct is safe.
sparse_set is a pointer of dyn ComponentStorage, which means moving this struct will NOT change the address of dyn ComponentStorage. Because dyn ComponentStorage is boxed by Box<dyn ComponentStorage>. And the sparse_set field’s lifetime equals to borrow’s 'a. So the pointer is valid when this struct is alive.

Structs

Traits

QueryIterator

The result of query

Queryable

Some thing can be queried

WithId

A trait for with_id method