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 { ... }
}step_trait)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
step_trait)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(&b, 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
fn forward_checked(start: Self, count: usize) -> Option<Self>
fn forward_checked(start: Self, count: usize) -> Option<Self>
step_trait)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:
fn backward_checked(start: Self, count: usize) -> Option<Self>
fn backward_checked(start: Self, count: usize) -> Option<Self>
step_trait)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
step_trait)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
unsafe fn forward_unchecked(start: Self, count: usize) -> Self
unsafe fn forward_unchecked(start: Self, count: usize) -> Self
step_trait)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)
step_trait)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
unsafe fn backward_unchecked(start: Self, count: usize) -> Self
unsafe fn backward_unchecked(start: Self, count: usize) -> Self
step_trait)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)
Implementations on Foreign Types
step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)step_trait)