Trait WorldEntityFetch

pub unsafe trait WorldEntityFetch {
    type Ref<'w>;
    type Mut<'w>;
    type DeferredMut<'w>;

    // Required methods
    unsafe fn fetch_ref(
        self,
        cell: UnsafeWorldCell<'_>,
    ) -> Result<Self::Ref<'_>, Entity>;
    unsafe fn fetch_mut(
        self,
        cell: UnsafeWorldCell<'_>,
    ) -> Result<Self::Mut<'_>, EntityFetchError>;
    unsafe fn fetch_deferred_mut(
        self,
        cell: UnsafeWorldCell<'_>,
    ) -> Result<Self::DeferredMut<'_>, EntityFetchError>;
}

Types that can be used to fetch Entity references from a World.

Provided implementations are:

• Entity: Fetch a single entity.
• [Entity; N]/&[Entity; N]: Fetch multiple entities, receiving a same-sized array of references.
• &[Entity]: Fetch multiple entities, receiving a vector of references.
• &EntityHashSet: Fetch multiple entities, receiving a hash map of Entity IDs to references.

Performance

• The slice and array implementations perform an aliased mutabiltiy check in WorldEntityFetch::fetch_mut that is O(N^2).
• The EntityHashSet implementation performs no such check as the type itself guarantees no duplicates.
• The single Entity implementation performs no such check as only one reference is returned.

Safety

Implementor must ensure that:

• No aliased mutability is caused by the returned references.
• WorldEntityFetch::fetch_ref returns only read-only references.
• WorldEntityFetch::fetch_deferred_mut returns only non-structurally-mutable references.

Required Associated Types

type Ref<'w>

The read-only reference type returned by WorldEntityFetch::fetch_ref.

type Mut<'w>

The mutable reference type returned by WorldEntityFetch::fetch_mut.

type DeferredMut<'w>

The mutable reference type returned by WorldEntityFetch::fetch_deferred_mut, but without structural mutability.

Required Methods

unsafe fn fetch_ref( self, cell: UnsafeWorldCell<'_>, ) -> Result<Self::Ref<'_>, Entity>

Returns read-only reference(s) to the entities with the given Entity IDs, as determined by self.

Safety

It is the caller’s responsibility to ensure that:

• The given UnsafeWorldCell has read-only access to the fetched entities.
• No other mutable references to the fetched entities exist at the same time.

Errors

• Returns Entity if the entity does not exist.

unsafe fn fetch_mut( self, cell: UnsafeWorldCell<'_>, ) -> Result<Self::Mut<'_>, EntityFetchError>

Returns mutable reference(s) to the entities with the given Entity IDs, as determined by self.

Safety

It is the caller’s responsibility to ensure that:

• The given UnsafeWorldCell has mutable access to the fetched entities.
• No other references to the fetched entities exist at the same time.

Errors

• Returns EntityFetchError::NoSuchEntity if the entity does not exist.
• Returns EntityFetchError::AliasedMutability if the entity was requested mutably more than once.

unsafe fn fetch_deferred_mut( self, cell: UnsafeWorldCell<'_>, ) -> Result<Self::DeferredMut<'_>, EntityFetchError>

Returns mutable reference(s) to the entities with the given Entity IDs, as determined by self, but without structural mutability.

No structural mutability means components cannot be removed from the entity, new components cannot be added to the entity, and the entity cannot be despawned.

Safety

It is the caller’s responsibility to ensure that:

• The given UnsafeWorldCell has mutable access to the fetched entities.
• No other references to the fetched entities exist at the same time.

Errors

• Returns EntityFetchError::NoSuchEntity if the entity does not exist.
• Returns EntityFetchError::AliasedMutability if the entity was requested mutably more than once.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl WorldEntityFetch for &[Entity]

type Ref<'w> = Vec<EntityRef<'w>>

type Mut<'w> = Vec<EntityMut<'w>>

type DeferredMut<'w> = Vec<EntityMut<'w>>

unsafe fn fetch_ref( self, cell: UnsafeWorldCell<'_>, ) -> Result<Self::Ref<'_>, Entity>

unsafe fn fetch_mut( self, cell: UnsafeWorldCell<'_>, ) -> Result<Self::Mut<'_>, EntityFetchError>

unsafe fn fetch_deferred_mut( self, cell: UnsafeWorldCell<'_>, ) -> Result<Self::DeferredMut<'_>, EntityFetchError>

impl<const N: usize> WorldEntityFetch for &[Entity; N]

type Ref<'w> = [EntityRef<'w>; N]

type Mut<'w> = [EntityMut<'w>; N]

type DeferredMut<'w> = [EntityMut<'w>; N]

unsafe fn fetch_ref( self, cell: UnsafeWorldCell<'_>, ) -> Result<Self::Ref<'_>, Entity>

unsafe fn fetch_mut( self, cell: UnsafeWorldCell<'_>, ) -> Result<Self::Mut<'_>, EntityFetchError>

unsafe fn fetch_deferred_mut( self, cell: UnsafeWorldCell<'_>, ) -> Result<Self::DeferredMut<'_>, EntityFetchError>

impl<const N: usize> WorldEntityFetch for [Entity; N]

type Ref<'w> = [EntityRef<'w>; N]

type Mut<'w> = [EntityMut<'w>; N]

type DeferredMut<'w> = [EntityMut<'w>; N]

unsafe fn fetch_ref( self, cell: UnsafeWorldCell<'_>, ) -> Result<Self::Ref<'_>, Entity>

unsafe fn fetch_mut( self, cell: UnsafeWorldCell<'_>, ) -> Result<Self::Mut<'_>, EntityFetchError>

unsafe fn fetch_deferred_mut( self, cell: UnsafeWorldCell<'_>, ) -> Result<Self::DeferredMut<'_>, EntityFetchError>

Implementors

impl WorldEntityFetch for &EntityHashSet

type Ref<'w> = HashMap<Entity, EntityRef<'w>, EntityHash>

type Mut<'w> = HashMap<Entity, EntityMut<'w>, EntityHash>

type DeferredMut<'w> = HashMap<Entity, EntityMut<'w>, EntityHash>

impl WorldEntityFetch for Entity

type Ref<'w> = EntityRef<'w>

type Mut<'w> = EntityWorldMut<'w>

type DeferredMut<'w> = EntityMut<'w>