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