bevy_ecs/query/
error.rs

1use bevy_utils::prelude::DebugName;
2
3use crate::{
4    archetype::ArchetypeId,
5    entity::{Entity, EntityNotSpawnedError},
6};
7
8/// An error that occurs when retrieving a specific [`Entity`]'s query result from [`Query`](crate::system::Query) or [`QueryState`](crate::query::QueryState).
9// TODO: return the type_name as part of this error
10#[derive(thiserror::Error, Clone, Copy, Debug, PartialEq, Eq)]
11pub enum QueryEntityError {
12    /// The given [`Entity`]'s components do not match the query.
13    ///
14    /// Either it does not have a requested component, or it has a component which the query filters out.
15    #[error("The query does not match entity {0}")]
16    QueryDoesNotMatch(Entity, ArchetypeId),
17    /// The given [`Entity`] is not spawned.
18    #[error("{0}")]
19    NotSpawned(#[from] EntityNotSpawnedError),
20    /// The [`Entity`] was requested mutably more than once.
21    ///
22    /// See [`Query::get_many_mut`](crate::system::Query::get_many_mut) for an example.
23    #[error("The entity with ID {0} was requested mutably more than once")]
24    AliasedMutability(Entity),
25}
26
27/// An error that occurs when evaluating a [`Query`](crate::system::Query) or [`QueryState`](crate::query::QueryState) as a single expected result via
28/// [`single`](crate::system::Query::single) or [`single_mut`](crate::system::Query::single_mut).
29#[derive(Debug, thiserror::Error)]
30pub enum QuerySingleError {
31    /// No entity fits the query.
32    #[error("No entities fit the query {0}")]
33    NoEntities(DebugName),
34    /// Multiple entities fit the query.
35    #[error("Multiple entities fit the query {0}")]
36    MultipleEntities(DebugName),
37}
38
39/// An error that occurs when creating a contiguous iterator from a non-dense [`Query`](crate::system::Query) or [`QueryState`](crate::query::QueryState) via
40/// [`contiguous_iter`](crate::system::Query::contiguous_iter) or [`contiguous_iter_mut`](crate::system::Query::contiguous_iter_mut).
41#[derive(Debug, thiserror::Error)]
42#[error("Cannot contiguously iterate non-dense query {0}")]
43pub struct QueryNotDenseError(pub DebugName);
44
45#[cfg(test)]
46mod test {
47    use crate::{prelude::World, query::QueryEntityError};
48    use bevy_ecs_macros::Component;
49
50    #[test]
51    fn query_does_not_match() {
52        let mut world = World::new();
53
54        #[derive(Component)]
55        struct Present1;
56        #[derive(Component)]
57        struct Present2;
58        #[derive(Component, Debug, PartialEq)]
59        struct NotPresent;
60
61        let entity = world.spawn((Present1, Present2));
62
63        let (entity, archetype_id) = (entity.id(), entity.archetype().id());
64
65        let result = world.query::<&NotPresent>().get(&world, entity);
66
67        assert_eq!(
68            result,
69            Err(QueryEntityError::QueryDoesNotMatch(entity, archetype_id))
70        );
71    }
72}
bevy_ecs/query/error.rs

bevy_ecs/query/
error.rs
