use crate::iter::Step;

/// 一个迭代器，用完后总是继续产生 `None`。
///
/// 确保一次返回 `None` 的融合迭代器上的 next 调用保证再次返回 [`None`]。
/// 该 trait 应该由以此方式运行的所有迭代器实现，因为它允许优化 [`Iterator::fuse()`]。
///
///
/// Note: 通常，如果需要融合的迭代器，则不应在泛型范围内使用 `FusedIterator`。
/// 相反，您应该只在迭代器上调用 [`Iterator::fuse()`]。
/// 如果迭代器已经融合，则额外的 [`Fuse`] 包装器将是无操作的，并且不会降低性能。
///
/// [`Fuse`]: crate::iter::Fuse
///
#[stable(feature = "fused", since = "1.26.0")]
#[rustc_unsafe_specialization_marker]
pub trait FusedIterator: Iterator {}

#[stable(feature = "fused", since = "1.26.0")]
impl<I: FusedIterator + ?Sized> FusedIterator for &mut I {}

/// 一个使用 size_hint 报告准确长度的迭代器。
///
/// 迭代器报告一个大小提示，该提示要么是精确的 (下限等于上限)，要么上限是 [`None`]。
/// 如果实际的迭代器长度大于 [`usize::MAX`]，则上限必须仅为 [`None`]。在这种情况下，下限必须是 [`usize::MAX`]，导致 `(usize::MAX, None)` 的 [`Iterator::size_hint()`]。
///
/// 迭代器必须精确地生成它所报告或发散的元素数量，然后才能结束。
///
/// # 什么时候*不应该*适配器是 `TrustedLen`?
///
/// 如果适配器使迭代器*短*给定数量，那么该适配器实现 `TrustedLen` 通常是不正确的。
/// 内部迭代器返回的可能多于 `usize::MAX` 项，但没有办法知道 `k` 小于该项的元素是多少，因为来自内部迭代器的 `size_hint` 已经饱和并丢失了该信息。
///
///
/// 这就是 [`Skip<I>`](crate::iter::Skip) 不是 `TrustedLen` 的原因，即使 `I` 实现了 `TrustedLen`。
///
/// # Safety
///
/// 只有在遵守契约的情况下才能实现 trait。这个 trait 的使用者必须检查 [`Iterator::size_hint () `] 的上限。
///
///
///
///
///
///
///
///
///
#[unstable(feature = "trusted_len", issue = "37572")]
#[rustc_unsafe_specialization_marker]
pub unsafe trait TrustedLen: Iterator {}

#[unstable(feature = "trusted_len", issue = "37572")]
unsafe impl<I: TrustedLen + ?Sized> TrustedLen for &mut I {}

/// 一个迭代器，当产生一个项时，它会从它的底层 [`SourceIter`] 中获取至少一个元素。
///
/// 调用任何推进迭代器的方法，例如
/// [`next()`] 或 [`try_fold()`]，保证对于每一步，迭代器的底层源的至少一个值已被移出，并且迭代器链的结果可以插入到它的位置，假设源的结构约束允许这样的插入。
///
/// 换句话说，此 trait 表示可以在适当位置收集迭代器管道。
///
/// 这个 trait 的主要用途是就地迭代。有关详细信息，请参见 [`vec::in_place_collect`] 模块文档。
///
/// [`vec::in_place_collect`]: ../../../../alloc/vec/in_place_collect/index.html
/// [`SourceIter`]: crate::iter::SourceIter
/// [`next()`]: Iterator::next
/// [`try_fold()`]: Iterator::try_fold
///
///
///
#[unstable(issue = "none", feature = "inplace_iteration")]
#[doc(hidden)]
pub unsafe trait InPlaceIterable: Iterator {}

/// 一种支持 [`Step`] 的所有不变量的类型。
///
/// [`Step::steps_between()`] 的不变量是 [`TrustedLen`] 的不变量的超集。
/// 因此，对于具有相同泛型参数的所有范围类型，都实现了 [`TrustedLen`]。
///
/// # Safety
///
/// 给定类型的 [`Step`] 的实现必须保证所有方法的所有不变量都得到支持。
/// 有关详细信息，请参见 [`Step`] trait 的文档。
/// 消费者可以自由地依赖不安全代码中的不变量。
///
#[unstable(feature = "trusted_step", issue = "85731")]
#[rustc_specialization_trait]
pub unsafe trait TrustedStep: Step {}