src/libcore/iter/sources.rs

   1 // Copyright 2013-2016 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 use fmt;
  12 use marker;
  13 use usize;
  14
  15 use super::FusedIterator;
  16
  17 /// An iterator that repeats an element endlessly.
  18 ///
  19 /// This `struct` is created by the [`repeat()`] function. See its documentation for more.
  20 ///
  21 /// [`repeat()`]: fn.repeat.html
  22 #[derive(Clone, Debug)]
  23 #[stable(feature = "rust1", since = "1.0.0")]
  24 pub struct Repeat<A> {
  25     element: A
  26 }
  27
  28 #[stable(feature = "rust1", since = "1.0.0")]
  29 impl<A: Clone> Iterator for Repeat<A> {
  30     type Item = A;
  31
  32     #[inline]
  33     fn next(&mut self) -> Option<A> { Some(self.element.clone()) }
  34     #[inline]
  35     fn size_hint(&self) -> (usize, Option<usize>) { (usize::MAX, None) }
  36 }
  37
  38 #[stable(feature = "rust1", since = "1.0.0")]
  39 impl<A: Clone> DoubleEndedIterator for Repeat<A> {
  40     #[inline]
  41     fn next_back(&mut self) -> Option<A> { Some(self.element.clone()) }
  42 }
  43
  44 #[unstable(feature = "fused", issue = "35602")]
  45 impl<A: Clone> FusedIterator for Repeat<A> {}
  46
  47 /// Creates a new iterator that endlessly repeats a single element.
  48 ///
  49 /// The `repeat()` function repeats a single value over and over and over and
  50 /// over and over and 🔁.
  51 ///
  52 /// Infinite iterators like `repeat()` are often used with adapters like
  53 /// [`take()`], in order to make them finite.
  54 ///
  55 /// [`take()`]: trait.Iterator.html#method.take
  56 ///
  57 /// # Examples
  58 ///
  59 /// Basic usage:
  60 ///
  61 /// ```
  62 /// use std::iter;
  63 ///
  64 /// // the number four 4ever:
  65 /// let mut fours = iter::repeat(4);
  66 ///
  67 /// assert_eq!(Some(4), fours.next());
  68 /// assert_eq!(Some(4), fours.next());
  69 /// assert_eq!(Some(4), fours.next());
  70 /// assert_eq!(Some(4), fours.next());
  71 /// assert_eq!(Some(4), fours.next());
  72 ///
  73 /// // yup, still four
  74 /// assert_eq!(Some(4), fours.next());
  75 /// ```
  76 ///
  77 /// Going finite with [`take()`]:
  78 ///
  79 /// ```
  80 /// use std::iter;
  81 ///
  82 /// // that last example was too many fours. Let's only have four fours.
  83 /// let mut four_fours = iter::repeat(4).take(4);
  84 ///
  85 /// assert_eq!(Some(4), four_fours.next());
  86 /// assert_eq!(Some(4), four_fours.next());
  87 /// assert_eq!(Some(4), four_fours.next());
  88 /// assert_eq!(Some(4), four_fours.next());
  89 ///
  90 /// // ... and now we're done
  91 /// assert_eq!(None, four_fours.next());
  92 /// ```
  93 #[inline]
  94 #[stable(feature = "rust1", since = "1.0.0")]
  95 pub fn repeat<T: Clone>(elt: T) -> Repeat<T> {
  96     Repeat{element: elt}
  97 }
  98
  99 /// An iterator that yields nothing.
 100 ///
 101 /// This `struct` is created by the [`empty()`] function. See its documentation for more.
 102 ///
 103 /// [`empty()`]: fn.empty.html
 104 #[stable(feature = "iter_empty", since = "1.2.0")]
 105 pub struct Empty<T>(marker::PhantomData<T>);
 106
 107 #[stable(feature = "core_impl_debug", since = "1.9.0")]
 108 impl<T> fmt::Debug for Empty<T> {
 109     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 110         f.pad("Empty")
 111     }
 112 }
 113
 114 #[stable(feature = "iter_empty", since = "1.2.0")]
 115 impl<T> Iterator for Empty<T> {
 116     type Item = T;
 117
 118     fn next(&mut self) -> Option<T> {
 119         None
 120     }
 121
 122     fn size_hint(&self) -> (usize, Option<usize>){
 123         (0, Some(0))
 124     }
 125 }
 126
 127 #[stable(feature = "iter_empty", since = "1.2.0")]
 128 impl<T> DoubleEndedIterator for Empty<T> {
 129     fn next_back(&mut self) -> Option<T> {
 130         None
 131     }
 132 }
 133
 134 #[stable(feature = "iter_empty", since = "1.2.0")]
 135 impl<T> ExactSizeIterator for Empty<T> {
 136     fn len(&self) -> usize {
 137         0
 138     }
 139 }
 140
 141 #[unstable(feature = "fused", issue = "35602")]
 142 impl<T> FusedIterator for Empty<T> {}
 143
 144 // not #[derive] because that adds a Clone bound on T,
 145 // which isn't necessary.
 146 #[stable(feature = "iter_empty", since = "1.2.0")]
 147 impl<T> Clone for Empty<T> {
 148     fn clone(&self) -> Empty<T> {
 149         Empty(marker::PhantomData)
 150     }
 151 }
 152
 153 // not #[derive] because that adds a Default bound on T,
 154 // which isn't necessary.
 155 #[stable(feature = "iter_empty", since = "1.2.0")]
 156 impl<T> Default for Empty<T> {
 157     fn default() -> Empty<T> {
 158         Empty(marker::PhantomData)
 159     }
 160 }
 161
 162 /// Creates an iterator that yields nothing.
 163 ///
 164 /// # Examples
 165 ///
 166 /// Basic usage:
 167 ///
 168 /// ```
 169 /// use std::iter;
 170 ///
 171 /// // this could have been an iterator over i32, but alas, it's just not.
 172 /// let mut nope = iter::empty::<i32>();
 173 ///
 174 /// assert_eq!(None, nope.next());
 175 /// ```
 176 #[stable(feature = "iter_empty", since = "1.2.0")]
 177 pub fn empty<T>() -> Empty<T> {
 178     Empty(marker::PhantomData)
 179 }
 180
 181 /// An iterator that yields an element exactly once.
 182 ///
 183 /// This `struct` is created by the [`once()`] function. See its documentation for more.
 184 ///
 185 /// [`once()`]: fn.once.html
 186 #[derive(Clone, Debug)]
 187 #[stable(feature = "iter_once", since = "1.2.0")]
 188 pub struct Once<T> {
 189     inner: ::option::IntoIter<T>
 190 }
 191
 192 #[stable(feature = "iter_once", since = "1.2.0")]
 193 impl<T> Iterator for Once<T> {
 194     type Item = T;
 195
 196     fn next(&mut self) -> Option<T> {
 197         self.inner.next()
 198     }
 199
 200     fn size_hint(&self) -> (usize, Option<usize>) {
 201         self.inner.size_hint()
 202     }
 203 }
 204
 205 #[stable(feature = "iter_once", since = "1.2.0")]
 206 impl<T> DoubleEndedIterator for Once<T> {
 207     fn next_back(&mut self) -> Option<T> {
 208         self.inner.next_back()
 209     }
 210 }
 211
 212 #[stable(feature = "iter_once", since = "1.2.0")]
 213 impl<T> ExactSizeIterator for Once<T> {
 214     fn len(&self) -> usize {
 215         self.inner.len()
 216     }
 217 }
 218
 219 #[unstable(feature = "fused", issue = "35602")]
 220 impl<T> FusedIterator for Once<T> {}
 221
 222 /// Creates an iterator that yields an element exactly once.
 223 ///
 224 /// This is commonly used to adapt a single value into a [`chain()`] of other
 225 /// kinds of iteration. Maybe you have an iterator that covers almost
 226 /// everything, but you need an extra special case. Maybe you have a function
 227 /// which works on iterators, but you only need to process one value.
 228 ///
 229 /// [`chain()`]: trait.Iterator.html#method.chain
 230 ///
 231 /// # Examples
 232 ///
 233 /// Basic usage:
 234 ///
 235 /// ```
 236 /// use std::iter;
 237 ///
 238 /// // one is the loneliest number
 239 /// let mut one = iter::once(1);
 240 ///
 241 /// assert_eq!(Some(1), one.next());
 242 ///
 243 /// // just one, that's all we get
 244 /// assert_eq!(None, one.next());
 245 /// ```
 246 ///
 247 /// Chaining together with another iterator. Let's say that we want to iterate
 248 /// over each file of the `.foo` directory, but also a configuration file,
 249 /// `.foorc`:
 250 ///
 251 /// ```no_run
 252 /// use std::iter;
 253 /// use std::fs;
 254 /// use std::path::PathBuf;
 255 ///
 256 /// let dirs = fs::read_dir(".foo").unwrap();
 257 ///
 258 /// // we need to convert from an iterator of DirEntry-s to an iterator of
 259 /// // PathBufs, so we use map
 260 /// let dirs = dirs.map(|file| file.unwrap().path());
 261 ///
 262 /// // now, our iterator just for our config file
 263 /// let config = iter::once(PathBuf::from(".foorc"));
 264 ///
 265 /// // chain the two iterators together into one big iterator
 266 /// let files = dirs.chain(config);
 267 ///
 268 /// // this will give us all of the files in .foo as well as .foorc
 269 /// for f in files {
 270 ///     println!("{:?}", f);
 271 /// }
 272 /// ```
 273 #[stable(feature = "iter_once", since = "1.2.0")]
 274 pub fn once<T>(value: T) -> Once<T> {
 275     Once { inner: Some(value).into_iter() }
 276 }