diff --git a/library/alloc/src/collections/binary_heap/mod.rs b/library/alloc/src/collections/binary_heap/mod.rs index b0ec70ad565..d0a87e3fb9f 100644 --- a/library/alloc/src/collections/binary_heap/mod.rs +++ b/library/alloc/src/collections/binary_heap/mod.rs @@ -1470,6 +1470,13 @@ impl FusedIterator for IntoIter {} #[stable(feature = "default_iters", since = "CURRENT_RUSTC_VERSION")] impl Default for IntoIter { + /// Creates an empty `binary_heap::IntoIter`. + /// + /// ``` + /// # use std::collections::binary_heap; + /// let iter: binary_heap::IntoIter = Default::default(); + /// assert_eq!(iter.len(), 0); + /// ``` fn default() -> Self { IntoIter { iter: Default::default() } } diff --git a/library/alloc/src/collections/btree/map.rs b/library/alloc/src/collections/btree/map.rs index c1e8a84969a..8c8a459fec9 100644 --- a/library/alloc/src/collections/btree/map.rs +++ b/library/alloc/src/collections/btree/map.rs @@ -364,6 +364,13 @@ impl fmt::Debug for Iter<'_, K, V> { #[stable(feature = "default_iters", since = "CURRENT_RUSTC_VERSION")] impl<'a, K: 'a, V: 'a> Default for Iter<'a, K, V> { + /// Creates an empty `btree_map::Iter`. + /// + /// ``` + /// # use std::collections::btree_map; + /// let iter: btree_map::Iter<'_, u8, u8> = Default::default(); + /// assert_eq!(iter.len(), 0); + /// ``` fn default() -> Self { Iter { range: Default::default(), length: 0 } } @@ -395,6 +402,13 @@ impl fmt::Debug for IterMut<'_, K, V> { #[stable(feature = "default_iters", since = "CURRENT_RUSTC_VERSION")] impl<'a, K: 'a, V: 'a> Default for IterMut<'a, K, V> { + /// Creates an empty `btree_map::IterMut`. + /// + /// ``` + /// # use std::collections::btree_map; + /// let iter: btree_map::IterMut<'_, u8, u8> = Default::default(); + /// assert_eq!(iter.len(), 0); + /// ``` fn default() -> Self { IterMut { range: Default::default(), length: 0, _marker: PhantomData {} } } @@ -437,6 +451,13 @@ impl Debug for IntoIter { #[stable(feature = "default_iters", since = "CURRENT_RUSTC_VERSION")] impl Default for IntoIter { + /// Creates an empty `btree_map::IntoIter`. + /// + /// ``` + /// # use std::collections::btree_map; + /// let iter: btree_map::IntoIter = Default::default(); + /// assert_eq!(iter.len(), 0); + /// ``` fn default() -> Self { IntoIter { range: Default::default(), length: 0, alloc: Global } } @@ -1791,6 +1812,13 @@ impl Clone for Keys<'_, K, V> { #[stable(feature = "default_iters", since = "CURRENT_RUSTC_VERSION")] impl Default for Keys<'_, K, V> { + /// Creates an empty `btree_map::Keys`. + /// + /// ``` + /// # use std::collections::btree_map; + /// let iter: btree_map::Keys<'_, u8, u8> = Default::default(); + /// assert_eq!(iter.len(), 0); + /// ``` fn default() -> Self { Keys { inner: Default::default() } } @@ -1839,6 +1867,13 @@ impl Clone for Values<'_, K, V> { #[stable(feature = "default_iters", since = "CURRENT_RUSTC_VERSION")] impl Default for Values<'_, K, V> { + /// Creates an empty `btree_map::Values`. + /// + /// ``` + /// # use std::collections::btree_map; + /// let iter: btree_map::Values<'_, u8, u8> = Default::default(); + /// assert_eq!(iter.len(), 0); + /// ``` fn default() -> Self { Values { inner: Default::default() } } @@ -1982,6 +2017,13 @@ impl<'a, K, V> Iterator for Range<'a, K, V> { #[stable(feature = "default_iters", since = "CURRENT_RUSTC_VERSION")] impl Default for Range<'_, K, V> { + /// Creates an empty `btree_map::Range`. + /// + /// ``` + /// # use std::collections::btree_map; + /// let iter: btree_map::Range<'_, u8, u8> = Default::default(); + /// assert_eq!(iter.count(), 0); + /// ``` fn default() -> Self { Range { inner: Default::default() } } @@ -2065,6 +2107,13 @@ impl FusedIterator for IntoKeys {} #[stable(feature = "default_iters", since = "CURRENT_RUSTC_VERSION")] impl Default for IntoKeys { + /// Creates an empty `btree_map::IntoKeys`. + /// + /// ``` + /// # use std::collections::btree_map; + /// let iter: btree_map::IntoKeys = Default::default(); + /// assert_eq!(iter.len(), 0); + /// ``` fn default() -> Self { IntoKeys { inner: Default::default() } } @@ -2106,6 +2155,13 @@ impl FusedIterator for IntoValues {} #[stable(feature = "default_iters", since = "CURRENT_RUSTC_VERSION")] impl Default for IntoValues { + /// Creates an empty `btree_map::IntoValues`. + /// + /// ``` + /// # use std::collections::btree_map; + /// let iter: btree_map::IntoValues = Default::default(); + /// assert_eq!(iter.len(), 0); + /// ``` fn default() -> Self { IntoValues { inner: Default::default() } } diff --git a/library/alloc/src/collections/btree/map/tests.rs b/library/alloc/src/collections/btree/map/tests.rs index 4d011195936..76c2f27b466 100644 --- a/library/alloc/src/collections/btree/map/tests.rs +++ b/library/alloc/src/collections/btree/map/tests.rs @@ -563,22 +563,6 @@ fn test_iter_min_max() { a.check(); } -#[test] -fn test_iters_default() { - let iter: Keys<'_, u8, u8> = Keys::default(); - assert_eq!(iter.len(), 0); - let iter: Values<'_, u8, u8> = Values::default(); - assert_eq!(iter.len(), 0); - let iter: Range<'_, u8, u8> = Range::default(); - assert_eq!(iter.count(), 0); - let iter: IntoIter = IntoIter::default(); - assert_eq!(iter.len(), 0); - let iter: IntoKeys = IntoKeys::default(); - assert_eq!(iter.len(), 0); - let iter: IntoValues = IntoValues::default(); - assert_eq!(iter.len(), 0); -} - fn range_keys(map: &BTreeMap, range: impl RangeBounds) -> Vec { Vec::from_iter(map.range(range).map(|(&k, &v)| { assert_eq!(k, v); diff --git a/library/alloc/src/collections/btree/set.rs b/library/alloc/src/collections/btree/set.rs index 897499db429..5992b814bba 100644 --- a/library/alloc/src/collections/btree/set.rs +++ b/library/alloc/src/collections/btree/set.rs @@ -1547,6 +1547,13 @@ impl Iterator for IntoIter { #[stable(feature = "default_iters", since = "CURRENT_RUSTC_VERSION")] impl Default for Iter<'_, T> { + /// Creates an empty `btree_set::Iter`. + /// + /// ``` + /// # use std::collections::btree_set; + /// let iter: btree_set::Iter<'_, u8> = Default::default(); + /// assert_eq!(iter.len(), 0); + /// ``` fn default() -> Self { Iter { iter: Default::default() } } @@ -1570,6 +1577,13 @@ impl FusedIterator for IntoIter {} #[stable(feature = "default_iters", since = "CURRENT_RUSTC_VERSION")] impl Default for IntoIter { + /// Creates an empty `btree_set::IntoIter`. + /// + /// ``` + /// # use std::collections::btree_set; + /// let iter: btree_set::IntoIter = Default::default(); + /// assert_eq!(iter.len(), 0); + /// ``` fn default() -> Self { IntoIter { iter: Default::default() } } @@ -1615,6 +1629,13 @@ impl FusedIterator for Range<'_, T> {} #[stable(feature = "default_iters", since = "CURRENT_RUSTC_VERSION")] impl Default for Range<'_, T> { + /// Creates an empty `btree_set::Range`. + /// + /// ``` + /// # use std::collections::btree_set; + /// let iter: btree_set::Range<'_, u8> = Default::default(); + /// assert_eq!(iter.count(), 0); + /// ``` fn default() -> Self { Range { iter: Default::default() } } diff --git a/library/alloc/src/collections/linked_list.rs b/library/alloc/src/collections/linked_list.rs index dae7fc48b1f..080a4a14eda 100644 --- a/library/alloc/src/collections/linked_list.rs +++ b/library/alloc/src/collections/linked_list.rs @@ -1077,6 +1077,13 @@ impl FusedIterator for Iter<'_, T> {} #[stable(feature = "default_iters", since = "CURRENT_RUSTC_VERSION")] impl Default for Iter<'_, T> { + /// Creates an empty `linked_list::Iter`. + /// + /// ``` + /// # use std::collections::linked_list; + /// let iter: linked_list::Iter<'_, u8> = Default::default(); + /// assert_eq!(iter.len(), 0); + /// ``` fn default() -> Self { Iter { head: None, tail: None, len: 0, marker: Default::default() } } @@ -1824,6 +1831,13 @@ impl FusedIterator for IntoIter {} #[stable(feature = "default_iters", since = "CURRENT_RUSTC_VERSION")] impl Default for IntoIter { + /// Creates an empty `linked_list::IntoIter`. + /// + /// ``` + /// # use std::collections::linked_list; + /// let iter: linked_list::IntoIter = Default::default(); + /// assert_eq!(iter.len(), 0); + /// ``` fn default() -> Self { LinkedList::new().into_iter() } diff --git a/library/alloc/src/collections/linked_list/tests.rs b/library/alloc/src/collections/linked_list/tests.rs index 075c68f7241..04594d55b6a 100644 --- a/library/alloc/src/collections/linked_list/tests.rs +++ b/library/alloc/src/collections/linked_list/tests.rs @@ -172,12 +172,6 @@ fn test_iterator() { assert_eq!(it.next(), None); } -#[test] -fn test_default() { - let iter: IntoIter = Default::default(); - assert_eq!(iter.len(), 0); -} - #[test] fn test_iterator_clone() { let mut n = LinkedList::new(); diff --git a/library/alloc/src/vec/into_iter.rs b/library/alloc/src/vec/into_iter.rs index 2be484c3dd4..8fed4a584a3 100644 --- a/library/alloc/src/vec/into_iter.rs +++ b/library/alloc/src/vec/into_iter.rs @@ -349,6 +349,14 @@ unsafe impl TrustedLen for IntoIter {} #[stable(feature = "default_iters", since = "CURRENT_RUSTC_VERSION")] impl Default for IntoIter { + /// Creates an empty `vec::IntoIter`. + /// + /// ``` + /// # use std::vec; + /// let iter: vec::IntoIter = Default::default(); + /// assert_eq!(iter.len(), 0); + /// assert_eq!(iter.as_slice(), &[]); + /// ``` fn default() -> Self { super::Vec::new().into_iter() } diff --git a/library/alloc/tests/vec.rs b/library/alloc/tests/vec.rs index 782b150681c..2f07c2911a5 100644 --- a/library/alloc/tests/vec.rs +++ b/library/alloc/tests/vec.rs @@ -1,6 +1,5 @@ use core::alloc::{Allocator, Layout}; -use core::assert_eq; -use core::iter::{ExactSizeIterator, IntoIterator}; +use core::iter::IntoIterator; use core::ptr::NonNull; use std::alloc::System; use std::assert_matches::assert_matches; @@ -1036,13 +1035,6 @@ fn test_into_iter_clone() { assert_eq!(it.next(), None); } -#[test] -fn test_into_iter_default() { - let iter: IntoIter = Default::default(); - assert_eq!(iter.len(), 0); - assert_eq!(iter.as_slice(), &[]); -} - #[test] fn test_into_iter_leak() { static mut DROPS: i32 = 0; diff --git a/library/core/src/iter/adapters/chain.rs b/library/core/src/iter/adapters/chain.rs index 21fc3bc6f6f..0f5e3718408 100644 --- a/library/core/src/iter/adapters/chain.rs +++ b/library/core/src/iter/adapters/chain.rs @@ -288,6 +288,21 @@ where A: Iterator + Default, B: Iterator + Default, { + /// Creates a `Chain` from the default values for `A` and `B`. + /// + /// ``` + /// # use core::iter::Chain; + /// # use core::slice; + /// # use std::collections::{btree_set, BTreeSet}; + /// # use std::mem; + /// struct Foo<'a>(Chain, btree_set::Iter<'a, u8>>); + /// + /// let set = BTreeSet::::new(); + /// let slice: &[u8] = &[]; + /// let mut foo = Foo(slice.iter().chain(set.iter())); + /// + /// // take requires `Default` + /// let _: Chain<_, _> = mem::take(&mut foo.0); fn default() -> Self { Chain::new(Default::default(), Default::default()) } diff --git a/library/core/src/iter/adapters/cloned.rs b/library/core/src/iter/adapters/cloned.rs index d22a6e721f5..b9e2700860c 100644 --- a/library/core/src/iter/adapters/cloned.rs +++ b/library/core/src/iter/adapters/cloned.rs @@ -160,6 +160,13 @@ where I: Default + Iterator, T: Clone, { + /// Creates a `Cloned` iterator from the default value of `I` + /// ``` + /// # use core::slice; + /// # use core::iter::Cloned; + /// let iter: Cloned> = Default::default(); + /// assert_eq!(iter.len(), 0); + /// ``` fn default() -> Self { Self::new(Default::default()) } diff --git a/library/core/src/iter/adapters/copied.rs b/library/core/src/iter/adapters/copied.rs index d5e579834ee..0aa466e37a2 100644 --- a/library/core/src/iter/adapters/copied.rs +++ b/library/core/src/iter/adapters/copied.rs @@ -247,6 +247,13 @@ where I: Default + Iterator, T: Copy, { + /// Creates a `Copied` iterator from the default value of `I` + /// ``` + /// # use core::slice; + /// # use core::iter::Copied; + /// let iter: Copied> = Default::default(); + /// assert_eq!(iter.len(), 0); + /// ``` fn default() -> Self { Self::new(Default::default()) } diff --git a/library/core/src/iter/adapters/enumerate.rs b/library/core/src/iter/adapters/enumerate.rs index 0b44139a83b..5b0025cb984 100644 --- a/library/core/src/iter/adapters/enumerate.rs +++ b/library/core/src/iter/adapters/enumerate.rs @@ -270,6 +270,13 @@ impl Default for Enumerate where I: Iterator + Default, { + /// Creates an `Enumerate` iterator from the default value of `I` + /// ``` + /// # use core::slice; + /// # use std::iter::Enumerate; + /// let iter: Enumerate> = Default::default(); + /// assert_eq!(iter.len(), 0); + /// ``` fn default() -> Self { Enumerate::new(Default::default()) } diff --git a/library/core/src/iter/adapters/flatten.rs b/library/core/src/iter/adapters/flatten.rs index c0a347a7c1d..cb68c807bf5 100644 --- a/library/core/src/iter/adapters/flatten.rs +++ b/library/core/src/iter/adapters/flatten.rs @@ -308,6 +308,14 @@ where I: Iterator + Default, ::Item: IntoIterator, { + /// Creates a `Flatten` iterator from the default value of `I`. + /// + /// ``` + /// # use core::slice; + /// # use std::iter::Flatten; + /// let iter: Flatten> = Default::default(); + /// assert_eq!(iter.count(), 0); + /// ``` fn default() -> Self { Flatten::new(Default::default()) } diff --git a/library/core/src/iter/adapters/fuse.rs b/library/core/src/iter/adapters/fuse.rs index 87275fa3951..de91c188eeb 100644 --- a/library/core/src/iter/adapters/fuse.rs +++ b/library/core/src/iter/adapters/fuse.rs @@ -183,6 +183,14 @@ where #[stable(feature = "default_iters", since = "CURRENT_RUSTC_VERSION")] impl Default for Fuse { + /// Creates a `Fuse` iterator from the default value of `I`. + /// + /// ``` + /// # use core::slice; + /// # use std::iter::Fuse; + /// let iter: Fuse> = Default::default(); + /// assert_eq!(iter.len(), 0); + /// ``` fn default() -> Self { Fuse { iter: Default::default() } } diff --git a/library/core/src/iter/adapters/rev.rs b/library/core/src/iter/adapters/rev.rs index 4ad75ec0ea2..0b132e13813 100644 --- a/library/core/src/iter/adapters/rev.rs +++ b/library/core/src/iter/adapters/rev.rs @@ -141,6 +141,13 @@ impl Default for Rev where I: Default + Iterator, { + /// Creates a `Rev` iterator from the default value of `I` + /// ``` + /// # use core::slice; + /// # use core::iter::Rev; + /// let iter: Rev> = Default::default(); + /// assert_eq!(iter.len(), 0); + /// ``` fn default() -> Self { Rev::new(Default::default()) } diff --git a/library/core/src/slice/iter/macros.rs b/library/core/src/slice/iter/macros.rs index 57754182c4e..a800da546b4 100644 --- a/library/core/src/slice/iter/macros.rs +++ b/library/core/src/slice/iter/macros.rs @@ -396,6 +396,13 @@ macro_rules! iterator { #[stable(feature = "default_iters", since = "CURRENT_RUSTC_VERSION")] impl Default for $name<'_, T> { + /// Creates an empty slice iterator. + /// + /// ``` + #[doc = concat!("# use core::slice::", stringify!($name), ";")] + #[doc = concat!("let iter: ", stringify!($name<'_, u8>), " = Default::default();")] + /// assert_eq!(iter.len(), 0); + /// ``` fn default() -> Self { (& $( $mut_ )? []).into_iter() } diff --git a/library/core/tests/slice.rs b/library/core/tests/slice.rs index 294de77a6b0..39559cdbb5e 100644 --- a/library/core/tests/slice.rs +++ b/library/core/tests/slice.rs @@ -1,10 +1,8 @@ use core::cell::Cell; use core::cmp::Ordering; -use core::iter::ExactSizeIterator; use core::mem::MaybeUninit; use core::result::Result::{Err, Ok}; -use core::slice::Iter; -use core::{assert_eq, slice}; +use core::slice; #[test] fn test_position() { @@ -226,12 +224,6 @@ fn test_iterator_count() { assert_eq!(iter2.count(), 3); } -#[test] -fn test_iterator_default() { - let iter: Iter<'_, u8> = Iter::default(); - assert_eq!(iter.len(), 0); -} - #[test] fn test_chunks_count() { let v: &[i32] = &[0, 1, 2, 3, 4, 5];