Trait sp_std::iter::Step

pub trait Step: Clone + PartialOrd<Self> {
    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>;

    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)

recently redesigned

Objects that have a notion of successor and predecessor operations.

The successor operation moves towards values that compare greater. The predecessor operation moves towards values that compare lesser.

Required methods

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

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

recently redesigned

Returns the number of successor steps required to get from start to end.

Returns None if the number of steps would overflow usize (or is infinite, or if end would never be reached).

Invariants

For any a, b, and n:

• steps_between(&a, &b) == Some(n) if and only if Step::forward_checked(&a, n) == Some(b)
• steps_between(&a, &b) == Some(n) if and only if Step::backward_checked(&a, n) == Some(a)
• steps_between(&a, &b) == Some(n) only if a <= b
  • Corollary: steps_between(&a, &b) == Some(0) if and only if a == b
  • Note that a <= b does not imply steps_between(&a, &b) != None; this is the case when it would require more than usize::MAX steps to get to b
• steps_between(&a, &b) == None if a > b

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

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

recently redesigned

Returns the value that would be obtained by taking the successor of self count times.

If this would overflow the range of values supported by Self, returns None.

Invariants

For any a, n, and 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))

For any a, n, and m where n + m does not overflow:

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

For any a and n:

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

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

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

recently redesigned

Returns the value that would be obtained by taking the predecessor of self count times.

If this would overflow the range of values supported by Self, returns None.

Invariants

For any a, n, and 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)?) }

For any a and n:

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

Provided methods

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

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

recently redesigned

Returns the value that would be obtained by taking the successor of self count times.

If this would overflow the range of values supported by Self, this function is allowed to panic, wrap, or saturate. The suggested behavior is to panic when debug assertions are enabled, and to wrap or saturate otherwise.

Unsafe code should not rely on the correctness of behavior after overflow.

Invariants

For any a, n, and m, where no overflow occurs:

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

For any a and n, where no overflow occurs:

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

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

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

recently redesigned

Returns the value that would be obtained by taking the successor of self count times.

Safety

It is undefined behavior for this operation to overflow the range of values supported by Self. If you cannot guarantee that this will not overflow, use forward or forward_checked instead.

Invariants

For any a:

• if there exists b such that b > a, it is safe to call Step::forward_unchecked(a, 1)
• if there exists b, n such that steps_between(&a, &b) == Some(n), it is safe to call Step::forward_unchecked(a, m) for any m <= n.

For any a and n, where no overflow occurs:

• Step::forward_unchecked(a, n) is equivalent to Step::forward(a, n)

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

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

recently redesigned

Returns the value that would be obtained by taking the predecessor of self count times.

If this would overflow the range of values supported by Self, this function is allowed to panic, wrap, or saturate. The suggested behavior is to panic when debug assertions are enabled, and to wrap or saturate otherwise.

Unsafe code should not rely on the correctness of behavior after overflow.

Invariants

For any a, n, and m, where no overflow occurs:

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

For any a and n, where no overflow occurs:

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

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

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

recently redesigned

Returns the value that would be obtained by taking the predecessor of self count times.

Safety

It is undefined behavior for this operation to overflow the range of values supported by Self. If you cannot guarantee that this will not overflow, use backward or backward_checked instead.

Invariants

For any a:

• if there exists b such that b < a, it is safe to call Step::backward_unchecked(a, 1)
• if there exists b, n such that steps_between(&b, &a) == Some(n), it is safe to call Step::backward_unchecked(a, m) for any m <= n.

For any a and n, where no overflow occurs:

• Step::backward_unchecked(a, n) is equivalent to Step::backward(a, n)

Implementations on Foreign Types

impl Step for usize

pub unsafe fn forward_unchecked(start: usize, n: usize) -> usize

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

recently redesigned

pub unsafe fn backward_unchecked(start: usize, n: usize) -> usize

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

recently redesigned

pub fn forward(start: usize, n: usize) -> usize

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

recently redesigned

pub fn backward(start: usize, n: usize) -> usize

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

recently redesigned

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

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

recently redesigned

pub fn forward_checked(start: usize, n: usize) -> Option<usize>

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

recently redesigned

pub fn backward_checked(start: usize, n: usize) -> Option<usize>

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

recently redesigned

impl Step for i64

pub unsafe fn forward_unchecked(start: i64, n: usize) -> i64

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

recently redesigned

pub unsafe fn backward_unchecked(start: i64, n: usize) -> i64

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

recently redesigned

pub fn forward(start: i64, n: usize) -> i64

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

recently redesigned

pub fn backward(start: i64, n: usize) -> i64

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

recently redesigned

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

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

recently redesigned

pub fn forward_checked(start: i64, n: usize) -> Option<i64>

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

recently redesigned

pub fn backward_checked(start: i64, n: usize) -> Option<i64>

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

recently redesigned

impl Step for i16

pub unsafe fn forward_unchecked(start: i16, n: usize) -> i16

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

recently redesigned

pub unsafe fn backward_unchecked(start: i16, n: usize) -> i16

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

recently redesigned

pub fn forward(start: i16, n: usize) -> i16

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

recently redesigned

pub fn backward(start: i16, n: usize) -> i16

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

recently redesigned

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

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

recently redesigned

pub fn forward_checked(start: i16, n: usize) -> Option<i16>

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

recently redesigned

pub fn backward_checked(start: i16, n: usize) -> Option<i16>

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

recently redesigned

impl Step for i8

pub unsafe fn forward_unchecked(start: i8, n: usize) -> i8

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

recently redesigned

pub unsafe fn backward_unchecked(start: i8, n: usize) -> i8

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

recently redesigned

pub fn forward(start: i8, n: usize) -> i8

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

recently redesigned

pub fn backward(start: i8, n: usize) -> i8

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

recently redesigned

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

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

recently redesigned

pub fn forward_checked(start: i8, n: usize) -> Option<i8>

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

recently redesigned

pub fn backward_checked(start: i8, n: usize) -> Option<i8>

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

recently redesigned

impl Step for i32

pub unsafe fn forward_unchecked(start: i32, n: usize) -> i32

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

recently redesigned

pub unsafe fn backward_unchecked(start: i32, n: usize) -> i32

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

recently redesigned

pub fn forward(start: i32, n: usize) -> i32

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

recently redesigned

pub fn backward(start: i32, n: usize) -> i32

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

recently redesigned

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

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

recently redesigned

pub fn forward_checked(start: i32, n: usize) -> Option<i32>

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

recently redesigned

pub fn backward_checked(start: i32, n: usize) -> Option<i32>

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

recently redesigned

impl Step for u128

pub unsafe fn forward_unchecked(start: u128, n: usize) -> u128

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

recently redesigned

pub unsafe fn backward_unchecked(start: u128, n: usize) -> u128

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

recently redesigned

pub fn forward(start: u128, n: usize) -> u128

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

recently redesigned

pub fn backward(start: u128, n: usize) -> u128

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

recently redesigned

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

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

recently redesigned

pub fn forward_checked(start: u128, n: usize) -> Option<u128>

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

recently redesigned

pub fn backward_checked(start: u128, n: usize) -> Option<u128>

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

recently redesigned

impl Step for u16

pub unsafe fn forward_unchecked(start: u16, n: usize) -> u16

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

recently redesigned

pub unsafe fn backward_unchecked(start: u16, n: usize) -> u16

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

recently redesigned

pub fn forward(start: u16, n: usize) -> u16

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

recently redesigned

pub fn backward(start: u16, n: usize) -> u16

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

recently redesigned

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

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

recently redesigned

pub fn forward_checked(start: u16, n: usize) -> Option<u16>

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

recently redesigned

pub fn backward_checked(start: u16, n: usize) -> Option<u16>

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

recently redesigned

impl Step for u32

pub unsafe fn forward_unchecked(start: u32, n: usize) -> u32

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

recently redesigned

pub unsafe fn backward_unchecked(start: u32, n: usize) -> u32

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

recently redesigned

pub fn forward(start: u32, n: usize) -> u32

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

recently redesigned

pub fn backward(start: u32, n: usize) -> u32

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

recently redesigned

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

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

recently redesigned

pub fn forward_checked(start: u32, n: usize) -> Option<u32>

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

recently redesigned

pub fn backward_checked(start: u32, n: usize) -> Option<u32>

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

recently redesigned

impl Step for char

pub fn steps_between(&char, &char) -> Option<usize>

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

recently redesigned

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

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

recently redesigned

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

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

recently redesigned

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

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

recently redesigned

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

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

recently redesigned

impl Step for u64

pub unsafe fn forward_unchecked(start: u64, n: usize) -> u64

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

recently redesigned

pub unsafe fn backward_unchecked(start: u64, n: usize) -> u64

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

recently redesigned

pub fn forward(start: u64, n: usize) -> u64

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

recently redesigned

pub fn backward(start: u64, n: usize) -> u64

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

recently redesigned

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

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

recently redesigned

pub fn forward_checked(start: u64, n: usize) -> Option<u64>

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

recently redesigned

pub fn backward_checked(start: u64, n: usize) -> Option<u64>

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

recently redesigned

impl Step for isize

pub unsafe fn forward_unchecked(start: isize, n: usize) -> isize

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

recently redesigned

pub unsafe fn backward_unchecked(start: isize, n: usize) -> isize

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

recently redesigned

pub fn forward(start: isize, n: usize) -> isize

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

recently redesigned

pub fn backward(start: isize, n: usize) -> isize

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

recently redesigned

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

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

recently redesigned

pub fn forward_checked(start: isize, n: usize) -> Option<isize>

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

recently redesigned

pub fn backward_checked(start: isize, n: usize) -> Option<isize>

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

recently redesigned

impl Step for u8

pub unsafe fn forward_unchecked(start: u8, n: usize) -> u8

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

recently redesigned

pub unsafe fn backward_unchecked(start: u8, n: usize) -> u8

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

recently redesigned

pub fn forward(start: u8, n: usize) -> u8

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

recently redesigned

pub fn backward(start: u8, n: usize) -> u8

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

recently redesigned

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

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

recently redesigned

pub fn forward_checked(start: u8, n: usize) -> Option<u8>

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

recently redesigned

pub fn backward_checked(start: u8, n: usize) -> Option<u8>

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

recently redesigned

impl Step for i128

pub unsafe fn forward_unchecked(start: i128, n: usize) -> i128

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

recently redesigned

pub unsafe fn backward_unchecked(start: i128, n: usize) -> i128

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

recently redesigned

pub fn forward(start: i128, n: usize) -> i128

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

recently redesigned

pub fn backward(start: i128, n: usize) -> i128

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

recently redesigned

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

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

recently redesigned

pub fn forward_checked(start: i128, n: usize) -> Option<i128>

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

recently redesigned

pub fn backward_checked(start: i128, n: usize) -> Option<i128>

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

recently redesigned

Implementors