pub trait Step:Sized +Clone +PartialOrd { // Required methods fnsteps_between(start: &Self, end: &Self) -> (usize,Option<usize>); fnforward_checked(start: Self, count:usize) ->Option<Self>; fnbackward_checked(start: Self, count:usize) ->Option<Self>; // Provided methods fnforward(start: Self, count:usize) -> Self { ... } unsafe fnforward_unchecked(start: Self, count:usize) -> Self { ... } fnbackward(start: Self, count:usize) -> Self { ... } unsafe fnbackward_unchecked(start: Self, count:usize) -> Self { ... }}step_trait #42168)Expand description
Objects that have a notion ofsuccessor andpredecessor operations.
Thesuccessor operation moves towards values that compare greater.Thepredecessor operation moves towards values that compare lesser.
Required Methods§
Sourcefnsteps_between(start: &Self, end: &Self) -> (usize,Option<usize>)
🔬This is a nightly-only experimental API. (step_trait #42168)
fnsteps_between(start: &Self, end: &Self) -> (usize,Option<usize>)
step_trait #42168)Returns the bounds on the number ofsuccessor steps required to get fromstart toendlikeIterator::size_hint().
Returns(usize::MAX, None) if the number of steps would overflowusize, or is infinite.
§Invariants
For anya,b, andn:
steps_between(&a, &b) == (n, Some(n))if and only ifStep::forward_checked(&a, n) == Some(b)steps_between(&a, &b) == (n, Some(n))if and only ifStep::backward_checked(&b, n) == Some(a)steps_between(&a, &b) == (n, Some(n))only ifa <= b- Corollary:
steps_between(&a, &b) == (0, Some(0))if and only ifa == b
- Corollary:
steps_between(&a, &b) == (0, None)ifa > b
Sourcefnforward_checked(start: Self, count:usize) ->Option<Self>
🔬This is a nightly-only experimental API. (step_trait #42168)
fnforward_checked(start: Self, count:usize) ->Option<Self>
step_trait #42168)Returns the value that would be obtained by taking thesuccessorofselfcount times.
If this would overflow the range of values supported bySelf, returnsNone.
§Invariants
For anya,n, andm:
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 anya andn:
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:
Sourcefnbackward_checked(start: Self, count:usize) ->Option<Self>
🔬This is a nightly-only experimental API. (step_trait #42168)
fnbackward_checked(start: Self, count:usize) ->Option<Self>
step_trait #42168)Returns the value that would be obtained by taking thepredecessorofselfcount times.
If this would overflow the range of values supported bySelf, returnsNone.
§Invariants
For anya,n, andm:
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 anya andn:
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§
Sourcefnforward(start: Self, count:usize) -> Self
🔬This is a nightly-only experimental API. (step_trait #42168)
fnforward(start: Self, count:usize) -> Self
step_trait #42168)Returns the value that would be obtained by taking thesuccessorofselfcount times.
If this would overflow the range of values supported bySelf,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 anya,n, andm, where no overflow occurs:
Step::forward(Step::forward(a, n), m) == Step::forward(a, n + m)
For anya andn, 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
Sourceunsafe fnforward_unchecked(start: Self, count:usize) -> Self
🔬This is a nightly-only experimental API. (step_trait #42168)
unsafe fnforward_unchecked(start: Self, count:usize) -> Self
step_trait #42168)Returns the value that would be obtained by taking thesuccessorofselfcount times.
§Safety
It is undefined behavior for this operation to overflow therange of values supported bySelf. If you cannot guarantee that thiswill not overflow, useforward orforward_checked instead.
§Invariants
For anya:
- 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.- Corollary:
Step::forward_unchecked(a, 0)is always safe.
- Corollary:
For anya andn, where no overflow occurs:
Step::forward_unchecked(a, n)is equivalent toStep::forward(a, n)
Sourcefnbackward(start: Self, count:usize) -> Self
🔬This is a nightly-only experimental API. (step_trait #42168)
fnbackward(start: Self, count:usize) -> Self
step_trait #42168)Returns the value that would be obtained by taking thepredecessorofselfcount times.
If this would overflow the range of values supported bySelf,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 anya,n, andm, where no overflow occurs:
Step::backward(Step::backward(a, n), m) == Step::backward(a, n + m)
For anya andn, 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
Sourceunsafe fnbackward_unchecked(start: Self, count:usize) -> Self
🔬This is a nightly-only experimental API. (step_trait #42168)
unsafe fnbackward_unchecked(start: Self, count:usize) -> Self
step_trait #42168)Returns the value that would be obtained by taking thepredecessorofselfcount times.
§Safety
It is undefined behavior for this operation to overflow therange of values supported bySelf. If you cannot guarantee that thiswill not overflow, usebackward orbackward_checked instead.
§Invariants
For anya:
- if there exists
bsuch thatb < a, it is safe to callStep::backward_unchecked(a, 1) - if there exists
b,nsuch thatsteps_between(&b, &a) == (n, Some(n)),it is safe to callStep::backward_unchecked(a, m)for anym <= n.- Corollary:
Step::backward_unchecked(a, 0)is always safe.
- Corollary:
For anya andn, where no overflow occurs:
Step::backward_unchecked(a, n)is equivalent toStep::backward(a, n)
Dyn Compatibility§
This trait isnotdyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.