Struct handy::Handle

pub struct Handle(_);

An untyped reference to some value. Handles are just a fancy u64.

Internally these store:

• A 32-bit index field.
• The 16-bit 'generation' of that index (this is incremented both when an item is removed from the index, and when another is inserted).
• An extra value typically used to store the ID of their map.

They're a #[repr(transparent)] wrapper around a u64, so if they need to be passed into C code over the FFI, that can be done directly.

Advanced Details

Typical use of this library expects that you just treat these as opaque, however you're free to inspect and construct them as you please (with from_raw and from_raw_parts), with the caveat that using the API to do so could cause the map to return non-sensical answers.

That said, should you want to do so, you absolutely can.

Some important notes if you're going to construct these:

• Valid indices should always be between 0 and i32::max_value.

• Generations for occupied indexs have a even value, and for empty indexs have an odd value. The zero generation is always skipped, and is never considered valid.

• If used with a HandleMap, the meta value must match the map they came from.

Implementations

impl Handle

pub const EMPTY: Handle

A constant for the default (null) handle. Never valid or returned by any map.

pub const fn index(self) -> usize

Returns the index value of this handle.

While a usize is returned, this value is guaranteed to be 32 bits.

Caveat

This is a low level feature intended for advanced usage, typically you do not need to access this value, however doing so is harmless.

pub const fn generation(self) -> u16

Returns the generation value of this handle.

Caveat

This is a low level feature intended for advanced usage, typically you do not need to access this value, however doing so is harmless.

pub const fn map_id(self) -> u16

Returns the metadata field of this handle. This is an alias for map_id, as in the common case, this is what the metadata field is used for.

See Handle::meta for more info.

pub const fn meta(self) -> u16

Returns the metadata field of this handle.

If used with a HandleMap (instead of directly coming from a HandleAlloc), this is the id of the HandleMap which constructed this handle. If used with a HandleAlloc, then the value has no meaning aside from whatever you assign to it -- it's 16 free bits you can use for whatever tagging you want.

Caveat

This is a low level feature intended for advanced usage, typically you do not need to access this value, however doing so is harmless.

pub const fn from_raw_parts(index: usize, generation: u16, meta: u16) -> Self

Construct a handle from the separate parts.

Warning

This is a feature intended for advanced usage. An attempt is made to cope with dubious handles, but it's almost certainly possible to pierce the abstraction veil of the HandleMap if you use this.

However, it should not be possible to cause memory unsafety -- this crate has no unsafe code.

pub const fn from_raw(value: u64) -> Self

Construct a handle from it's internal u64 value.

Layout

The 64 bit value is interpreted as such. It's recommended that you instead use from_raw_parts to construct these in cases where this is relevant, though.

[16 bits of generation | 16 bits of map id | 32 bit index]
MSB                                                    LSB

Warning

This is a feature intended for advanced usage. An attempt is made to cope with dubious handles, but it's almost certainly possible to pierce the abstraction veil of the HandleMap if you use this.

However, it should not be possible to cause memory unsafety -- this crate has no unsafe code.

pub const fn into_raw(self) -> u64

Get the internal u64 representation of this handle.

Caveat

This is a low level feature intended for advanced usage, typically you do not need to access this value, however doing so is harmless.

Layout

The layout of the returned value is as such:

[16 bits of generation | 16 bits of map id | 32 bit index]
MSB                                                    LSB

pub fn decompose(self) -> (u32, u16, u16)

Get the internal parts of this handle.

Equivalent to (self.index(), self.generation(), self.meta())

Caveat

This is a low level feature intended for advanced usage, typically you do not need to access this value, however doing so is harmless.

Trait Implementations

impl Clone for Handle

fn clone(&self) -> Handle

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Copy for Handle

impl Debug for Handle

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

Formats the value using the given formatter.

impl Default for Handle

fn default() -> Handle

Returns the "default value" for a type.

impl Eq for Handle

impl Hash for Handle

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl<T> Index<Handle> for HandleMap<T>

type Output = T

The returned type after indexing.

fn index(&self, h: Handle) -> &T

Performs the indexing (container[index]) operation.

impl<T> IndexMut<Handle> for HandleMap<T>

fn index_mut(&mut self, h: Handle) -> &mut T

Performs the mutable indexing (container[index]) operation.

impl Ord for Handle

fn cmp(&self, other: &Handle) -> Ordering

This method returns an [Ordering] between self and other.

#[must_use]fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl PartialEq<Handle> for Handle

fn eq(&self, other: &Handle) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Handle) -> bool

This method tests for !=.

impl PartialOrd<Handle> for Handle

fn partial_cmp(&self, other: &Handle) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Handle) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Handle) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Handle) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Handle) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StructuralEq for Handle

impl StructuralPartialEq for Handle