Step in core::iter - Rust
Skip to main content Step core :: iter Trait Step Source pub trait Step: Clone + PartialOrd + Sized { // Required methods fn steps_between (start: &Self, end: &Self) -> ( usize , Option < usize >); fn forward_checked (start: Self, count: usize ) -> Option <Self>; fn forward_overflowing (start: Self, count: usize ) -> (Self, bool ); fn backward_checked (start: Self, count: usize ) -> Option <Self>; fn backward_overflowing (start: Self, count: usize ) -> (Self, bool ); // 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 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 § Source fn steps_between (start: &Self, end: &Self) -> ( usize , Option < usize >) 🔬 This is a nightly-only experimental API. ( step_trait #42168 ) Returns the bounds on the number of successor steps required to get from start to end like Iterator::size_hint() . Returns (usize::MAX, None) if the number of steps would overflow usize , or is infinite. § Invariants For any a , b , and n : steps_between(&a, &b) == (n, Some(n)) if and only if Step::forward_checked(&a, n) == Some(b) steps_between(&a, &b) == (n, Some(n)) if and only if Step::backward_checked(&b, n) == Some(a) steps_between(&a, &b) == (n, Some(n)) only if a <= b Corollary: steps_between(&a, &b) == (0, Some(0)) if and only if a == b steps_between(&a, &b) == (0, None) if a > b Source fn forward_checked (start: Self, count: usize ) -> Option <Self> 🔬 This is a nightly-only experimental API. ( step_trait #42168 ) 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)) Step::forward_checked(a, n).and_then(|x| Step::forward_checked(x, m)) == try { Step::forward_checked(a, n.checked_add(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) Source fn forward_overflowing (start: Self, count: usize ) -> (Self, bool ) 🔬 This is a nightly-only experimental API. ( step_trait #42168 ) Returns the value that would be obtained by taking the successor of self count times along with a boolean tracking whether overflow occurred.
If this would overflow the range of values supported by Self , the value returned is unspecified and should not be relied on, though typically wrapping (modular arithmetic) is the most effective implementation to enable optimizations. § Invariants For any a , n , and m , where no overflow occurs: Step::forward_overflowing(Step::forward_overflowing(a, n).0, m) == Step::forward_overflowing(a, n + m) For any a and n , where no overflow occurs: Step::forward_overflowing(a, n) == (Step::forward_checked(a, n).unwrap(), false) For any a and n : Step::forward_overflowing(a, n) == (0..n).fold((a, false), |(x, y), _| { let (s, o) = Step::forward_overflowing(x, 1); (s, y || o) }) Corollary: Step::forward_overflowing(a, 0) == (a, false) Source fn backward_checked (start: Self, count: usize ) -> Option <Self> 🔬 This is a nightly-only experimental API. ( step_trait #42168 ) 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) Source fn backward_overflowing (start: Self, count: usize ) -> (Self, bool ) 🔬 This is a nightly-only experimental API. ( step_trait #42168 ) Returns the value that would be obtained by taking the successor of self count times along with a boolean tracking whether overflow occurred.
If this would overflow the range of values supported by Self , the value returned is unspecified and should not be relied on, though typically wrapping (modular arithmetic) is the most effective implementation to enable optimizations. § Invariants For any a , n , and m , where no overflow occurs: Step::backward_overflowing(Step::backward_overflowing(a, n).0, m) == Step::backward_overflowing(a, n + m) For any a and n , where no overflow occurs: Step::backward_overflowing(a, n) == (Step::backward_checked(a, n).unwrap(), false) For any a and n : Step::backward_overflowing(a, n) == (0..n).fold((a, false), |(x, y), _| { let (s, o) = Step::backward_overflowing(x, 1); (s, y || o) }) Corollary: Step::backward_overflowing(a, 0) == (a, false) Provided Methods § Source fn forward (start: Self, count: usize ) -> Self 🔬 This is a nightly-only experimental API. ( step_trait #42168 ) 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 Source unsafe fn forward_unchecked (start: Self, count: usize ) -> Self 🔬 This is a nightly-only experimental API. ( step_trait #42168 ) 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 . Corollary: Step::forward_unchecked(a, 0) is always safe. For any a and n , where no overflow occurs: Step::forward_unchecked(a, n) is equivalent to Step::forward(a, n) Source fn backward (start: Self, count: usize ) -> Self 🔬 This is a nightly-only experimental API. ( step_trait #42168 ) 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)
The rest of this page is on the live site.