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 // Newtype for use in `PhantomData` to avoid
  26 // > error: const-stable function cannot use `#[feature(const_fn_fn_ptr_basics)]`
  27 // in `const fn empty<T>()` above.
  28 struct FnReturning<T>(fn() -> T);
  29
  30 /// An iterator that yields nothing.
  31 ///
  32 /// This `struct` is created by the [`empty()`] function. See its documentation for more.
  33 #[must_use = "iterators are lazy and do nothing unless consumed"]
  34 #[stable(feature = "iter_empty", since = "1.2.0")]
  35 pub struct Empty<T>(marker::PhantomData<FnReturning<T>>);
  36
  37 #[stable(feature = "core_impl_debug", since = "1.9.0")]
  38 impl<T> fmt::Debug for Empty<T> {
  39     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  40         f.debug_struct("Empty").finish()
  41     }
  42 }
  43
  44 #[stable(feature = "iter_empty", since = "1.2.0")]
  45 impl<T> Iterator for Empty<T> {
  46     type Item = T;
  47
  48     fn next(&mut self) -> Option<T> {
  49         None
  50     }
  51
  52     fn size_hint(&self) -> (usize, Option<usize>) {
  53         (0, Some(0))
  54     }
  55 }
  56
  57 #[stable(feature = "iter_empty", since = "1.2.0")]
  58 impl<T> DoubleEndedIterator for Empty<T> {
  59     fn next_back(&mut self) -> Option<T> {
  60         None
  61     }
  62 }
  63
  64 #[stable(feature = "iter_empty", since = "1.2.0")]
  65 impl<T> ExactSizeIterator for Empty<T> {
  66     fn len(&self) -> usize {
  67         0
  68     }
  69 }
  70
  71 #[unstable(feature = "trusted_len", issue = "37572")]
  72 unsafe impl<T> TrustedLen for Empty<T> {}
  73
  74 #[stable(feature = "fused", since = "1.26.0")]
  75 impl<T> FusedIterator for Empty<T> {}
  76
  77 // not #[derive] because that adds a Clone bound on T,
  78 // which isn't necessary.
  79 #[stable(feature = "iter_empty", since = "1.2.0")]
  80 impl<T> Clone for Empty<T> {
  81     fn clone(&self) -> Empty<T> {
  82         Empty(marker::PhantomData)
  83     }
  84 }
  85
  86 // not #[derive] because that adds a Default bound on T,
  87 // which isn't necessary.
  88 #[stable(feature = "iter_empty", since = "1.2.0")]
  89 #[rustc_const_unstable(feature = "const_default_impls", issue = "87864")]
  90 impl<T> const Default for Empty<T> {
  91     fn default() -> Empty<T> {
  92         Empty(marker::PhantomData)
  93     }
  94 }