From: Chris Morgan Date: Tue, 6 Jan 2015 13:39:06 +0000 (+1100) Subject: 0.9.7: parity with the collections API X-Git-Tag: 0.9.7 X-Git-Url: https://git.chrismorgan.info/anymap/commitdiff_plain/0e65782e654c4b3659095acdf674659e6816bac3 0.9.7: parity with the collections API There’s some Rust updating here too. This entails the addition of various methods and iterator types where appropriate, based on what’s on `HashMap`, though I doubt that people will actually be able to make all that much use of the iterators. They’d be of more use with a basis of a trait other than `Any`, such as might be conveniently achieved by combining this with my MOPA crate. (Getting a little close to HKT there, innit?) You know, I wonder sometimes if anyone ever reads these messages after they are written, myself included. If you have read this, please drop me a note; I’m curious. I’ve also gone over all the stability attributes, marking things as appropriate. --- diff --git a/Cargo.toml b/Cargo.toml index 67a0be7..567ac12 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "anymap" -version = "0.9.6" +version = "0.9.7" authors = ["Chris Morgan "] description = "A safe and convenient store for one value of each type" #documentation = "http://www.rust-ci.org/chris-morgan/anymap/doc/anymap/index.html" diff --git a/src/lib.rs b/src/lib.rs index 16644bf..36210f5 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,6 +1,5 @@ //! This crate provides the `AnyMap` type, a safe and convenient store for one value of each type. -#![feature(default_type_params)] #![warn(unused_qualifications, non_upper_case_globals, variant_size_differences, unused_typecasts, missing_docs, unused_results)] @@ -36,7 +35,7 @@ impl Writer for TypeIdState { } impl Hasher for TypeIdHasher { - fn hash>(&self, value: &T) -> u64 { + fn hash>(&self, value: &T) -> u64 { let mut state = TypeIdState { value: 0, }; @@ -102,7 +101,7 @@ impl UncheckedBoxAny for Box { } } -/// A map containing zero or one values for any given type and allowing convenient, +/// A collection containing zero or one values for any given type and allowing convenient, /// type-safe access to those values. /// /// ```rust @@ -127,63 +126,137 @@ impl UncheckedBoxAny for Box { /// ``` /// /// Values containing non-static references are not permitted. +#[stable] pub struct AnyMap { data: HashMap, TypeIdHasher>, } impl AnyMap { /// Construct a new `AnyMap`. + #[inline] + #[stable] pub fn new() -> AnyMap { AnyMap { data: HashMap::with_hasher(TypeIdHasher), } } -} -impl AnyMap { - /// Deprecated: Renamed to `get`. - #[deprecated = "Renamed to `get`"] - pub fn find(&self) -> Option<&T> { - self.get::() + /// Creates an empty AnyMap with the given initial capacity. + #[inline] + #[stable] + pub fn with_capcity(capacity: uint) -> AnyMap { + AnyMap { + data: HashMap::with_capacity_and_hasher(capacity, TypeIdHasher), + } + } + + /// Returns the number of elements the collection can hold without reallocating. + #[inline] + #[stable] + pub fn capacity(&self) -> uint { + self.data.capacity() + } + + /// Reserves capacity for at least `additional` more elements to be inserted + /// in the `AnyMap`. The collection may reserve more space to avoid + /// frequent reallocations. + /// + /// # Panics + /// + /// Panics if the new allocation size overflows `uint`. + #[inline] + #[stable] + pub fn reserve(&mut self, additional: uint) { + self.data.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] + #[stable] + pub fn shrink_to_fit(&mut self) { + self.data.shrink_to_fit() + } + + /// An iterator visiting all items in the collection in arbitrary order. + /// Iterator element type is `&Any`. + /// + /// This is probably not a great deal of use. + #[inline] + #[stable] + pub fn iter(&self) -> Iter { + Iter { + inner: self.data.iter(), + } } - /// Deprecated: Renamed to `get_mut`. - #[deprecated = "Renamed to `get_mut`"] - pub fn find_mut(&mut self) -> Option<&mut T> { - self.get_mut::() + /// An iterator visiting all items in the collection in arbitrary order. + /// Iterator element type is `&mut Any`. + /// + /// This is probably not a great deal of use. + #[inline] + #[stable] + pub fn iter_mut(&mut self) -> IterMut { + IterMut { + inner: self.data.iter_mut(), + } } - /// Retrieve the value stored in the map for the type `T`, if it exists. + /// An iterator visiting all items in the collection in arbitrary order. + /// Creates a consuming iterator, that is, one that moves each item + /// out of the map in arbitrary order. The map cannot be used after + /// calling this. + /// + /// Iterator element type is `Box`. + #[inline] + #[stable] + pub fn into_iter(self) -> IntoIter { + IntoIter { + inner: self.data.into_iter(), + } + } + + /// Returns a reference to the value stored in the collection for the type `T`, if it exists. + #[stable] pub fn get(&self) -> Option<&T> { self.data.get(&TypeId::of::()) .map(|any| unsafe { any.downcast_ref_unchecked::() }) } - /// Retrieve a mutable reference to the value stored in the map for the type `T`, if it exists. + /// Returns a mutable reference to the value stored in the collection for the type `T`, + /// if it exists. + #[stable] pub fn get_mut(&mut self) -> Option<&mut T> { self.data.get_mut(&TypeId::of::()) .map(|any| unsafe { any.downcast_mut_unchecked::() }) } - /// Set the value contained in the map for the type `T`. - /// If there is a previous value stored, it will be returned. + /// Sets the value stored in the collection for the type `T`. + /// If the collection already had a value of type `T`, that value is returned. + /// Otherwise, `None` is returned. + #[stable] pub fn insert(&mut self, value: T) -> Option { self.data.insert(TypeId::of::(), box value as Box) .map(|any| *unsafe { any.downcast_unchecked::() }) } - /// Remove and return the value for the type `T` if it existed. + /// Removes the `T` value from the collection, + /// returning it if there was one or `None` if there was not. + #[stable] pub fn remove(&mut self) -> Option { self.data.remove(&TypeId::of::()) .map(|any| *unsafe { any.downcast_unchecked::() }) } - /// Does a value of type `T` exist? + /// Returns true if the collection contains a value of type `T`. + #[stable] pub fn contains(&self) -> bool { self.data.contains_key(&TypeId::of::()) } - /// Gets the given key's corresponding entry in the map for in-place manipulation + /// Gets the entry for the given type in the collection for in-place manipulation + #[stable] pub fn entry(&mut self) -> Entry { match self.data.entry(TypeId::of::()) { hash_map::Entry::Occupied(e) => Entry::Occupied(OccupiedEntry { entry: e }), @@ -192,32 +265,54 @@ impl AnyMap { } /// Returns the number of items in the collection. + #[inline] + #[stable] pub fn len(&self) -> uint { self.data.len() } /// Returns true if there are no items in the collection. + #[inline] + #[stable] pub fn is_empty(&self) -> bool { self.data.is_empty() } - /// Removes all items from the collection. + /// Clears the map, returning all items as an iterator. + /// + /// Iterator element type is `Box`. + /// + /// Keeps the allocated memory for reuse. + #[inline] + #[unstable = "matches collection reform specification, waiting for dust to settle"] + pub fn drain(&mut self) -> Drain { + Drain { + inner: self.data.drain(), + } + } + + /// Removes all items from the collection. Keeps the allocated memory for reuse. + #[inline] + #[stable] pub fn clear(&mut self) { self.data.clear(); } } /// A view into a single occupied location in an AnyMap +#[stable] pub struct OccupiedEntry<'a, V: 'a> { entry: hash_map::OccupiedEntry<'a, TypeId, Box>, } /// A view into a single empty location in an AnyMap +#[stable] pub struct VacantEntry<'a, V: 'a> { entry: hash_map::VacantEntry<'a, TypeId, Box>, } -/// A view into a single location in a map, which may be vacant or occupied +/// A view into a single location in an AnyMap, which may be vacant or occupied +#[stable] pub enum Entry<'a, V: 'a> { /// An occupied Entry Occupied(OccupiedEntry<'a, V>), @@ -225,42 +320,136 @@ pub enum Entry<'a, V: 'a> { Vacant(VacantEntry<'a, V>), } +impl<'a, V: 'static + Clone> Entry<'a, V> { + #[unstable = "matches collection reform v2 specification, waiting for dust to settle"] + /// Returns a mutable reference to the entry if occupied, or the VacantEntry if vacant + pub fn get(self) -> Result<&'a mut V, VacantEntry<'a, V>> { + match self { + Entry::Occupied(entry) => Ok(entry.into_mut()), + Entry::Vacant(entry) => Err(entry), + } + } +} + impl<'a, V: 'static> OccupiedEntry<'a, V> { + #[stable] /// Gets a reference to the value in the entry pub fn get(&self) -> &V { unsafe { self.entry.get().downcast_ref_unchecked() } } + #[stable] /// Gets a mutable reference to the value in the entry pub fn get_mut(&mut self) -> &mut V { unsafe { self.entry.get_mut().downcast_mut_unchecked() } } + #[stable] /// Converts the OccupiedEntry into a mutable reference to the value in the entry - /// with a lifetime bound to the map itself + /// with a lifetime bound to the collection itself pub fn into_mut(self) -> &'a mut V { unsafe { self.entry.into_mut().downcast_mut_unchecked() } } + #[stable] /// Sets the value of the entry, and returns the entry's old value - pub fn set(&mut self, value: V) -> V { - unsafe { *self.entry.set(box value as Box).downcast_unchecked() } + pub fn insert(&mut self, value: V) -> V { + unsafe { *self.entry.insert(box value as Box).downcast_unchecked() } } + #[stable] /// Takes the value out of the entry, and returns it - pub fn take(self) -> V { - unsafe { *self.entry.take().downcast_unchecked() } + pub fn remove(self) -> V { + unsafe { *self.entry.remove().downcast_unchecked() } } } impl<'a, V: 'static> VacantEntry<'a, V> { + #[stable] /// Sets the value of the entry with the VacantEntry's key, /// and returns a mutable reference to it - pub fn set(self, value: V) -> &'a mut V { - unsafe { self.entry.set(box value as Box).downcast_mut_unchecked() } + pub fn insert(self, value: V) -> &'a mut V { + unsafe { self.entry.insert(box value as Box).downcast_mut_unchecked() } } } +/// `AnyMap` iterator. +#[stable] +#[derive(Clone)] +pub struct Iter<'a> { + inner: hash_map::Iter<'a, TypeId, Box>, +} + +/// `AnyMap` mutable references iterator. +#[stable] +pub struct IterMut<'a> { + inner: hash_map::IterMut<'a, TypeId, Box>, +} + +/// `AnyMap` draining iterator. +#[unstable = "matches collection reform specification, waiting for dust to settle"] +pub struct Drain<'a> { + inner: hash_map::Drain<'a, TypeId, Box>, +} + +/// `AnyMap` move iterator. +#[stable] +pub struct IntoIter { + inner: hash_map::IntoIter>, +} + +#[stable] +impl<'a> Iterator for Iter<'a> { + type Item = &'a Any; + + #[inline] + fn next(&mut self) -> Option<&'a Any> { + self.inner.next().map(|item| &**item.1) + } + + #[inline] + fn size_hint(&self) -> (uint, Option) { self.inner.size_hint() } +} + +#[stable] +impl<'a> Iterator for IterMut<'a> { + type Item = &'a mut Any; + + #[inline] + fn next(&mut self) -> Option<&'a mut Any> { + self.inner.next().map(|item| &mut **item.1) + } + + #[inline] + fn size_hint(&self) -> (uint, Option) { self.inner.size_hint() } +} + +#[stable] +impl<'a> Iterator for Drain<'a> { + type Item = Box; + + #[inline] + fn next(&mut self) -> Option> { + self.inner.next().map(|item| item.1) + } + + #[inline] + fn size_hint(&self) -> (uint, Option) { self.inner.size_hint() } +} + +#[stable] +impl Iterator for IntoIter { + type Item = Box; + + #[inline] + fn next(&mut self) -> Option> { + self.inner.next().map(|item| item.1) + } + + #[inline] + fn size_hint(&self) -> (uint, Option) { self.inner.size_hint() } +} + #[bench] fn bench_insertion(b: &mut ::test::Bencher) { b.iter(|| { @@ -316,7 +505,7 @@ fn test_entry() { Entry::Vacant(_) => unreachable!(), Entry::Occupied(mut view) => { assert_eq!(view.get(), &A(10)); - assert_eq!(view.set(A(100)), A(10)); + assert_eq!(view.insert(A(100)), A(10)); } } assert_eq!(map.get::().unwrap(), &A(100)); @@ -336,11 +525,11 @@ fn test_entry() { assert_eq!(map.len(), 6); - // Existing key (take) + // Existing key (remove) match map.entry::() { Entry::Vacant(_) => unreachable!(), Entry::Occupied(view) => { - assert_eq!(view.take(), C(30)); + assert_eq!(view.remove(), C(30)); } } assert_eq!(map.get::(), None); @@ -351,7 +540,7 @@ fn test_entry() { match map.entry::() { Entry::Occupied(_) => unreachable!(), Entry::Vacant(view) => { - assert_eq!(*view.set(J(1000)), J(1000)); + assert_eq!(*view.insert(J(1000)), J(1000)); } } assert_eq!(map.get::().unwrap(), &J(1000));