Moved get_component(_unchecked_mut) from Query to QueryState

crates/bevy_ecs/src/query/error.rs

@@ -0,0 +1,151 @@
+use std::fmt;
+
+use crate::entity::Entity;
+
+/// An error that occurs when retrieving a specific [`Entity`]'s query result from [`Query`](crate::system::Query) or [`QueryState`](crate::query::QueryState).
+// TODO: return the type_name as part of this error
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+pub enum QueryEntityError {
+ /// The given [`Entity`]'s components do not match the query.
+ ///
+ /// Either it does not have a requested component, or it has a component which the query filters out.
+ QueryDoesNotMatch(Entity),
+ /// The given [`Entity`] does not exist.
+ NoSuchEntity(Entity),
+ /// The [`Entity`] was requested mutably more than once.
+ ///
+ /// See [`QueryState::get_many_mut`](crate::query::QueryState::get_many_mut) for an example.
+ AliasedMutability(Entity),
+}
+
+impl std::error::Error for QueryEntityError {}
+
+impl fmt::Display for QueryEntityError {
+ fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+ match self {
+ QueryEntityError::QueryDoesNotMatch(_) => {
+ write!(f, "The given entity's components do not match the query.")
+ }
+ QueryEntityError::NoSuchEntity(_) => write!(f, "The requested entity does not exist."),
+ QueryEntityError::AliasedMutability(_) => {
+ write!(f, "The entity was requested mutably more than once.")
+ }
+ }
+ }
+}
+
+/// An error that occurs when retrieving a specific [`Entity`]'s component from a [`Query`](crate::system::Query).
+#[derive(Debug, PartialEq, Eq)]
+pub enum QueryComponentError {
+ /// The [`Query`](crate::system::Query) does not have read access to the requested component.
+ ///
+ /// This error occurs when the requested component is not included in the original query.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// # use bevy_ecs::{prelude::*, query::QueryComponentError};
+ /// #
+ /// # #[derive(Component)]
+ /// # struct OtherComponent;
+ /// #
+ /// # #[derive(Component, PartialEq, Debug)]
+ /// # struct RequestedComponent;
+ /// #
+ /// # #[derive(Resource)]
+ /// # struct SpecificEntity {
+ /// # entity: Entity,
+ /// # }
+ /// #
+ /// fn get_missing_read_access_error(query: Query<&OtherComponent>, res: Res<SpecificEntity>) {
+ /// assert_eq!(
+ /// query.get_component::<RequestedComponent>(res.entity),
+ /// Err(QueryComponentError::MissingReadAccess),
+ /// );
+ /// println!("query doesn't have read access to RequestedComponent because it does not appear in Query<&OtherComponent>");
+ /// }
+ /// # bevy_ecs::system::assert_is_system(get_missing_read_access_error);
+ /// ```
+ MissingReadAccess,
+ /// The [`Query`](crate::system::Query) does not have write access to the requested component.
+ ///
+ /// This error occurs when the requested component is not included in the original query, or the mutability of the requested component is mismatched with the original query.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// # use bevy_ecs::{prelude::*, query::QueryComponentError};
+ /// #
+ /// # #[derive(Component, PartialEq, Debug)]
+ /// # struct RequestedComponent;
+ /// #
+ /// # #[derive(Resource)]
+ /// # struct SpecificEntity {
+ /// # entity: Entity,
+ /// # }
+ /// #
+ /// fn get_missing_write_access_error(mut query: Query<&RequestedComponent>, res: Res<SpecificEntity>) {
+ /// assert_eq!(
+ /// query.get_component::<RequestedComponent>(res.entity),
+ /// Err(QueryComponentError::MissingWriteAccess),
+ /// );
+ /// println!("query doesn't have write access to RequestedComponent because it doesn't have &mut in Query<&RequestedComponent>");
+ /// }
+ /// # bevy_ecs::system::assert_is_system(get_missing_write_access_error);
+ /// ```
+ MissingWriteAccess,
+ /// The given [`Entity`] does not have the requested component.
+ MissingComponent,
+ /// The requested [`Entity`] does not exist.
+ NoSuchEntity,
+}
+
+impl std::error::Error for QueryComponentError {}
+
+impl std::fmt::Display for QueryComponentError {
+ fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+ match self {
+ QueryComponentError::MissingReadAccess => {
+ write!(
+ f,
+ "This query does not have read access to the requested component."
+ )
+ }
+ QueryComponentError::MissingWriteAccess => {
+ write!(
+ f,
+ "This query does not have write access to the requested component."
+ )
+ }
+ QueryComponentError::MissingComponent => {
+ write!(f, "The given entity does not have the requested component.")
+ }
+ QueryComponentError::NoSuchEntity => {
+ write!(f, "The requested entity does not exist.")
+ }
+ }
+ }
+}
+
+/// An error that occurs when evaluating a [`Query`](crate::system::Query) or [`QueryState`](crate::query::QueryState) as a single expected result via
+/// [`get_single`](crate::system::Query::get_single) or [`get_single_mut`](crate::system::Query::get_single_mut).
+#[derive(Debug)]
+pub enum QuerySingleError {
+ /// No entity fits the query.
+ NoEntities(&'static str),
+ /// Multiple entities fit the query.
+ MultipleEntities(&'static str),
+}
+
+impl std::error::Error for QuerySingleError {}
+
+impl std::fmt::Display for QuerySingleError {
+ fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+ match self {
+ QuerySingleError::NoEntities(query) => write!(f, "No entities fit the query {query}"),
+ QuerySingleError::MultipleEntities(query) => {
+ write!(f, "Multiple entities fit the query {query}!")
+ }
+ }
+ }
+}

crates/bevy_ecs/src/query/mod.rs

@@ -1,13 +1,15 @@
 //! Contains APIs for retrieving component data from the world.
 
 mod access;
+mod error;
 mod fetch;
 mod filter;
 mod iter;
 mod par_iter;
 mod state;
 
 pub use access::*;
+pub use error::*;
 pub use fetch::*;
 pub use filter::*;
 pub use iter::*;