pub unsafe 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 { ... }
}
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.
This trait is unsafe because its implementation must be correct for the safety of unsafe trait TrustedLen implementations, and the results of using this trait can otherwise be trusted by unsafe code to be correct and fulfill the listed obligations.
fn steps_between(start: &Self, end: &Self) -> Option<usize>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).
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 steps_between(&a, &b) == Some(0) if and only if a == b
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>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.
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)) Step::forward_checked(&a, 0) == Some(a)
fn backward_checked(start: Self, count: usize) -> Option<Self>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.
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)) Step::backward_checked(&a, 0) == Some(a)
fn forward(start: Self, count: usize) -> SelfReturns 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.
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)) Step::forward(a, 0) == a
Step::forward(a, n) >= aStep::backward(Step::forward(a, n), n) == aunsafe fn forward_unchecked(start: Self, count: usize) -> SelfReturns the value that would be obtained by taking the successor of self count times.
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.
For any a:
b such that b > a, it is safe to call Step::forward_unchecked(a, 1)
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) -> SelfReturns 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.
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)) Step::backward(a, 0) == a
Step::backward(a, n) <= aStep::forward(Step::backward(a, n), n) == aunsafe fn backward_unchecked(start: Self, count: usize) -> SelfReturns the value that would be obtained by taking the predecessor of self count times.
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.
For any a:
b such that b < a, it is safe to call Step::backward_unchecked(a, 1)
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)
impl Step for char[src]
fn steps_between(&char, &char) -> Option<usize>[src]
fn forward_checked(start: char, count: usize) -> Option<char>[src]
fn backward_checked(start: char, count: usize) -> Option<char>[src]
unsafe fn forward_unchecked(start: char, count: usize) -> char[src]
unsafe fn backward_unchecked(start: char, count: usize) -> char[src]
impl Step for i8[src]
unsafe fn forward_unchecked(start: i8, n: usize) -> i8[src]
unsafe fn backward_unchecked(start: i8, n: usize) -> i8[src]
fn forward(start: i8, n: usize) -> i8[src]
fn backward(start: i8, n: usize) -> i8[src]
fn steps_between(start: &i8, end: &i8) -> Option<usize>[src]
fn forward_checked(start: i8, n: usize) -> Option<i8>[src]
fn backward_checked(start: i8, n: usize) -> Option<i8>[src]
impl Step for i16[src]
unsafe fn forward_unchecked(start: i16, n: usize) -> i16[src]
unsafe fn backward_unchecked(start: i16, n: usize) -> i16[src]
fn forward(start: i16, n: usize) -> i16[src]
fn backward(start: i16, n: usize) -> i16[src]
fn steps_between(start: &i16, end: &i16) -> Option<usize>[src]
fn forward_checked(start: i16, n: usize) -> Option<i16>[src]
fn backward_checked(start: i16, n: usize) -> Option<i16>[src]
impl Step for i32[src]
unsafe fn forward_unchecked(start: i32, n: usize) -> i32[src]
unsafe fn backward_unchecked(start: i32, n: usize) -> i32[src]
fn forward(start: i32, n: usize) -> i32[src]
fn backward(start: i32, n: usize) -> i32[src]
fn steps_between(start: &i32, end: &i32) -> Option<usize>[src]
fn forward_checked(start: i32, n: usize) -> Option<i32>[src]
fn backward_checked(start: i32, n: usize) -> Option<i32>[src]
impl Step for i64[src]
unsafe fn forward_unchecked(start: i64, n: usize) -> i64[src]
unsafe fn backward_unchecked(start: i64, n: usize) -> i64[src]
fn forward(start: i64, n: usize) -> i64[src]
fn backward(start: i64, n: usize) -> i64[src]
fn steps_between(start: &i64, end: &i64) -> Option<usize>[src]
fn forward_checked(start: i64, n: usize) -> Option<i64>[src]
fn backward_checked(start: i64, n: usize) -> Option<i64>[src]
impl Step for i128[src]
unsafe fn forward_unchecked(start: i128, n: usize) -> i128[src]
unsafe fn backward_unchecked(start: i128, n: usize) -> i128[src]
fn forward(start: i128, n: usize) -> i128[src]
fn backward(start: i128, n: usize) -> i128[src]
fn steps_between(start: &i128, end: &i128) -> Option<usize>[src]
fn forward_checked(start: i128, n: usize) -> Option<i128>[src]
fn backward_checked(start: i128, n: usize) -> Option<i128>[src]
impl Step for isize[src]
unsafe fn forward_unchecked(start: isize, n: usize) -> isize[src]
unsafe fn backward_unchecked(start: isize, n: usize) -> isize[src]
fn forward(start: isize, n: usize) -> isize[src]
fn backward(start: isize, n: usize) -> isize[src]
fn steps_between(start: &isize, end: &isize) -> Option<usize>[src]
fn forward_checked(start: isize, n: usize) -> Option<isize>[src]
fn backward_checked(start: isize, n: usize) -> Option<isize>[src]
impl Step for u8[src]
unsafe fn forward_unchecked(start: u8, n: usize) -> u8[src]
unsafe fn backward_unchecked(start: u8, n: usize) -> u8[src]
fn forward(start: u8, n: usize) -> u8[src]
fn backward(start: u8, n: usize) -> u8[src]
fn steps_between(start: &u8, end: &u8) -> Option<usize>[src]
fn forward_checked(start: u8, n: usize) -> Option<u8>[src]
fn backward_checked(start: u8, n: usize) -> Option<u8>[src]
impl Step for u16[src]
unsafe fn forward_unchecked(start: u16, n: usize) -> u16[src]
unsafe fn backward_unchecked(start: u16, n: usize) -> u16[src]
fn forward(start: u16, n: usize) -> u16[src]
fn backward(start: u16, n: usize) -> u16[src]
fn steps_between(start: &u16, end: &u16) -> Option<usize>[src]
fn forward_checked(start: u16, n: usize) -> Option<u16>[src]
fn backward_checked(start: u16, n: usize) -> Option<u16>[src]
impl Step for u32[src]
unsafe fn forward_unchecked(start: u32, n: usize) -> u32[src]
unsafe fn backward_unchecked(start: u32, n: usize) -> u32[src]
fn forward(start: u32, n: usize) -> u32[src]
fn backward(start: u32, n: usize) -> u32[src]
fn steps_between(start: &u32, end: &u32) -> Option<usize>[src]
fn forward_checked(start: u32, n: usize) -> Option<u32>[src]
fn backward_checked(start: u32, n: usize) -> Option<u32>[src]
impl Step for u64[src]
unsafe fn forward_unchecked(start: u64, n: usize) -> u64[src]
unsafe fn backward_unchecked(start: u64, n: usize) -> u64[src]
fn forward(start: u64, n: usize) -> u64[src]
fn backward(start: u64, n: usize) -> u64[src]
fn steps_between(start: &u64, end: &u64) -> Option<usize>[src]
fn forward_checked(start: u64, n: usize) -> Option<u64>[src]
fn backward_checked(start: u64, n: usize) -> Option<u64>[src]
impl Step for u128[src]
unsafe fn forward_unchecked(start: u128, n: usize) -> u128[src]
unsafe fn backward_unchecked(start: u128, n: usize) -> u128[src]
fn forward(start: u128, n: usize) -> u128[src]
fn backward(start: u128, n: usize) -> u128[src]
fn steps_between(start: &u128, end: &u128) -> Option<usize>[src]
fn forward_checked(start: u128, n: usize) -> Option<u128>[src]
fn backward_checked(start: u128, n: usize) -> Option<u128>[src]
impl Step for usize[src]
unsafe fn forward_unchecked(start: usize, n: usize) -> usize[src]
unsafe fn backward_unchecked(start: usize, n: usize) -> usize[src]
fn forward(start: usize, n: usize) -> usize[src]
fn backward(start: usize, n: usize) -> usize[src]
fn steps_between(start: &usize, end: &usize) -> Option<usize>[src]
fn forward_checked(start: usize, n: usize) -> Option<usize>[src]
fn backward_checked(start: usize, n: usize) -> Option<usize>[src]
© 2010 The Rust Project Developers
Licensed under the Apache License, Version 2.0 or the MIT license, at your option.
https://doc.rust-lang.org/std/iter/trait.Step.html