Struct PtrBool

Source

pub struct PtrBool<T> { /* private fields */ }

Expand description

A pointer and boolean bitpacked together.

PtrBools are the same size as a raw pointer; four bytes on a 32-bit system and eight bytes on a 64-bit system. This is done by storing in the boolean value in the one-bit of the pointer.

§Caveats

The pointer must be aligned by two to ensure that the one-bit is unnecessary and can be used to stored the boolean value.
Possibly a slight overhead when reading the values of the PtrBool, as the boolean value must be omitted from the pointer each time it’s read, and the pointer value must be omitted from the boolean value each time it is read. That is, unless there is some sort of unknown optimization built into Rust for the case of storing a boolean in one bit.
The value stored inside of a PtrBool must be Sized. This is because the pointer is converted to and from a usize; which loses any metadata which would have been in the raw pointer.

Implementations§

Source §

impl<T> PtrBool<T>

Source

pub fn new(ptr: *mut T, bool_: bool) -> Option<Self>

Initializes a PtrBool from the provided pointer and boolean values if the pointer is aligned by two.

§Examples

use ptr_bool::PtrBool;

let mut my_value = 42;
let ptr = PtrBool::new(&mut my_value as *mut _, true).unwrap();

assert_eq!(ptr.as_bool(), true);
unsafe {
    assert_eq!(*ptr.as_ref().unwrap(), 42);
}

Source

pub fn null(bool_: bool) -> Option<Self>

Initializes a PtrBool with a null pointer and the provided boolean value. Returns None if the type of this PtrBool is not aligned by 2.

§Examples

use ptr_bool::PtrBool;

let ptr: PtrBool<usize> = PtrBool::null(true).unwrap();

assert_eq!(ptr.as_bool(), true);
assert_eq!(ptr.is_null(), true);

Source

pub fn as_bool(&self) -> bool

Converts this PtrBool into a boolean value.

§Examples

use ptr_bool::PtrBool;

let ptr: PtrBool<usize> = PtrBool::null(true).unwrap();

assert_eq!(ptr.as_bool(), true);

Source

pub fn set_bool(&mut self, bool_: bool)

Sets the inner boolean value of this pointer.

§Examples

use ptr_bool::PtrBool;

let mut ptr: PtrBool<usize> = PtrBool::null(true).unwrap();

assert_eq!(ptr.as_bool(), true);
ptr.set_bool(false);
assert_eq!(ptr.as_bool(), false);

Source

pub fn as_ptr(&self) -> *const T

Converts this PtrBool into a raw pointer.

§Examples

use ptr_bool::PtrBool;
use std::ptr;

let mut ptr: PtrBool<usize> = PtrBool::null(true).unwrap();

assert_eq!(ptr.as_ptr(), ptr::null());

Source

pub fn as_mut_ptr(&self) -> *mut T

Converts this PtrBool into a raw mutable pointer.

§Examples

use ptr_bool::PtrBool;
use std::ptr;

let mut ptr: PtrBool<usize> = PtrBool::null(true).unwrap();

assert_eq!(ptr.as_mut_ptr(), ptr::null_mut());

Source

pub fn is_null(&self) -> bool

Returns true if the internal pointer is null.

§Examples

use ptr_bool::PtrBool;
use std::ptr;

let mut ptr: PtrBool<usize> = PtrBool::null(true).unwrap();

assert_eq!(ptr.is_null(), true);

Source

pub unsafe fn as_ref<'a>(&self) -> Option<&'a T>

Converts this PtrBool into a reference.

§Safety

By calling this method you promise that:

The wrapped pointer must be properly aligned.
This pointer must be dereferenceable in the sense defined in the ptr documentation.
The pointer must point to an initialized instance of T.
You must enforce Rust’s aliasing rules, since the returned lifetime 'a is arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. In particular, while this reference exists, the memory the pointer points to must not get mutated (except inside UnsafeCell).

If you are completely sure this pointer is not null; then the as_ref_unchecked method can be used instead.

§Examples

use ptr_bool::PtrBool;

let raw_ptr = Box::into_raw(Box::new(42));
let ptr_bool = PtrBool::new(raw_ptr, true).unwrap();

unsafe { assert_eq!(*ptr_bool.as_ref().unwrap(), 42) };
assert_eq!(ptr_bool.as_bool(), true);

unsafe { Box::from_raw(ptr_bool.as_mut_ptr()) };

Source

pub unsafe fn as_ref_unchecked<'a>(&self) -> &'a T

Converts this PtrBool into a reference. Equivalent to &*ptr_bool.as_mut_ptr() in terms of safety.

§Safety

By calling this method you promise that:

The wrapped pointer must be properly aligned.
This pointer must be dereferenceable in the sense defined in the ptr documentation.
The pointer must point to an initialized instance of T.
You must enforce Rust’s aliasing rules, since the returned lifetime 'a is arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. In particular, while this reference exists, the memory the pointer points to must not get mutated (except inside UnsafeCell).

If this pointer may be null, use the as_ref method instead.

§Examples

use ptr_bool::PtrBool;

let raw_ptr = Box::into_raw(Box::new(42));
let ptr_bool = PtrBool::new(raw_ptr, true).unwrap();

unsafe { assert_eq!(*ptr_bool.as_ref_unchecked(), 42) };
assert_eq!(ptr_bool.as_bool(), true);

unsafe { Box::from_raw(ptr_bool.as_mut_ptr()) };

Source

pub unsafe fn as_mut<'a>(&self) -> Option<&'a mut T>

Converts this PtrBool into a reference.

§Safety

By calling this method you promise that:

The wrapped pointer must be properly aligned.
This pointer must be dereferenceable in the sense defined in the ptr documentation.
The pointer must point to an initialized instance of T.
You must enforce Rust’s aliasing rules, since the returned lifetime 'a is arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. In particular, while this reference exists, the memory the pointer points to must not get accessed (read or written) through any other pointer.

If you are completely sure this pointer is not null; then the as_mut_unchecked method can be used instead.

§Examples

use ptr_bool::PtrBool;

let raw_ptr = Box::into_raw(Box::new(42));
let ptr_bool = PtrBool::new(raw_ptr, true).unwrap();

unsafe { assert_eq!(*ptr_bool.as_mut().unwrap(), 42) };
assert_eq!(ptr_bool.as_bool(), true);

unsafe { Box::from_raw(ptr_bool.as_mut_ptr()) };

Source

pub unsafe fn as_mut_unchecked<'a>(&self) -> &'a mut T

Converts this PtrBool into a reference. Equivalent to &mut *ptr_bool.as_mut_ptr() in terms of safety.

§Safety

By calling this method you promise that:

The wrapped pointer must be properly aligned.
This pointer must be dereferenceable in the sense defined in the ptr documentation.
The pointer must point to an initialized instance of T.
You must enforce Rust’s aliasing rules, since the returned lifetime 'a is arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. In particular, while this reference exists, the memory the pointer points to must not get accessed (read or written) through any other pointer.

If this pointer may be null, use the as_mut method instead.

§Examples

use ptr_bool::PtrBool;

let raw_ptr = Box::into_raw(Box::new(42));
let ptr_bool = PtrBool::new(raw_ptr, true).unwrap();

unsafe { assert_eq!(*ptr_bool.as_mut_unchecked(), 42) };
assert_eq!(ptr_bool.as_bool(), true);

unsafe { Box::from_raw(ptr_bool.as_mut_ptr()) };