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};
/// 创建一个迭代器,该迭代器只生成一次元素。
///
/// 这通常用于将单个值适配到其他类型的迭代的 [`chain()`] 中。
/// 也许您有一个涵盖几乎所有内容的迭代器,但是您需要一个额外的特殊情况。
/// 也许您有一个可在迭代器上使用的函数,但只需要处理一个值即可。
///
/// [`chain()`]: Iterator::chain
///
/// # Examples
///
/// 基本用法:
///
/// ```
/// use std::iter;
///
/// // 一个是最孤独的数字
/// let mut one = iter::once(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(PathBuf::from(".foorc"));
///
/// // 将两个迭代器链接到一个大迭代器中
/// let files = dirs.chain(config);
///
/// // 这将为我们提供 .foo 和 .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() }
}
/// 一个仅产生一次元素的迭代器。
///
/// 该 `struct` 由 [`once()`] 函数创建。有关更多信息,请参见其文档。
#[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> {}