Struct rs_ecs::Query

pub struct Query<S> where
    S: QuerySpec,  { /* fields omitted */ }

Query to get an iterator over all entities with a certain combination of components.

Queries are specified through their type argument, by composing the type of their result. The following type specifications are possible:

• &C - shared, immutable reference to components of type C
• &mut C - exclusive, mutable reference
• (P, Q, R) - combine multiple queries
• Option<Q> - optional component(s)
• With<Q, C> to filter Q for presence of C
• Without<Q, C> to filter Q for absence of C

Note that Entities are components themselves, so they can be optionally obtained in a query, like Query<Entity, &C, &mut D>.

Queries are provided as stand-alone structs to allow for prepared queries that can be re-used, as an optimzation. Hence, queries need to borrow the World before their results can be iterated (see Query::borrow).

Examples

let mut world = World::new();

let entity1 = world.alloc();
world.insert(entity1, (42_i32, 23_u32, 1.0_f32));

let entity2 = world.alloc();
world.insert(entity2, (0_i32, true));

let mut query = Query::<(&mut i32, Option<(&u32, &mut f32)>)>::new();
for (i, opt) in query.borrow(&world).iter() {
    if let Some((u, f)) = opt {
        *i += *u as i32;
        *f += 1.0
    } else {
        *i -= 1;
    }
}

assert_eq!(*world.get::<i32>(entity1).unwrap(), 65);
assert_eq!(*world.get::<f32>(entity1).unwrap(), 2.0);
assert_eq!(*world.get::<i32>(entity2).unwrap(), -1);

Use of a prepared query that is stored and reused for optimization:

#[derive(Default)]
struct System {
    query: Query<(&'static i32, &'static mut bool)>
}

impl System {
    pub fn update(&mut self, world: &World) {
        for (i, b) in self.query.borrow(world).iter() {
            *b = *i >= 0;
        }
    }
}

fn main() {
    let mut world = World::new();

    let entity = world.alloc();
    world.insert(entity, (23_i32, false));

    let mut system = System::default();

    for _ in 0..42 {
        system.update(&world);
    }
}

Implementations

impl<S> Query<S> where
    S: QuerySpec, 

pub fn new() -> Self

Create a query.

Examples

let mut immutable_query = Query::<(&i32,)>::new();
let mut mutable_query = Query::<(&i32, &mut bool)>::new();
let mut query_with_entity = Query::<(&Entity, &i32, &mut bool)>::new();

pub fn borrow<'w>(&'w mut self, world: &'w World) -> QueryRef<'w, S>

Borrow the World to allow for iterating the query.

Examples

let mut world = World::new();
let mut query = Query::<(&i32, &bool)>::new();
let mut borrow = query.borrow(&world);

for (i, b) in borrow.iter() {
    println!("{}, {}", i, b);
}

pub fn with<C>(self) -> Query<With<S, C>> where
    C: 'static, 

Narrow down a query to entities that have a certain component, without borrowing that component.

For use with prepared queries, see With.

Examples

let query = Query::<(&i32,)>::new().with::<bool>();

pub fn without<C>(self) -> Query<Without<S, C>> where
    C: 'static, 

Narrow down a query to entities that do not have a certain component.

For use with prepared queries, see Without.

Examples

let query = Query::<(&i32,)>::new().without::<bool>();

Trait Implementations

impl<S> Default for Query<S> where
    S: QuerySpec, 

fn default() -> Self

Create a query.