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 <= b
does not implysteps_between(&a, &b) != None
; this is the case when it would require more thanusize::MAX
steps to get tob
- Corollary:
steps_between(&a, &b) == None
ifa > 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) >= a
Step::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
b
such thatb > a
, it is safe to callStep::forward_unchecked(a, 1)
- if there exists
b
,n
such 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) <= a
Step::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
b
such thatb < a
, it is safe to callStep::backward_unchecked(a, 1)
- if there exists
b
,n
such 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
sourceimpl Step for u8
impl Step for u8
sourceunsafe fn forward_unchecked(start: u8, n: usize) -> u8
unsafe fn forward_unchecked(start: u8, n: usize) -> u8
step_trait
)sourceunsafe fn backward_unchecked(start: u8, n: usize) -> u8
unsafe fn backward_unchecked(start: u8, n: usize) -> u8
step_trait
)sourcefn steps_between(start: &u8, end: &u8) -> Option<usize>
fn steps_between(start: &u8, end: &u8) -> Option<usize>
step_trait
)sourceimpl Step for u64
impl Step for u64
sourceunsafe fn forward_unchecked(start: u64, n: usize) -> u64
unsafe fn forward_unchecked(start: u64, n: usize) -> u64
step_trait
)sourceunsafe fn backward_unchecked(start: u64, n: usize) -> u64
unsafe fn backward_unchecked(start: u64, n: usize) -> u64
step_trait
)sourcefn forward(start: u64, n: usize) -> u64
fn forward(start: u64, n: usize) -> u64
step_trait
)sourcefn backward(start: u64, n: usize) -> u64
fn backward(start: u64, n: usize) -> u64
step_trait
)sourcefn steps_between(start: &u64, end: &u64) -> Option<usize>
fn steps_between(start: &u64, end: &u64) -> Option<usize>
step_trait
)sourceimpl Step for i64
impl Step for i64
sourceunsafe fn forward_unchecked(start: i64, n: usize) -> i64
unsafe fn forward_unchecked(start: i64, n: usize) -> i64
step_trait
)sourceunsafe fn backward_unchecked(start: i64, n: usize) -> i64
unsafe fn backward_unchecked(start: i64, n: usize) -> i64
step_trait
)sourcefn forward(start: i64, n: usize) -> i64
fn forward(start: i64, n: usize) -> i64
step_trait
)sourcefn backward(start: i64, n: usize) -> i64
fn backward(start: i64, n: usize) -> i64
step_trait
)sourcefn steps_between(start: &i64, end: &i64) -> Option<usize>
fn steps_between(start: &i64, end: &i64) -> Option<usize>
step_trait
)sourceimpl Step for char
impl Step for char
sourcefn steps_between(&char, &char) -> Option<usize>
fn steps_between(&char, &char) -> Option<usize>
step_trait
)sourcefn forward_checked(start: char, count: usize) -> Option<char>
fn forward_checked(start: char, count: usize) -> Option<char>
step_trait
)sourcefn backward_checked(start: char, count: usize) -> Option<char>
fn backward_checked(start: char, count: usize) -> Option<char>
step_trait
)sourceunsafe fn forward_unchecked(start: char, count: usize) -> char
unsafe fn forward_unchecked(start: char, count: usize) -> char
step_trait
)sourceunsafe fn backward_unchecked(start: char, count: usize) -> char
unsafe fn backward_unchecked(start: char, count: usize) -> char
step_trait
)sourceimpl Step for i128
impl Step for i128
sourceunsafe fn forward_unchecked(start: i128, n: usize) -> i128
unsafe fn forward_unchecked(start: i128, n: usize) -> i128
step_trait
)sourceunsafe fn backward_unchecked(start: i128, n: usize) -> i128
unsafe fn backward_unchecked(start: i128, n: usize) -> i128
step_trait
)sourcefn forward(start: i128, n: usize) -> i128
fn forward(start: i128, n: usize) -> i128
step_trait
)sourcefn backward(start: i128, n: usize) -> i128
fn backward(start: i128, n: usize) -> i128
step_trait
)sourcefn steps_between(start: &i128, end: &i128) -> Option<usize>
fn steps_between(start: &i128, end: &i128) -> Option<usize>
step_trait
)sourceimpl Step for i16
impl Step for i16
sourceunsafe fn forward_unchecked(start: i16, n: usize) -> i16
unsafe fn forward_unchecked(start: i16, n: usize) -> i16
step_trait
)sourceunsafe fn backward_unchecked(start: i16, n: usize) -> i16
unsafe fn backward_unchecked(start: i16, n: usize) -> i16
step_trait
)sourcefn forward(start: i16, n: usize) -> i16
fn forward(start: i16, n: usize) -> i16
step_trait
)sourcefn backward(start: i16, n: usize) -> i16
fn backward(start: i16, n: usize) -> i16
step_trait
)sourcefn steps_between(start: &i16, end: &i16) -> Option<usize>
fn steps_between(start: &i16, end: &i16) -> Option<usize>
step_trait
)sourceimpl Step for i32
impl Step for i32
sourceunsafe fn forward_unchecked(start: i32, n: usize) -> i32
unsafe fn forward_unchecked(start: i32, n: usize) -> i32
step_trait
)sourceunsafe fn backward_unchecked(start: i32, n: usize) -> i32
unsafe fn backward_unchecked(start: i32, n: usize) -> i32
step_trait
)sourcefn forward(start: i32, n: usize) -> i32
fn forward(start: i32, n: usize) -> i32
step_trait
)sourcefn backward(start: i32, n: usize) -> i32
fn backward(start: i32, n: usize) -> i32
step_trait
)sourcefn steps_between(start: &i32, end: &i32) -> Option<usize>
fn steps_between(start: &i32, end: &i32) -> Option<usize>
step_trait
)sourceimpl Step for u128
impl Step for u128
sourceunsafe fn forward_unchecked(start: u128, n: usize) -> u128
unsafe fn forward_unchecked(start: u128, n: usize) -> u128
step_trait
)sourceunsafe fn backward_unchecked(start: u128, n: usize) -> u128
unsafe fn backward_unchecked(start: u128, n: usize) -> u128
step_trait
)sourcefn forward(start: u128, n: usize) -> u128
fn forward(start: u128, n: usize) -> u128
step_trait
)sourcefn backward(start: u128, n: usize) -> u128
fn backward(start: u128, n: usize) -> u128
step_trait
)sourcefn steps_between(start: &u128, end: &u128) -> Option<usize>
fn steps_between(start: &u128, end: &u128) -> Option<usize>
step_trait
)sourceimpl Step for usize
impl Step for usize
sourceunsafe fn forward_unchecked(start: usize, n: usize) -> usize
unsafe fn forward_unchecked(start: usize, n: usize) -> usize
step_trait
)sourceunsafe fn backward_unchecked(start: usize, n: usize) -> usize
unsafe fn backward_unchecked(start: usize, n: usize) -> usize
step_trait
)sourcefn forward(start: usize, n: usize) -> usize
fn forward(start: usize, n: usize) -> usize
step_trait
)sourcefn backward(start: usize, n: usize) -> usize
fn backward(start: usize, n: usize) -> usize
step_trait
)sourcefn steps_between(start: &usize, end: &usize) -> Option<usize>
fn steps_between(start: &usize, end: &usize) -> Option<usize>
step_trait
)sourceimpl Step for u32
impl Step for u32
sourceunsafe fn forward_unchecked(start: u32, n: usize) -> u32
unsafe fn forward_unchecked(start: u32, n: usize) -> u32
step_trait
)sourceunsafe fn backward_unchecked(start: u32, n: usize) -> u32
unsafe fn backward_unchecked(start: u32, n: usize) -> u32
step_trait
)sourcefn forward(start: u32, n: usize) -> u32
fn forward(start: u32, n: usize) -> u32
step_trait
)sourcefn backward(start: u32, n: usize) -> u32
fn backward(start: u32, n: usize) -> u32
step_trait
)sourcefn steps_between(start: &u32, end: &u32) -> Option<usize>
fn steps_between(start: &u32, end: &u32) -> Option<usize>
step_trait
)sourceimpl Step for isize
impl Step for isize
sourceunsafe fn forward_unchecked(start: isize, n: usize) -> isize
unsafe fn forward_unchecked(start: isize, n: usize) -> isize
step_trait
)sourceunsafe fn backward_unchecked(start: isize, n: usize) -> isize
unsafe fn backward_unchecked(start: isize, n: usize) -> isize
step_trait
)sourcefn forward(start: isize, n: usize) -> isize
fn forward(start: isize, n: usize) -> isize
step_trait
)sourcefn backward(start: isize, n: usize) -> isize
fn backward(start: isize, n: usize) -> isize
step_trait
)sourcefn steps_between(start: &isize, end: &isize) -> Option<usize>
fn steps_between(start: &isize, end: &isize) -> Option<usize>
step_trait
)sourceimpl Step for i8
impl Step for i8
sourceunsafe fn forward_unchecked(start: i8, n: usize) -> i8
unsafe fn forward_unchecked(start: i8, n: usize) -> i8
step_trait
)sourceunsafe fn backward_unchecked(start: i8, n: usize) -> i8
unsafe fn backward_unchecked(start: i8, n: usize) -> i8
step_trait
)sourcefn steps_between(start: &i8, end: &i8) -> Option<usize>
fn steps_between(start: &i8, end: &i8) -> Option<usize>
step_trait
)sourceimpl Step for u16
impl Step for u16
sourceunsafe fn forward_unchecked(start: u16, n: usize) -> u16
unsafe fn forward_unchecked(start: u16, n: usize) -> u16
step_trait
)sourceunsafe fn backward_unchecked(start: u16, n: usize) -> u16
unsafe fn backward_unchecked(start: u16, n: usize) -> u16
step_trait
)sourcefn forward(start: u16, n: usize) -> u16
fn forward(start: u16, n: usize) -> u16
step_trait
)sourcefn backward(start: u16, n: usize) -> u16
fn backward(start: u16, n: usize) -> u16
step_trait
)sourcefn steps_between(start: &u16, end: &u16) -> Option<usize>
fn steps_between(start: &u16, end: &u16) -> Option<usize>
step_trait
)