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#[cfg(test)]
40mod test {
41    use crate::{prelude::World, query::QueryEntityError};
42    use bevy_ecs_macros::Component;
43
44    #[test]
45    fn query_does_not_match() {
46        let mut world = World::new();
47
48        #[derive(Component)]
49        struct Present1;
50        #[derive(Component)]
51        struct Present2;
52        #[derive(Component, Debug, PartialEq)]
53        struct NotPresent;
54
55        let entity = world.spawn((Present1, Present2));
56
57        let (entity, archetype_id) = (entity.id(), entity.archetype().id());
58
59        let result = world.query::<&NotPresent>().get(&world, entity);
60
61        assert_eq!(
62            result,
63            Err(QueryEntityError::QueryDoesNotMatch(entity, archetype_id))
64        );
65    }
66}
bevy_ecs/query/error.rs

bevy_ecs/query/
error.rs
