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
100
101
102
103
104
105
106
107
108
109

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

/// 创建一个迭代器，该迭代器通过调用提供的闭包来懒惰地一次生成一个值。
///
/// 这通常用于使单个值生成器适应其他类型的迭代的 [`chain()`]。
/// 也许您有一个涵盖几乎所有内容的迭代器，但是您需要一个额外的特殊情况。
/// 也许您有一个可在迭代器上使用的函数，但只需要处理一个值即可。
///
/// 与 [`once()`] 不同，此函数将根据要求延迟生成值。
///
/// [`chain()`]: Iterator::chain
/// [`once()`]: crate::iter::once
///
/// # Examples
///
/// 基本用法:
///
/// ```
/// use std::iter;
///
/// // 一个是最孤独的数字
/// let mut one = iter::once_with(|| 1);
///
/// assert_eq!(Some(1), one.next());
///
/// // 只是一个，这就是我们得到的
/// assert_eq!(None, one.next());
/// ```
///
/// 与另一个迭代器链接在一起。
/// 假设我们要遍历 `.foo` 目录的每个文件，还要遍历一个配置文件，
///
/// `.foorc`:
///
/// ```no_run
/// use std::iter;
/// use std::fs;
/// use std::path::PathBuf;
///
/// let dirs = fs::read_dir(".foo").unwrap();
///
/// // 我们需要将 DirEntry-s 的迭代器转换为 PathBufs 的迭代器，因此我们使用 map
/////
/// let dirs = dirs.map(|file| file.unwrap().path());
///
/// // 现在，我们的迭代器仅用于我们的配置文件
/// let config = iter::once_with(|| PathBuf::from(".foorc"));
///
/// // 将两个迭代器链接到一个大迭代器中
/// let files = dirs.chain(config);
///
/// // 这将为我们提供 .foo 和 .foorc 中的所有文件
/// for f in files {
///     println!("{:?}", f);
/// }
/// ```
///
#[inline]
#[stable(feature = "iter_once_with", since = "1.43.0")]
pub fn once_with<A, F: FnOnce() -> A>(gen: F) -> OnceWith<F> {
    OnceWith { gen: Some(gen) }
}

/// 通过应用提供的闭包 `F: FnOnce() -> A` 产生类型为 `A` 的单个元素的迭代器。
///
///
/// 该 `struct` 由 [`once_with()`] 函数创建。
/// 有关更多信息，请参见其文档。
#[derive(Clone, Debug)]
#[stable(feature = "iter_once_with", since = "1.43.0")]
pub struct OnceWith<F> {
    gen: Option<F>,
}

#[stable(feature = "iter_once_with", since = "1.43.0")]
impl<A, F: FnOnce() -> A> Iterator for OnceWith<F> {
    type Item = A;

    #[inline]
    fn next(&mut self) -> Option<A> {
        let f = self.gen.take()?;
        Some(f())
    }

    #[inline]
    fn size_hint(&self) -> (usize, Option<usize>) {
        self.gen.iter().size_hint()
    }
}

#[stable(feature = "iter_once_with", since = "1.43.0")]
impl<A, F: FnOnce() -> A> DoubleEndedIterator for OnceWith<F> {
    fn next_back(&mut self) -> Option<A> {
        self.next()
    }
}

#[stable(feature = "iter_once_with", since = "1.43.0")]
impl<A, F: FnOnce() -> A> ExactSizeIterator for OnceWith<F> {
    fn len(&self) -> usize {
        self.gen.iter().len()
    }
}

#[stable(feature = "iter_once_with", since = "1.43.0")]
impl<A, F: FnOnce() -> A> FusedIterator for OnceWith<F> {}

#[stable(feature = "iter_once_with", since = "1.43.0")]
unsafe impl<A, F: FnOnce() -> A> TrustedLen for OnceWith<F> {}