Trait DynamicComponentFetch

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

    // Required methods
    unsafe fn fetch_ref(
        self,
        cell: UnsafeEntityCell<'_>,
    ) -> Result<Self::Ref<'_>, EntityComponentError>;
    unsafe fn fetch_mut(
        self,
        cell: UnsafeEntityCell<'_>,
    ) -> Result<Self::Mut<'_>, EntityComponentError>;
}

Types that can be used to fetch components from an entity dynamically by ComponentIds.

Provided implementations are:

• ComponentId: Returns a single untyped reference.
• [ComponentId; N] and &[ComponentId; N]: Returns a same-sized array of untyped references.
• &[ComponentId]: Returns a Vec of untyped references.
• &HashSet<ComponentId>: Returns a HashMap of IDs to untyped references.

Performance

• The slice and array implementations perform an aliased mutability check in DynamicComponentFetch::fetch_mut that is O(N^2).
• The HashSet implementation performs no such check as the type itself guarantees unique IDs.
• The single ComponentId 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.
• DynamicComponentFetch::fetch_ref returns only read-only references.

Required Associated Types

type Ref<'w>

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

type Mut<'w>

The mutable reference type returned by DynamicComponentFetch::fetch_mut.

Required Methods

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

Returns untyped read-only reference(s) to the component(s) with the given ComponentIds, as determined by self.

Safety

It is the caller’s responsibility to ensure that:

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

Errors

• Returns EntityComponentError::MissingComponent if a component is missing from the entity.

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

Returns untyped mutable reference(s) to the component(s) with the given ComponentIds, as determined by self.

Safety

It is the caller’s responsibility to ensure that:

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

Errors

• Returns EntityComponentError::MissingComponent if a component is missing from the entity.
• Returns EntityComponentError::AliasedMutability if a component is requested multiple times.

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl DynamicComponentFetch for &HashSet<ComponentId>

type Ref<'w> = HashMap<ComponentId, Ptr<'w>>

type Mut<'w> = HashMap<ComponentId, MutUntyped<'w>>

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

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

impl DynamicComponentFetch for &[ComponentId]

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

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

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

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

impl<const N: usize> DynamicComponentFetch for &[ComponentId; N]

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

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

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

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

impl<const N: usize> DynamicComponentFetch for [ComponentId; N]

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

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

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

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

Implementors

impl DynamicComponentFetch for ComponentId

type Ref<'w> = Ptr<'w>

type Mut<'w> = MutUntyped<'w>