1 | use crate::fmt; |
2 | use crate::iter::{FusedIterator, TrustedLen}; |
3 | use crate::marker; |
4 | |
5 | /// Creates an iterator that yields nothing. |
6 | /// |
7 | /// # Examples |
8 | /// |
9 | /// Basic usage: |
10 | /// |
11 | /// ``` |
12 | /// use std::iter; |
13 | /// |
14 | /// // this could have been an iterator over i32, but alas, it's just not. |
15 | /// let mut nope = iter::empty::<i32>(); |
16 | /// |
17 | /// assert_eq!(None, nope.next()); |
18 | /// ``` |
19 | #[stable (feature = "iter_empty" , since = "1.2.0" )] |
20 | #[rustc_const_stable (feature = "const_iter_empty" , since = "1.32.0" )] |
21 | pub const fn empty<T>() -> Empty<T> { |
22 | Empty(marker::PhantomData) |
23 | } |
24 | |
25 | /// An iterator that yields nothing. |
26 | /// |
27 | /// This `struct` is created by the [`empty()`] function. See its documentation for more. |
28 | #[must_use = "iterators are lazy and do nothing unless consumed" ] |
29 | #[stable (feature = "iter_empty" , since = "1.2.0" )] |
30 | #[rustc_diagnostic_item = "IterEmpty" ] |
31 | pub struct Empty<T>(marker::PhantomData<fn() -> T>); |
32 | |
33 | #[stable (feature = "core_impl_debug" , since = "1.9.0" )] |
34 | impl<T> fmt::Debug for Empty<T> { |
35 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
36 | f.debug_struct(name:"Empty" ).finish() |
37 | } |
38 | } |
39 | |
40 | #[stable (feature = "iter_empty" , since = "1.2.0" )] |
41 | impl<T> Iterator for Empty<T> { |
42 | type Item = T; |
43 | |
44 | fn next(&mut self) -> Option<T> { |
45 | None |
46 | } |
47 | |
48 | fn size_hint(&self) -> (usize, Option<usize>) { |
49 | (0, Some(0)) |
50 | } |
51 | } |
52 | |
53 | #[stable (feature = "iter_empty" , since = "1.2.0" )] |
54 | impl<T> DoubleEndedIterator for Empty<T> { |
55 | fn next_back(&mut self) -> Option<T> { |
56 | None |
57 | } |
58 | } |
59 | |
60 | #[stable (feature = "iter_empty" , since = "1.2.0" )] |
61 | impl<T> ExactSizeIterator for Empty<T> { |
62 | fn len(&self) -> usize { |
63 | 0 |
64 | } |
65 | } |
66 | |
67 | #[unstable (feature = "trusted_len" , issue = "37572" )] |
68 | unsafe impl<T> TrustedLen for Empty<T> {} |
69 | |
70 | #[stable (feature = "fused" , since = "1.26.0" )] |
71 | impl<T> FusedIterator for Empty<T> {} |
72 | |
73 | // not #[derive] because that adds a Clone bound on T, |
74 | // which isn't necessary. |
75 | #[stable (feature = "iter_empty" , since = "1.2.0" )] |
76 | impl<T> Clone for Empty<T> { |
77 | fn clone(&self) -> Empty<T> { |
78 | Empty(marker::PhantomData) |
79 | } |
80 | } |
81 | |
82 | // not #[derive] because that adds a Default bound on T, |
83 | // which isn't necessary. |
84 | #[stable (feature = "iter_empty" , since = "1.2.0" )] |
85 | impl<T> Default for Empty<T> { |
86 | fn default() -> Empty<T> { |
87 | Empty(marker::PhantomData) |
88 | } |
89 | } |
90 | |