Enable EntityRef::get_by_id and friends to take multiple ids and get multiple pointers back (#15593)

# Objective

- Closes #15577 

## Solution

The following functions can now also take multiple component IDs and
return multiple pointers back:
- `EntityRef::get_by_id`
- `EntityMut::get_by_id`
- `EntityMut::into_borrow_by_id`
- `EntityMut::get_mut_by_id`
- `EntityMut::into_mut_by_id`
- `EntityWorldMut::get_by_id`
- `EntityWorldMut::into_borrow_by_id`
- `EntityWorldMut::get_mut_by_id`
- `EntityWorldMut::into_mut_by_id`

If you pass in X, you receive Y:
- give a single `ComponentId`, receive a single `Ptr`/`MutUntyped`
- give a `[ComponentId; N]` (array), receive a `[Ptr; N]`/`[MutUntyped;
N]`
- give a `&[ComponentId; N]` (array), receive a `[Ptr; N]`/`[MutUntyped;
N]`
- give a `&[ComponentId]` (slice), receive a
`Vec<Ptr>`/`Vec<MutUntyped>`
- give a `&HashSet<ComponentId>`, receive a `HashMap<ComponentId,
Ptr>`/`HashMap<ComponentId, MutUntyped>`

## Testing

- Added 4 new tests.

---

## Migration Guide

- The following functions now return an `Result<_,
EntityComponentError>` instead of a `Option<_>`: `EntityRef::get_by_id`,
`EntityMut::get_by_id`, `EntityMut::into_borrow_by_id`,
`EntityMut::get_mut_by_id`, `EntityMut::into_mut_by_id`,
`EntityWorldMut::get_by_id`, `EntityWorldMut::into_borrow_by_id`,
`EntityWorldMut::get_mut_by_id`, `EntityWorldMut::into_mut_by_id`
This commit is contained in:
Christian Hughes 2024-10-02 12:02:20 -07:00 committed by GitHub
parent ca709ffb5a
commit 7c6057bc69
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 914 additions and 87 deletions

File diff suppressed because it is too large Load Diff

View File

@ -2,7 +2,7 @@
use thiserror::Error;
use crate::schedule::InternedScheduleLabel;
use crate::{component::ComponentId, schedule::InternedScheduleLabel};
/// The error type returned by [`World::try_run_schedule`] if the provided schedule does not exist.
///
@ -10,3 +10,14 @@ use crate::schedule::InternedScheduleLabel;
#[derive(Error, Debug)]
#[error("The schedule with the label {0:?} was not found.")]
pub struct TryRunScheduleError(pub InternedScheduleLabel);
/// An error that occurs when dynamically retrieving components from an entity.
#[derive(Error, Debug, Clone, Copy, PartialEq, Eq)]
pub enum EntityComponentError {
/// The component with the given [`ComponentId`] does not exist on the entity.
#[error("The component with ID {0:?} does not exist on the entity.")]
MissingComponent(ComponentId),
/// The component with the given [`ComponentId`] was requested mutably more than once.
#[error("The component with ID {0:?} was requested mutably more than once.")]
AliasedMutability(ComponentId),
}