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.

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 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>