library/core/src/iter/sources/empty.rs

   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 pub struct Empty<T>(marker::PhantomData<fn() -> T>);
  31
  32 #[stable(feature = "core_impl_debug", since = "1.9.0")]
  33 impl<T> fmt::Debug for Empty<T> {
  34     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  35         f.debug_struct("Empty").finish()
  36     }
  37 }
  38
  39 #[stable(feature = "iter_empty", since = "1.2.0")]
  40 impl<T> Iterator for Empty<T> {
  41     type Item = T;
  42
  43     fn next(&mut self) -> Option<T> {
  44         None
  45     }
  46
  47     fn size_hint(&self) -> (usize, Option<usize>) {
  48         (0, Some(0))
  49     }
  50 }
  51
  52 #[stable(feature = "iter_empty", since = "1.2.0")]
  53 impl<T> DoubleEndedIterator for Empty<T> {
  54     fn next_back(&mut self) -> Option<T> {
  55         None
  56     }
  57 }
  58
  59 #[stable(feature = "iter_empty", since = "1.2.0")]
  60 impl<T> ExactSizeIterator for Empty<T> {
  61     fn len(&self) -> usize {
  62         0
  63     }
  64 }
  65
  66 #[unstable(feature = "trusted_len", issue = "37572")]
  67 unsafe impl<T> TrustedLen for Empty<T> {}
  68
  69 #[stable(feature = "fused", since = "1.26.0")]
  70 impl<T> FusedIterator for Empty<T> {}
  71
  72 // not #[derive] because that adds a Clone bound on T,
  73 // which isn't necessary.
  74 #[stable(feature = "iter_empty", since = "1.2.0")]
  75 impl<T> Clone for Empty<T> {
  76     fn clone(&self) -> Empty<T> {
  77         Empty(marker::PhantomData)
  78     }
  79 }
  80
  81 // not #[derive] because that adds a Default bound on T,
  82 // which isn't necessary.
  83 #[stable(feature = "iter_empty", since = "1.2.0")]
  84 #[rustc_const_unstable(feature = "const_default_impls", issue = "87864")]
  85 impl<T> const Default for Empty<T> {
  86     fn default() -> Empty<T> {
  87         Empty(marker::PhantomData)
  88     }
  89 }