     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99

    use crate::iter::{FusedIterator, TrustedLen};

    /// Creates an iterator that yields an element exactly once.
    ///
    /// This is commonly used to adapt a single value into a [`chain()`] of other
    /// kinds of iteration. Maybe you have an iterator that covers almost
    /// everything, but you need an extra special case. Maybe you have a function
    /// which works on iterators, but you only need to process one value.
    ///
    /// [`chain()`]: Iterator::chain
    ///
    /// # Examples
    ///
    /// Basic usage:
    ///
    /// ```
    /// use std::iter;
    ///
    /// // one is the loneliest number
    /// let mut one = iter::once(1);
    ///
    /// assert_eq!(Some(1), one.next());
    ///
    /// // just one, that's all we get
    /// assert_eq!(None, one.next());
    /// ```
    ///
    /// Chaining together with another iterator. Let's say that we want to iterate
    /// over each file of the `.foo` directory, but also a configuration file,
    /// `.foorc`:
    ///
    /// ```no_run
    /// use std::iter;
    /// use std::fs;
    /// use std::path::PathBuf;
    ///
    /// let dirs = fs::read_dir(".foo").unwrap();
    ///
    /// // we need to convert from an iterator of DirEntry-s to an iterator of
    /// // PathBufs, so we use map
    /// let dirs = dirs.map(|file| file.unwrap().path());
    ///
    /// // now, our iterator just for our config file
    /// let config = iter::once(PathBuf::from(".foorc"));
    ///
    /// // chain the two iterators together into one big iterator
    /// let files = dirs.chain(config);
    ///
    /// // this will give us all of the files in .foo as well as .foorc
    /// for f in files {
    ///     println!("{:?}", f);
    /// }
    /// ```
    #[stable(feature = "iter_once", since = "1.2.0")]
    pub fn once<T>(value: T) -> Once<T> {
        Once { inner: Some(value).into_iter() }
    }

    /// An iterator that yields an element exactly once.
    ///
    /// This `struct` is created by the [`once()`] function. See its documentation for more.
    #[derive(Clone, Debug)]
    #[stable(feature = "iter_once", since = "1.2.0")]
    pub struct Once<T> {
        inner: crate::option::IntoIter<T>,
    }

    #[stable(feature = "iter_once", since = "1.2.0")]
    impl<T> Iterator for Once<T> {
        type Item = T;

        fn next(&mut self) -> Option<T> {
            self.inner.next()
        }

        fn size_hint(&self) -> (usize, Option<usize>) {
            self.inner.size_hint()
        }
    }

    #[stable(feature = "iter_once", since = "1.2.0")]
    impl<T> DoubleEndedIterator for Once<T> {
        fn next_back(&mut self) -> Option<T> {
            self.inner.next_back()
        }
    }

    #[stable(feature = "iter_once", since = "1.2.0")]
    impl<T> ExactSizeIterator for Once<T> {
        fn len(&self) -> usize {
            self.inner.len()
        }
    }

    #[unstable(feature = "trusted_len", issue = "37572")]
    unsafe impl<T> TrustedLen for Once<T> {}

    #[stable(feature = "fused", since = "1.26.0")]
    impl<T> FusedIterator for Once<T> {}