[−][src]Struct handy::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
[src]
pub const EMPTY: Handle
[src]
A constant for the default (null) handle. Never valid or returned by any map.
pub const fn index(self) -> usize
[src]
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
[src]
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
[src]
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
[src]
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
[src]
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
[src]
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
[src]
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)
[src]
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
[src]
fn clone(&self) -> Handle
[src]
fn clone_from(&mut self, source: &Self)
1.0.0[src]
impl Copy for Handle
[src]
impl Debug for Handle
[src]
impl Default for Handle
[src]
impl Eq for Handle
[src]
impl Hash for Handle
[src]
fn hash<__H: Hasher>(&self, state: &mut __H)
[src]
fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,
1.3.0[src]
H: Hasher,
impl<T> Index<Handle> for HandleMap<T>
[src]
impl<T> IndexMut<Handle> for HandleMap<T>
[src]
impl Ord for Handle
[src]
fn cmp(&self, other: &Handle) -> Ordering
[src]
#[must_use]fn max(self, other: Self) -> Self
1.21.0[src]
#[must_use]fn min(self, other: Self) -> Self
1.21.0[src]
#[must_use]fn clamp(self, min: Self, max: Self) -> Self
[src]
impl PartialEq<Handle> for Handle
[src]
impl PartialOrd<Handle> for Handle
[src]
fn partial_cmp(&self, other: &Handle) -> Option<Ordering>
[src]
fn lt(&self, other: &Handle) -> bool
[src]
fn le(&self, other: &Handle) -> bool
[src]
fn gt(&self, other: &Handle) -> bool
[src]
fn ge(&self, other: &Handle) -> bool
[src]
impl StructuralEq for Handle
[src]
impl StructuralPartialEq for Handle
[src]
Auto Trait Implementations
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
fn to_owned(&self) -> T
[src]
fn clone_into(&self, target: &mut T)
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,