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

具有 successorpredecessor 操作概念的对象。

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

Required Methods§

source

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

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

返回从 startend 所需的 successor 步骤的数量。

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

Invariants

对于任何 abn

  • 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 countsuccessor 而获得的值。

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

Invariants

对于任何 anm

  • 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 不会溢出的任何 anm

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

对于任何 an

  • 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

对于任何 anm

  • 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)?) }

对于任何 an

  • 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 countsuccessor 而获得的值。

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

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

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

Invariants

对于任何 anm,都不会发生溢出:

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

对于任何 an,都不会发生溢出:

  • 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 countsuccessor 而获得的值。

Safety

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

Invariants

对于任何 a

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

对于任何 an,都不会发生溢出:

  • 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

对于任何 anm,都不会发生溢出:

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

对于任何 an,都不会发生溢出:

  • 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 支持的值范围是不确定的行为。 如果不能保证不会溢出,请改用 backwardbackward_checked

Invariants

对于任何 a

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

对于任何 an,都不会发生溢出:

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

Implementors§