Struct FlaggedPtr

Source

pub struct FlaggedPtr<P, F, M>where
    P: PtrMeta<M>,
    F: FlagMeta,
    M: Copy,
{ /* private fields */ }

Expand description

A pointer that stores flags within unused bits of the pointer representation.

This struct combines a pointer and flag information into a single usize value by utilizing unused bits in the pointer due to alignment requirements.

§Type Parameters

P: The pointer type (e.g., Box<T>, NonNull<T>, Rc<T>)
F: The flag type (must implement FlagMeta)
M: Metadata associated with the pointer

§Examples

use flagged_pointer::FlaggedPtr;
use enumflags2::{bitflags, BitFlags};

#[bitflags]
#[repr(u8)]
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
enum Color {
    Red = 1 << 0,
    Blue = 1 << 1,
    Green = 1 << 2,
}

let boxed = Box::new("hello");
let flagged = FlaggedPtr::new(boxed, Color::Red | Color::Blue);

assert_eq!(*flagged, "hello");
assert_eq!(flagged.flag(), Color::Red | Color::Blue);

§Example with trait object

use flagged_pointer::alias::*;
use std::sync::Arc;
use ptr_meta::pointee;
use enumflags2::{bitflags,BitFlags};

#[bitflags]
#[repr(u8)]
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
enum Color {
    Red = 1 << 0,
    Blue = 1 << 1,
    Green = 1 << 2,
}

#[ptr_meta::pointee]
trait MyTrait {
   fn method(&self);
}

impl MyTrait for i64 {
   fn method(&self) {
       println!("i32 method");
   }
}

impl MyTrait for String {
   fn method(&self) {
       println!("String method");
   }
}

let trait_obj: FlaggedBoxDyn<dyn MyTrait, BitFlags<Color>> = FlaggedBoxDyn::new(Box::new(42_i64), Color::Red | Color::Blue);
trait_obj.method();
let trait_obj: FlaggedArcDyn<dyn MyTrait, BitFlags<Color>> = FlaggedArcDyn::new(Arc::new("hello".to_string()), Color::Red | Color::Blue);
trait_obj.method();

Implementations§

Source §

impl<P, F, M> FlaggedPtr<P, F, M>
where P: PtrMeta<M>, F: FlagMeta, M: Copy,

Source

pub fn new(ptr: P, flag: F) -> Self

Creates a new FlaggedPtr from a pointer and flags.

§Arguments

ptr: The pointer to store
flag: The flags to encode in the unused bits

§Examples

use flagged_pointer::FlaggedPtr;
use enumflags2::bitflags;
use std::ptr::NonNull;

#[bitflags]
#[repr(u8)]
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
enum MyFlags {
    A = 1 << 0,
    B = 1 << 1,
}

let boxed = Box::new(42);
let flagged = FlaggedPtr::new(boxed, MyFlags::A | MyFlags::B);
assert_eq!(*flagged, 42);

§Panics

Panics if the pointer and flag bits overlap, which should not happen for properly aligned pointers and reasonable flag values.

Source §

impl<P, F, M> FlaggedPtr<P, F, M>
where P: PtrMeta<M>, F: FlagMeta, M: Copy,

Source

pub fn flag(&self) -> F

Returns the flags stored in this pointer.

§Examples

use flagged_pointer::FlaggedPtr;
use enumflags2::bitflags;

#[bitflags]
#[repr(u8)]
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
enum MyFlags {
    A = 1 << 0,
    B = 1 << 1,
}

let boxed = Box::new(123);
let flagged = FlaggedPtr::new(boxed, MyFlags::A | MyFlags::B);
assert_eq!(flagged.flag(), MyFlags::A | MyFlags::B);

Source

pub fn set_flag(&mut self, flag: F)

Sets new flags for this pointer.

§Arguments

flag: The new flags to set

§Examples

use flagged_pointer::FlaggedPtr;
use enumflags2::bitflags;

#[bitflags]
#[repr(u8)]
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
enum MyFlags {
    A = 1 << 0,
    B = 1 << 1,
}

let boxed = Box::new(123);
let mut flagged = FlaggedPtr::new(boxed, MyFlags::A | MyFlags::B);
flagged.set_flag(MyFlags::B.into());
assert_eq!(flagged.flag(), MyFlags::B);

Source

pub fn dissolve(self) -> (P, F)

Consumes this FlaggedPtr and returns the original pointer and flags.

This is the inverse operation of new().

§Returns

A tuple containing (original_pointer, flags)

§Examples

use flagged_pointer::FlaggedPtr;
use enumflags2::bitflags;

#[bitflags]
#[repr(u8)]
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
enum MyFlags {
    A = 1 << 0,
    B = 1 << 1,
}

let boxed = Box::new(42);
let flagged = FlaggedPtr::new(boxed, MyFlags::A | MyFlags::B);
let (recovered_box, flags) = flagged.dissolve();

assert_eq!(*recovered_box, 42);
assert_eq!(flags, MyFlags::A | MyFlags::B);

Source

pub fn as_ptr(&self) -> NonNull<P::Pointee>

Returns a raw pointer to the pointee.

§Safety

The caller must ensure that the pointer is valid for the lifetime of self.

§Examples

use flagged_pointer::FlaggedPtr;
use enumflags2::bitflags;

#[bitflags]
#[repr(u8)]
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
enum MyFlags {
    A = 1 << 0,
    B = 1 << 1,
}

let boxed = Box::new(123);
let flagged = FlaggedPtr::new(boxed, MyFlags::A | MyFlags::B);
let ptr = flagged.as_ptr();
assert_eq!(unsafe { *ptr.as_ref() }, 123);