X-Git-Url: https://git.chrismorgan.info/anymap/blobdiff_plain/2bcbd9c551d256e06e3e3044a2a99f79a7946449..983fc421145cf18f5e3f6398b5b712ed5503f9fd:/src/lib.rs diff --git a/src/lib.rs b/src/lib.rs index d4f227a..79a4561 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -7,6 +7,8 @@ #![cfg_attr(not(feature = "std"), no_std)] use core::any::{Any, TypeId}; +use core::convert::TryInto; +use core::hash::{Hasher, BuildHasherDefault}; use core::marker::PhantomData; #[cfg(not(any(feature = "std", feature = "hashbrown")))] @@ -18,93 +20,46 @@ extern crate alloc; #[cfg(not(feature = "std"))] use alloc::boxed::Box; -use raw::RawMap; use any::{UncheckedAnyExt, IntoBox}; pub use any::CloneAny; -macro_rules! impl_common_methods { - ( - field: $t:ident.$field:ident; - new() => $new:expr; - with_capacity($with_capacity_arg:ident) => $with_capacity:expr; - ) => { - impl $t { - /// Create an empty collection. - #[inline] - pub fn new() -> $t { - $t { - $field: $new, - } - } - - /// Creates an empty collection with the given initial capacity. - #[inline] - pub fn with_capacity($with_capacity_arg: usize) -> $t { - $t { - $field: $with_capacity, - } - } - - /// Returns the number of elements the collection can hold without reallocating. - #[inline] - pub fn capacity(&self) -> usize { - self.$field.capacity() - } - - /// Reserves capacity for at least `additional` more elements to be inserted - /// in the collection. The collection may reserve more space to avoid - /// frequent reallocations. - /// - /// # Panics - /// - /// Panics if the new allocation size overflows `usize`. - #[inline] - pub fn reserve(&mut self, additional: usize) { - self.$field.reserve(additional) - } - - /// Shrinks the capacity of the collection as much as possible. It will drop - /// down as much as possible while maintaining the internal rules - /// and possibly leaving some space in accordance with the resize policy. - #[inline] - pub fn shrink_to_fit(&mut self) { - self.$field.shrink_to_fit() - } - - // Additional stable methods (as of 1.60.0-nightly) that could be added: - // try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> (1.57.0) - // shrink_to(&mut self, min_capacity: usize) (1.56.0) - - /// Returns the number of items in the collection. - #[inline] - pub fn len(&self) -> usize { - self.$field.len() - } - - /// Returns true if there are no items in the collection. - #[inline] - pub fn is_empty(&self) -> bool { - self.$field.is_empty() - } - - /// Removes all items from the collection. Keeps the allocated memory for reuse. - #[inline] - pub fn clear(&mut self) { - self.$field.clear() - } - } +#[cfg(all(feature = "std", not(feature = "hashbrown")))] +/// A re-export of [`std::collections::hash_map`] for raw access. +/// +/// If the `hashbrown` feature gets enabled, this will become an export of `hashbrown::hash_map`. +/// +/// As with [`RawMap`][crate::RawMap], this is exposed for compatibility reasons, since features +/// are supposed to be additive. This *is* imperfect, since the two modules are incompatible in a +/// few places (e.g. hashbrown’s entry types have an extra generic parameter), but it’s close, and +/// much too useful to give up the whole concept. +pub use std::collections::hash_map as raw_hash_map; + +#[cfg(feature = "hashbrown")] +/// A re-export of [`hashbrown::hash_map`] for raw access. +/// +/// If the `hashbrown` feature was disabled, this would become an export of +/// `std::collections::hash_map`. +/// +/// As with [`RawMap`][crate::RawMap], this is exposed for compatibility reasons, since features +/// are supposed to be additive. This *is* imperfect, since the two modules are incompatible in a +/// few places (e.g. hashbrown’s entry types have an extra generic parameter), but it’s close, and +/// much too useful to give up the whole concept. +pub use hashbrown::hash_map as raw_hash_map; - impl Default for $t { - #[inline] - fn default() -> $t { - $t::new() - } - } - } -} +use self::raw_hash_map::HashMap; mod any; -pub mod raw; + +/// Raw access to the underlying `HashMap`. +/// +/// This is a public type alias because the underlying `HashMap` could be +/// `std::collections::HashMap` or `hashbrown::HashMap`, depending on the crate features enabled. +/// For that reason, you should refer to this type as `anymap::RawMap` rather than +/// `std::collections::HashMap` to avoid breakage if something else in your crate tree enables +/// hashbrown. +/// +/// See also [`raw_hash_map`], an export of the corresponding `hash_map` module. +pub type RawMap = HashMap, BuildHasherDefault>; /// A collection containing zero or one values for any given type and allowing convenient, /// type-safe access to those values. @@ -174,13 +129,78 @@ impl Clone for Map where Box: Clone { /// It’s a bit sad, really. Ah well, I guess this approach will do. pub type AnyMap = Map; -impl_common_methods! { - field: Map.raw; - new() => RawMap::new(); - with_capacity(capacity) => RawMap::with_capacity(capacity); +impl Default for Map { + #[inline] + fn default() -> Map { + Map::new() + } } impl Map { + /// Create an empty collection. + #[inline] + pub fn new() -> Map { + Map { + raw: RawMap::with_hasher(Default::default()), + } + } + + /// Creates an empty collection with the given initial capacity. + #[inline] + pub fn with_capacity(capacity: usize) -> Map { + Map { + raw: RawMap::with_capacity_and_hasher(capacity, Default::default()), + } + } + + /// Returns the number of elements the collection can hold without reallocating. + #[inline] + pub fn capacity(&self) -> usize { + self.raw.capacity() + } + + /// Reserves capacity for at least `additional` more elements to be inserted + /// in the collection. The collection may reserve more space to avoid + /// frequent reallocations. + /// + /// # Panics + /// + /// Panics if the new allocation size overflows `usize`. + #[inline] + pub fn reserve(&mut self, additional: usize) { + self.raw.reserve(additional) + } + + /// Shrinks the capacity of the collection as much as possible. It will drop + /// down as much as possible while maintaining the internal rules + /// and possibly leaving some space in accordance with the resize policy. + #[inline] + pub fn shrink_to_fit(&mut self) { + self.raw.shrink_to_fit() + } + + // Additional stable methods (as of 1.60.0-nightly) that could be added: + // try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> (1.57.0) + // shrink_to(&mut self, min_capacity: usize) (1.56.0) + + /// Returns the number of items in the collection. + #[inline] + pub fn len(&self) -> usize { + self.raw.len() + } + + /// Returns true if there are no items in the collection. + #[inline] + pub fn is_empty(&self) -> bool { + self.raw.is_empty() + } + + /// Removes all items from the collection. Keeps the allocated memory for reuse. + #[inline] + pub fn clear(&mut self) { + self.raw.clear() + } + /// Returns a reference to the value stored in the collection for the type `T`, if it exists. #[inline] pub fn get>(&self) -> Option<&T> { @@ -227,57 +247,121 @@ impl Map { #[inline] pub fn entry>(&mut self) -> Entry { match self.raw.entry(TypeId::of::()) { - raw::Entry::Occupied(e) => Entry::Occupied(OccupiedEntry { + raw_hash_map::Entry::Occupied(e) => Entry::Occupied(OccupiedEntry { inner: e, type_: PhantomData, }), - raw::Entry::Vacant(e) => Entry::Vacant(VacantEntry { + raw_hash_map::Entry::Vacant(e) => Entry::Vacant(VacantEntry { inner: e, type_: PhantomData, }), } } -} -impl Extend> for Map { + /// Get access to the raw hash map that backs this. + /// + /// This will seldom be useful, but it’s conceivable that you could wish to iterate over all + /// the items in the collection, and this lets you do that. + /// + /// To improve compatibility with Cargo features, interact with this map through the names + /// [`anymap::RawMap`][RawMap] and [`anymap::raw_hash_map`][raw_hash_map], rather than through + /// `std::collections::{HashMap, hash_map}` or `hashbrown::{HashMap, hash_map}`, for anything + /// beyond self methods. Otherwise, if you use std and another crate in the tree enables + /// hashbrown, your code will break. #[inline] - fn extend>>(&mut self, iter: T) { - for item in iter { - let _ = unsafe { self.raw.insert(item.type_id(), item) }; - } + pub fn as_raw(&self) -> &RawMap { + &self.raw } -} -impl AsRef> for Map { + /// Get mutable access to the raw hash map that backs this. + /// + /// This will seldom be useful, but it’s conceivable that you could wish to iterate over all + /// the items in the collection mutably, or drain or something, or *possibly* even batch + /// insert, and this lets you do that. + /// + /// To improve compatibility with Cargo features, interact with this map through the names + /// [`anymap::RawMap`][RawMap] and [`anymap::raw_hash_map`][raw_hash_map], rather than through + /// `std::collections::{HashMap, hash_map}` or `hashbrown::{HashMap, hash_map}`, for anything + /// beyond self methods. Otherwise, if you use std and another crate in the tree enables + /// hashbrown, your code will break. + /// + /// # Safety + /// + /// If you insert any values to the raw map, the key (a `TypeId`) must match the value’s type, + /// or *undefined behaviour* will occur when you access those values. + /// + /// (*Removing* entries is perfectly safe.) #[inline] - fn as_ref(&self) -> &RawMap { - &self.raw + pub unsafe fn as_raw_mut(&mut self) -> &mut RawMap { + &mut self.raw } -} -impl AsMut> for Map { + /// Convert this into the raw hash map that backs this. + /// + /// This will seldom be useful, but it’s conceivable that you could wish to consume all the + /// items in the collection and do *something* with some or all of them, and this lets you do + /// that, without the `unsafe` that `.as_raw_mut().drain()` would require. + /// + /// To improve compatibility with Cargo features, interact with this map through the names + /// [`anymap::RawMap`][RawMap] and [`anymap::raw_hash_map`][raw_hash_map], rather than through + /// `std::collections::{HashMap, hash_map}` or `hashbrown::{HashMap, hash_map}`, for anything + /// beyond self methods. Otherwise, if you use std and another crate in the tree enables + /// hashbrown, your code will break. #[inline] - fn as_mut(&mut self) -> &mut RawMap { - &mut self.raw + pub fn into_raw(self) -> RawMap { + self.raw + } + + /// Construct a map from a collection of raw values. + /// + /// You know what? I can’t immediately think of any legitimate use for this, especially because + /// of the requirement of the `BuildHasherDefault` generic in the map. + /// + /// Perhaps this will be most practical as `unsafe { Map::from_raw(iter.collect()) }`, iter + /// being an iterator over `(TypeId, Box)` pairs. Eh, this method provides symmetry with + /// `into_raw`, so I don’t care if literally no one ever uses it. I’m not even going to write a + /// test for it, it’s so trivial. + /// + /// To improve compatibility with Cargo features, interact with this map through the names + /// [`anymap::RawMap`][RawMap] and [`anymap::raw_hash_map`][raw_hash_map], rather than through + /// `std::collections::{HashMap, hash_map}` or `hashbrown::{HashMap, hash_map}`, for anything + /// beyond self methods. Otherwise, if you use std and another crate in the tree enables + /// hashbrown, your code will break. + /// + /// # Safety + /// + /// For all entries in the raw map, the key (a `TypeId`) must match the value’s type, + /// or *undefined behaviour* will occur when you access that entry. + #[inline] + pub unsafe fn from_raw(raw: RawMap) -> Map { + Self { raw } } } -impl From> for RawMap { +impl Extend> for Map { #[inline] - fn from(map: Map) -> RawMap { - map.raw + fn extend>>(&mut self, iter: T) { + for item in iter { + let _ = self.raw.insert(item.type_id(), item); + } } } /// A view into a single occupied location in an `Map`. pub struct OccupiedEntry<'a, A: ?Sized + UncheckedAnyExt, V: 'a> { - inner: raw::OccupiedEntry<'a, A>, + #[cfg(all(feature = "std", not(feature = "hashbrown")))] + inner: raw_hash_map::OccupiedEntry<'a, TypeId, Box>, + #[cfg(feature = "hashbrown")] + inner: raw_hash_map::OccupiedEntry<'a, TypeId, Box, BuildHasherDefault>, type_: PhantomData, } /// A view into a single empty location in an `Map`. pub struct VacantEntry<'a, A: ?Sized + UncheckedAnyExt, V: 'a> { - inner: raw::VacantEntry<'a, A>, + #[cfg(all(feature = "std", not(feature = "hashbrown")))] + inner: raw_hash_map::VacantEntry<'a, TypeId, Box>, + #[cfg(feature = "hashbrown")] + inner: raw_hash_map::VacantEntry<'a, TypeId, Box, BuildHasherDefault>, type_: PhantomData, } @@ -309,6 +393,34 @@ impl<'a, A: ?Sized + UncheckedAnyExt, V: IntoBox> Entry<'a, A, V> { Entry::Vacant(inner) => inner.insert(default()), } } + + /// Ensures a value is in the entry by inserting the default value if empty, + /// and returns a mutable reference to the value in the entry. + #[inline] + pub fn or_default(self) -> &'a mut V where V: Default { + match self { + Entry::Occupied(inner) => inner.into_mut(), + Entry::Vacant(inner) => inner.insert(Default::default()), + } + } + + /// Provides in-place mutable access to an occupied entry before any potential inserts into the + /// map. + #[inline] + // std::collections::hash_map::Entry::and_modify doesn’t have #[must_use], I’ll follow suit. + #[allow(clippy::return_self_not_must_use)] + pub fn and_modify(self, f: F) -> Self { + match self { + Entry::Occupied(mut inner) => { + f(inner.get_mut()); + Entry::Occupied(inner) + }, + Entry::Vacant(inner) => Entry::Vacant(inner), + } + } + + // Additional stable methods (as of 1.60.0-nightly) that could be added: + // insert_entry(self, value: V) -> OccupiedEntry<'a, K, V> (1.59.0) } impl<'a, A: ?Sized + UncheckedAnyExt, V: IntoBox> OccupiedEntry<'a, A, V> { @@ -353,6 +465,35 @@ impl<'a, A: ?Sized + UncheckedAnyExt, V: IntoBox> VacantEntry<'a, A, V> { } } +/// A hasher designed to eke a little more speed out, given `TypeId`’s known characteristics. +/// +/// Specifically, this is a no-op hasher that expects to be fed a u64’s worth of +/// randomly-distributed bits. It works well for `TypeId` (eliminating start-up time, so that my +/// get_missing benchmark is ~30ns rather than ~900ns, and being a good deal faster after that, so +/// that my insert_and_get_on_260_types benchmark is ~12μs instead of ~21.5μs), but will +/// panic in debug mode and always emit zeros in release mode for any other sorts of inputs, so +/// yeah, don’t use it! 😀 +#[derive(Default)] +pub struct TypeIdHasher { + value: u64, +} + +impl Hasher for TypeIdHasher { + #[inline] + fn write(&mut self, bytes: &[u8]) { + // This expects to receive exactly one 64-bit value, and there’s no realistic chance of + // that changing, but I don’t want to depend on something that isn’t expressly part of the + // contract for safety. But I’m OK with release builds putting everything in one bucket + // if it *did* change (and debug builds panicking). + debug_assert_eq!(bytes.len(), 8); + let _ = bytes.try_into() + .map(|array| self.value = u64::from_ne_bytes(array)); + } + + #[inline] + fn finish(&self) -> u64 { self.value } +} + #[cfg(test)] mod tests { use super::*; @@ -487,4 +628,23 @@ mod tests { assert_debug::>(); assert_debug::>(); } + + #[test] + fn type_id_hasher() { + #[cfg(not(feature = "std"))] + use alloc::vec::Vec; + use core::hash::Hash; + fn verify_hashing_with(type_id: TypeId) { + let mut hasher = TypeIdHasher::default(); + type_id.hash(&mut hasher); + // SAFETY: u64 is valid for all bit patterns. + assert_eq!(hasher.finish(), unsafe { core::mem::transmute::(type_id) }); + } + // Pick a variety of types, just to demonstrate it’s all sane. Normal, zero-sized, unsized, &c. + verify_hashing_with(TypeId::of::()); + verify_hashing_with(TypeId::of::<()>()); + verify_hashing_with(TypeId::of::()); + verify_hashing_with(TypeId::of::<&str>()); + verify_hashing_with(TypeId::of::>()); + } }