Struct Bucket

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

A reference to a hash table bucket containing a T.

This is usually just a pointer to the element itself. However if the element is a ZST, then we instead track the index of the element in the table so that erase works properly.

Implementations

impl<T> Bucket<T>

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

Acquires the underlying raw pointer *mut T to data.

Note

If T is not Copy, do not use *mut T methods that can cause calling the destructor of T (for example the <*mut T>::drop_in_place method), because for properly dropping the data we also need to clear data control bytes. If we drop data, but do not clear data control byte it leads to double drop when RawTable goes out of scope.

If you modify an already initialized value, so Hash and Eq on the new T value and its borrowed form must match those for the old T value, as the map will not re-evaluate where the new value should go, meaning the value may become “lost” if their location does not reflect their state.

Examples

use core::hash::{BuildHasher, Hash};
use core::convert::Infallible;

use rune::alloc::hashbrown::raw::{Bucket, RawTable};

type NewHashBuilder = core::hash::BuildHasherDefault<ahash::AHasher>;

fn make_hash<K: Hash + ?Sized, S: BuildHasher>(hash_builder: &S, key: &K) -> u64 {
    use core::hash::Hasher;
    let mut state = hash_builder.build_hasher();
    key.hash(&mut state);
    state.finish()
}

let hash_builder = NewHashBuilder::default();
let mut table = RawTable::new();

let value = ("a", 100);
let hash = make_hash(&hash_builder, &value.0);

table.insert(&mut (), hash, value.clone(), |_: &mut (), val: &(&str, _)| Ok::<_, Infallible>(make_hash(&hash_builder, &val.0)));

let bucket: Bucket<(&str, i32)> = table.find(&mut (), hash, |_: &mut (), (k1, _): &(&str, _)| Ok::<_, Infallible>(k1 == &value.0)).unwrap().unwrap();

assert_eq!(unsafe { &*bucket.as_ptr() }, &("a", 100));

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

Returns a shared immutable reference to the value.

Safety

See NonNull::as_ref for safety concerns.

Examples

use core::hash::{BuildHasher, Hash};
use core::convert::Infallible;

use rune::alloc::hashbrown::raw::{Bucket, RawTable};

type NewHashBuilder = core::hash::BuildHasherDefault<ahash::AHasher>;

fn make_hash<K: Hash + ?Sized, S: BuildHasher>(hash_builder: &S, key: &K) -> u64 {
    use core::hash::Hasher;
    let mut state = hash_builder.build_hasher();
    key.hash(&mut state);
    state.finish()
}

let hash_builder = NewHashBuilder::default();
let mut table = RawTable::new();

let value: (&str, String) = ("A pony", "is a small horse".to_owned());
let hash = make_hash(&hash_builder, &value.0);

table.insert(&mut (), hash, value.clone(), |_: &mut (), (val, _): &(&str, _)| Ok::<_, Infallible>(make_hash(&hash_builder, val))).unwrap();

let bucket: Bucket<(&str, String)> = table.find(&mut (), hash, |_: &mut (), (k, _): &(&str, _)| Ok::<_, Infallible>(k == &value.0)).unwrap().unwrap();

assert_eq!(
    unsafe { bucket.as_ref() },
    &("A pony", "is a small horse".to_owned())
);

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

Returns a unique mutable reference to the value.

Safety

See NonNull::as_mut for safety concerns.

Note

Hash and Eq on the new T value and its borrowed form must match those for the old T value, as the map will not re-evaluate where the new value should go, meaning the value may become “lost” if their location does not reflect their state.

Examples

use core::hash::{BuildHasher, Hash};
use core::convert::Infallible;

use rune::alloc::hashbrown::raw::{Bucket, RawTable};

type NewHashBuilder = core::hash::BuildHasherDefault<ahash::AHasher>;

fn make_hash<K: Hash + ?Sized, S: BuildHasher>(hash_builder: &S, key: &K) -> u64 {
    use core::hash::Hasher;
    let mut state = hash_builder.build_hasher();
    key.hash(&mut state);
    state.finish()
}

let hash_builder = NewHashBuilder::default();
let mut table = RawTable::new();

let value: (&str, String) = ("A pony", "is a small horse".to_owned());
let hash = make_hash(&hash_builder, &value.0);

table.insert(&mut (), hash, value.clone(), |_: &mut (), (k, _): &(&str, _)| Ok::<_, Infallible>(make_hash(&hash_builder, k))).unwrap();

let bucket: Bucket<(&str, String)> = table.find(&mut (), hash, |_: &mut (), (k, _): &(&str, _)| Ok::<_, Infallible>(k == &value.0)).unwrap().unwrap();

unsafe {
    bucket
        .as_mut()
        .1
        .push_str(" less than 147 cm at the withers")
};
assert_eq!(
    unsafe { bucket.as_ref() },
    &(
        "A pony",
        "is a small horse less than 147 cm at the withers".to_owned()
    )
);

pub unsafe fn copy_from_nonoverlapping(&self, other: &Bucket<T>)

Copies size_of<T> bytes from other to self. The source and destination may not overlap.

Safety

See ptr::copy_nonoverlapping for safety concerns.

Like read, copy_nonoverlapping creates a bitwise copy of T, regardless of whether T is Copy. If T is not Copy, using both the values in the region beginning at *self and the region beginning at *other can violate memory safety.

Note

Hash and Eq on the new T value and its borrowed form must match those for the old T value, as the map will not re-evaluate where the new value should go, meaning the value may become “lost” if their location does not reflect their state.

Trait Implementations

impl<T> Clone for Bucket<T>

fn clone(&self) -> Bucket<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Send for Bucket<T>