Trait core::iter::Step

source · 
pub trait Step: Clone + PartialOrd + Sized {
    // Required methods
    fn steps_between(start: &Self, end: &Self) -> Option<usize>;
    fn forward_checked(start: Self, count: usize) -> Option<Self>;
    fn backward_checked(start: Self, count: usize) -> Option<Self>;

    // Provided methods
    fn forward(start: Self, count: usize) -> Self { ... }
    unsafe fn forward_unchecked(start: Self, count: usize) -> Self { ... }
    fn backward(start: Self, count: usize) -> Self { ... }
    unsafe fn backward_unchecked(start: Self, count: usize) -> Self { ... }
}
🔬This is a nightly-only experimental API. (step_trait #42168)
Expand description

具有 successor 和 predecessor 操作概念的对象。

successor 操作朝着比较大的值移动。 predecessor 运算将移向比较较小的值。

Required Methods§

source

fn steps_between(start: &Self, end: &Self) -> Option<usize>

🔬This is a nightly-only experimental API. (step_trait #42168)

返回从 start 到 end 所需的 successor 步骤的数量。

如果步数溢出 usize (或者是无限的，或者永远不会达到 end)，则返回 None。

Invariants

对于任何 a，b 和 n：

  • steps_between(&a, &b) == Some(n) 当且仅当 Step::forward_checked(&a, n) == Some(b)
  • steps_between(&a, &b) == Some(n) 当且仅当 Step::backward_checked(&b, n) == Some(a)
  • steps_between(&a, &b) == Some(n) only if a <= b
    • 推论: steps_between(&a, &b) == Some(0) 当且仅当 a == b
    • 请注意，a <= b 确实不表示 steps_between(&a, &b) != None。 当需要多个 usize::MAX 步骤才能到达 b 时，就是这种情况
  • steps_between(&a, &b) == None if a > b
source

fn forward_checked(start: Self, count: usize) -> Option<Self>

🔬This is a nightly-only experimental API. (step_trait #42168)

返回通过将 self count 的 successor 而获得的值。

如果这会溢出 Self 支持的值范围，则返回 None。

Invariants

对于任何 a，n 和 m：

  • Step::forward_checked(a, n).and_then(|x| Step::forward_checked(x, m)) == Step::forward_checked(a, m).and_then(|x| Step::forward_checked(x, n))

对于 n + m 不会溢出的任何 a，n 和 m：

  • Step::forward_checked(a, n).and_then(|x| Step::forward_checked(x, m)) == Step::forward_checked(a, n + m)

对于任何 a 和 n：

  • Step::forward_checked(a, n) == (0..n).try_fold(a, |x, _| Step::forward_checked(&x, 1))
    • 推论: Step::forward_checked(&a, 0) == Some(a)
source

fn backward_checked(start: Self, count: usize) -> Option<Self>

🔬This is a nightly-only experimental API. (step_trait #42168)

返回通过获取 self count 次的 predecessor 而获得的值。

如果这会溢出 Self 支持的值范围，则返回 None。

Invariants

对于任何 a，n 和 m：

  • Step::backward_checked(a, n).and_then(|x| Step::backward_checked(x, m)) == n.checked_add(m).and_then(|x| Step::backward_checked(a, x))

  • Step::backward_checked(a, n).and_then(|x| Step::backward_checked(x, m)) == try { Step::backward_checked(a, n.checked_add(m)?) }

对于任何 a 和 n：

  • Step::backward_checked(a, n) == (0..n).try_fold(a, |x, _| Step::backward_checked(&x, 1))
    • 推论: Step::backward_checked(&a, 0) == Some(a)

Provided Methods§

source

fn forward(start: Self, count: usize) -> Self

🔬This is a nightly-only experimental API. (step_trait #42168)

返回通过将 self count 的 successor 而获得的值。

如果这会使 Self 支持的值范围溢出，则可以将此函数设置为 panic，自动换行或饱和。

启用调试断言后，建议的行为是 panic，否则将自动换行或饱和。

不安全的代码不应依赖溢出后行为的正确性。

Invariants

对于任何 a，n 和 m，都不会发生溢出：

  • Step::forward(Step::forward(a, n), m) == Step::forward(a, n + m)

对于任何 a 和 n，都不会发生溢出：

  • Step::forward_checked(a, n) == Some(Step::forward(a, n))
  • Step::forward(a, n) == (0..n).fold(a, |x, _| Step::forward(x, 1))
    • 推论: Step::forward(a, 0) == a
  • Step::forward(a, n) >= a
  • Step::backward(Step::forward(a, n), n) == a
source

unsafe fn forward_unchecked(start: Self, count: usize) -> Self

🔬This is a nightly-only experimental API. (step_trait #42168)

返回通过将 self count 的 successor 而获得的值。

Safety

该操作溢出 Self 支持的值范围是不确定的行为。 如果不能保证不会溢出，请改用 forward 或 forward_checked。

Invariants

对于任何 a：

  • 如果存在 b 这样的 b > a，则调用 Step::forward_unchecked(a, 1) 是安全的
  • 如果存在 b，n (例如 steps_between(&a, &b) == Some(n))，则对于任何 m <= n 都可以调用 Step::forward_unchecked(a, m)。

对于任何 a 和 n，都不会发生溢出：

  • Step::forward_unchecked(a, n) 相当于 Step::forward(a, n)
source

fn backward(start: Self, count: usize) -> Self

🔬This is a nightly-only experimental API. (step_trait #42168)

返回通过获取 self count 次的 predecessor 而获得的值。

如果这会使 Self 支持的值范围溢出，则可以将此函数设置为 panic，自动换行或饱和。

启用调试断言后，建议的行为是 panic，否则将自动换行或饱和。

不安全的代码不应依赖溢出后行为的正确性。

Invariants

对于任何 a，n 和 m，都不会发生溢出：

  • Step::backward(Step::backward(a, n), m) == Step::backward(a, n + m)

对于任何 a 和 n，都不会发生溢出：

  • Step::backward_checked(a, n) == Some(Step::backward(a, n))
  • Step::backward(a, n) == (0..n).fold(a, |x, _| Step::backward(x, 1))
    • 推论: Step::backward(a, 0) == a
  • Step::backward(a, n) <= a
  • Step::forward(Step::backward(a, n), n) == a
source

unsafe fn backward_unchecked(start: Self, count: usize) -> Self

🔬This is a nightly-only experimental API. (step_trait #42168)

返回通过获取 self count 次的 predecessor 而获得的值。

Safety

该操作溢出 Self 支持的值范围是不确定的行为。 如果不能保证不会溢出，请改用 backward 或 backward_checked。

Invariants

对于任何 a：

  • 如果存在 b 这样的 b < a，则调用 Step::backward_unchecked(a, 1) 是安全的
  • 如果存在 b，n (例如 steps_between(&b, &a) == Some(n))，则对于任何 m <= n 都可以调用 Step::backward_unchecked(a, m)。

对于任何 a 和 n，都不会发生溢出：

  • Step::backward_unchecked(a, n) 相当于 Step::backward(a, n)

Implementors§