Struct DataHandle

pub struct DataHandle<T: DataObject + 'static> { /* private fields */ }

A path to a data resource, resolvable to a cached DataId.

This object serves three purposes:

• Conveniently resolving a path to an ID but only when resolution is necessary
• Serializing data that needs to reference a DataObject
• Keeping a package open so it doesn’t get auto-unloaded.

If placing inside a DataObject struct, take care not to have a self-referencing type (i.e. a DataHandle<T> inside a T) or a type cycle (i.e. a DataHandle<T> inside a U and a DataHandle<U> inside a T). Otherwise the auto-unload mechanism may not be able to unload the package the object is from.

Implementations

impl<T: DataObject + 'static> DataHandle<T>

pub fn null() -> DataHandle<T>

Creates a new DataHandle that points to nothing. Resolving this data handle will fail until it is given a valid path, such as through set_path().

pub fn with_path(package: &str, path: &str) -> DataHandle<T>

Creates a new DataHandle with the given resource path. The data ID will be unresolved. You will need to call resolve() for the data ID to point to a valid resource.

pub fn clone_without_path(&self) -> DataHandle<T>

Clones the given DataHandle but only retains the ID, erasing the path. This is useful for instances where you want to store a lot of handles but don’t need the path, to cut down on memory usage.

pub fn set_path(&mut self, package: &str, path: &str)

Changes the resource path. The data ID will reset to be unresolved. You will need to call resolve() for the data ID to point to a valid resource.

pub fn package(&self) -> &String

Returns the package name part of the resource path

pub fn path(&self) -> &String

Returns the filepath to the resource

pub fn id(&self) -> DataId<T>

Returns the data ID. You will need to call resolve() beforehand for the data ID to point to a valid resource.

pub fn resolved(&self) -> bool

Returns true if the path has been resolved via a call to resolve().

pub fn resolve( &self, data_res: &mut DataStore<T>, load_error: LoadErrorMode, ) -> DataId<T>

Resolves the data ID using the given DataStore. Returns the resolved data ID, which is cached inside the object. If load_error is Fatal, this function will panic if the load fails. Otherwise it will simply return a null data ID.

pub fn get<'a, 'b: 'a>( &self, data_res: &'b mut DataStore<T>, load_error: LoadErrorMode, ) -> Option<&'a T>

Returns a reference to data object in the store, if it exists. If the data object is not resolved, then resolve() will be called, and then the data object reference returned, if available.

pub fn get_mut<'a, 'b: 'a>( &self, data_res: &'b mut DataStore<T>, load_error: LoadErrorMode, ) -> Option<&'a mut T>

Returns a mutable reference to data object in the store, if it exists. If the data object is not resolved, then resolve() will be called, and then the data object reference returned, if available.

pub fn get_if_resolved<'a, 'b: 'a>( &self, data_res: &'b DataStore<T>, ) -> Option<&'a T>

Returns a reference to data object in the store, if it exists. If the data object is not resolved, returns None instead of attempting to resolve.

pub fn get_mut_if_resolved<'a, 'b: 'a>( &self, data_res: &'b mut DataStore<T>, ) -> Option<&'a mut T>

Returns a mutable reference to data object in the store, if it exists. If the data object is not resolved, returns None instead of attempting to resolve.

pub fn resolve_if_loaded(&self, data_res: &DataStore<T>) -> DataId<T>

Resolves the data ID using the given DataStore. Returns the resolved data ID, which is cached inside the object. If the data is not yet loaded, returns a null ID.

Trait Implementations

impl<T: DataObject + 'static> Clone for DataHandle<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: DataObject + 'static> Debug for DataHandle<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: DataObject + 'static> Default for DataHandle<T>

fn default() -> Self

Returns the “default value” for a type.