Trait std::iter::Step [−][src]
pub unsafe trait Step: Clone + PartialOrd<Self> { pub fn steps_between(start: &Self, end: &Self) -> Option<usize>; pub fn forward_checked(start: Self, count: usize) -> Option<Self>; pub fn backward_checked(start: Self, count: usize) -> Option<Self>; pub fn forward(start: Self, count: usize) -> Self { ... } pub unsafe fn forward_unchecked(start: Self, count: usize) -> Self { ... } pub fn backward(start: Self, count: usize) -> Self { ... } pub unsafe fn backward_unchecked(start: Self, count: usize) -> Self { ... } }
🔬 This is a nightly-only experimental API. (step_trait #42168)
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.
Safety
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.
Required methods
pub fn steps_between(start: &Self, end: &Self) -> Option<usize>[src]
🔬 This is a nightly-only experimental API. (step_trait #42168)
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 ifStep::forward_checked(&a, n) == Some(b)steps_between(&a, &b) == Some(n)if and only ifStep::backward_checked(&a, n) == Some(a)steps_between(&a, &b) == Some(n)only ifa <= b- Corollary:
steps_between(&a, &b) == Some(0)if and only ifa == b - Note that
a <= bdoes not implysteps_between(&a, &b) != None; this is the case when it would require more thanusize::MAXsteps to get tob
- Corollary:
steps_between(&a, &b) == Noneifa > b
pub fn forward_checked(start: Self, count: usize) -> Option<Self>[src]
🔬 This is a nightly-only experimental API. (step_trait_ext #42168)
recently added
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)
- Corollary:
pub fn backward_checked(start: Self, count: usize) -> Option<Self>[src]
🔬 This is a nightly-only experimental API. (step_trait_ext #42168)
recently added
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)
- Corollary:
Provided methods
pub fn forward(start: Self, count: usize) -> Self[src]
🔬 This is a nightly-only experimental API. (step_trait_ext #42168)
recently added
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
- Corollary:
Step::forward(a, n) >= aStep::backward(Step::forward(a, n), n) == a
pub unsafe fn forward_unchecked(start: Self, count: usize) -> Self[src]
🔬 This is a nightly-only experimental API. (unchecked_math)
niche optimization path
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
bsuch thatb > a, it is safe to callStep::forward_unchecked(a, 1) - if there exists
b,nsuch thatsteps_between(&a, &b) == Some(n), it is safe to callStep::forward_unchecked(a, m)for anym <= n.
For any a and n, where no overflow occurs:
Step::forward_unchecked(a, n)is equivalent toStep::forward(a, n)
pub fn backward(start: Self, count: usize) -> Self[src]
🔬 This is a nightly-only experimental API. (step_trait_ext #42168)
recently added
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
- Corollary:
Step::backward(a, n) <= aStep::forward(Step::backward(a, n), n) == a
pub unsafe fn backward_unchecked(start: Self, count: usize) -> Self[src]
🔬 This is a nightly-only experimental API. (unchecked_math)
niche optimization path
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
bsuch thatb < a, it is safe to callStep::backward_unchecked(a, 1) - if there exists
b,nsuch thatsteps_between(&b, &a) == Some(n), it is safe to callStep::backward_unchecked(a, m)for anym <= n.
For any a and n, where no overflow occurs:
Step::backward_unchecked(a, n)is equivalent toStep::backward(a, n)
Implementors
impl Step for char[src]
impl Step for char[src]pub fn steps_between(&char, &char) -> Option<usize>[src]
pub fn forward_checked(start: char, count: usize) -> Option<char>[src]
pub fn backward_checked(start: char, count: usize) -> Option<char>[src]
pub unsafe fn forward_unchecked(start: char, count: usize) -> char[src]
pub unsafe fn backward_unchecked(start: char, count: usize) -> char[src]
impl Step for i8[src]
impl Step for i8[src]pub unsafe fn forward_unchecked(start: i8, n: usize) -> i8[src]
pub unsafe fn backward_unchecked(start: i8, n: usize) -> i8[src]
pub fn forward(start: i8, n: usize) -> i8[src]
pub fn backward(start: i8, n: usize) -> i8[src]
pub fn steps_between(start: &i8, end: &i8) -> Option<usize>[src]
pub fn forward_checked(start: i8, n: usize) -> Option<i8>[src]
pub fn backward_checked(start: i8, n: usize) -> Option<i8>[src]
impl Step for i16[src]
impl Step for i16[src]pub unsafe fn forward_unchecked(start: i16, n: usize) -> i16[src]
pub unsafe fn backward_unchecked(start: i16, n: usize) -> i16[src]
pub fn forward(start: i16, n: usize) -> i16[src]
pub fn backward(start: i16, n: usize) -> i16[src]
pub fn steps_between(start: &i16, end: &i16) -> Option<usize>[src]
pub fn forward_checked(start: i16, n: usize) -> Option<i16>[src]
pub fn backward_checked(start: i16, n: usize) -> Option<i16>[src]
impl Step for i32[src]
impl Step for i32[src]pub unsafe fn forward_unchecked(start: i32, n: usize) -> i32[src]
pub unsafe fn backward_unchecked(start: i32, n: usize) -> i32[src]
pub fn forward(start: i32, n: usize) -> i32[src]
pub fn backward(start: i32, n: usize) -> i32[src]
pub fn steps_between(start: &i32, end: &i32) -> Option<usize>[src]
pub fn forward_checked(start: i32, n: usize) -> Option<i32>[src]
pub fn backward_checked(start: i32, n: usize) -> Option<i32>[src]
impl Step for i64[src]
impl Step for i64[src]pub unsafe fn forward_unchecked(start: i64, n: usize) -> i64[src]
pub unsafe fn backward_unchecked(start: i64, n: usize) -> i64[src]
pub fn forward(start: i64, n: usize) -> i64[src]
pub fn backward(start: i64, n: usize) -> i64[src]
pub fn steps_between(start: &i64, end: &i64) -> Option<usize>[src]
pub fn forward_checked(start: i64, n: usize) -> Option<i64>[src]
pub fn backward_checked(start: i64, n: usize) -> Option<i64>[src]
impl Step for i128[src]
impl Step for i128[src]pub unsafe fn forward_unchecked(start: i128, n: usize) -> i128[src]
pub unsafe fn backward_unchecked(start: i128, n: usize) -> i128[src]
pub fn forward(start: i128, n: usize) -> i128[src]
pub fn backward(start: i128, n: usize) -> i128[src]
pub fn steps_between(start: &i128, end: &i128) -> Option<usize>[src]
pub fn forward_checked(start: i128, n: usize) -> Option<i128>[src]
pub fn backward_checked(start: i128, n: usize) -> Option<i128>[src]
impl Step for isize[src]
impl Step for isize[src]pub unsafe fn forward_unchecked(start: isize, n: usize) -> isize[src]
pub unsafe fn backward_unchecked(start: isize, n: usize) -> isize[src]
pub fn forward(start: isize, n: usize) -> isize[src]
pub fn backward(start: isize, n: usize) -> isize[src]
pub fn steps_between(start: &isize, end: &isize) -> Option<usize>[src]
pub fn forward_checked(start: isize, n: usize) -> Option<isize>[src]
pub fn backward_checked(start: isize, n: usize) -> Option<isize>[src]
impl Step for u8[src]
impl Step for u8[src]pub unsafe fn forward_unchecked(start: u8, n: usize) -> u8[src]
pub unsafe fn backward_unchecked(start: u8, n: usize) -> u8[src]
pub fn forward(start: u8, n: usize) -> u8[src]
pub fn backward(start: u8, n: usize) -> u8[src]
pub fn steps_between(start: &u8, end: &u8) -> Option<usize>[src]
pub fn forward_checked(start: u8, n: usize) -> Option<u8>[src]
pub fn backward_checked(start: u8, n: usize) -> Option<u8>[src]
impl Step for u16[src]
impl Step for u16[src]pub unsafe fn forward_unchecked(start: u16, n: usize) -> u16[src]
pub unsafe fn backward_unchecked(start: u16, n: usize) -> u16[src]
pub fn forward(start: u16, n: usize) -> u16[src]
pub fn backward(start: u16, n: usize) -> u16[src]
pub fn steps_between(start: &u16, end: &u16) -> Option<usize>[src]
pub fn forward_checked(start: u16, n: usize) -> Option<u16>[src]
pub fn backward_checked(start: u16, n: usize) -> Option<u16>[src]
impl Step for u32[src]
impl Step for u32[src]pub unsafe fn forward_unchecked(start: u32, n: usize) -> u32[src]
pub unsafe fn backward_unchecked(start: u32, n: usize) -> u32[src]
pub fn forward(start: u32, n: usize) -> u32[src]
pub fn backward(start: u32, n: usize) -> u32[src]
pub fn steps_between(start: &u32, end: &u32) -> Option<usize>[src]
pub fn forward_checked(start: u32, n: usize) -> Option<u32>[src]
pub fn backward_checked(start: u32, n: usize) -> Option<u32>[src]
impl Step for u64[src]
impl Step for u64[src]pub unsafe fn forward_unchecked(start: u64, n: usize) -> u64[src]
pub unsafe fn backward_unchecked(start: u64, n: usize) -> u64[src]
pub fn forward(start: u64, n: usize) -> u64[src]
pub fn backward(start: u64, n: usize) -> u64[src]
pub fn steps_between(start: &u64, end: &u64) -> Option<usize>[src]
pub fn forward_checked(start: u64, n: usize) -> Option<u64>[src]
pub fn backward_checked(start: u64, n: usize) -> Option<u64>[src]
impl Step for u128[src]
impl Step for u128[src]pub unsafe fn forward_unchecked(start: u128, n: usize) -> u128[src]
pub unsafe fn backward_unchecked(start: u128, n: usize) -> u128[src]
pub fn forward(start: u128, n: usize) -> u128[src]
pub fn backward(start: u128, n: usize) -> u128[src]
pub fn steps_between(start: &u128, end: &u128) -> Option<usize>[src]
pub fn forward_checked(start: u128, n: usize) -> Option<u128>[src]
pub fn backward_checked(start: u128, n: usize) -> Option<u128>[src]
impl Step for usize[src]
impl Step for usize[src]