🔬 This is a nightly-only experimental API. (step_trait
)
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.
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.
fn steps_between(start: &Self, end: &Self) -> Option<usize>
🔬 This is a nightly-only experimental API. (step_trait
)
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).
For any a
, b
, and n
:
steps_between(&a, &b) == Some(n)
if and only if Step::forward_checked(&a, n) == Some(b)
steps_between(&a, &b) == Some(n)
if and only if Step::backward_checked(&a, n) == Some(a)
steps_between(&a, &b) == Some(n)
only if a <= b
- Corollary:
steps_between(&a, &b) == Some(0)
if and only if a == b
- Note that
a <= b
does not imply steps_between(&a, &b) != None
;
this is the case when it would require more than usize::MAX
steps to get to b
steps_between(&a, &b) == None
if a > b
🔬 This is a nightly-only experimental API. (step_trait_ext
)
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
.
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)
🔬 This is a nightly-only experimental API. (step_trait_ext
)
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
.
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)
Loading content...fn forward(start: Self, count: usize) -> Self
🔬 This is a nightly-only experimental API. (step_trait_ext
)
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.
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
unsafe fn forward_unchecked(start: Self, count: usize) -> Self
🔬 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.
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.
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
.
For any a
and n
, where no overflow occurs:
Step::forward_unchecked(a, n)
is equivalent to Step::forward(a, n)
fn backward(start: Self, count: usize) -> Self
🔬 This is a nightly-only experimental API. (step_trait_ext
)
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.
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
Step::backward(a, n) <= a
Step::forward(Step::backward(a, n), n) == a
unsafe fn backward_unchecked(start: Self, count: usize) -> Self
🔬 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.
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.
For any a
:
- if there exists
b
such that b < a
, it is safe to call Step::backward_unchecked(a, 1)
- if there exists
b
, n
such that steps_between(&b, &a) == Some(n)
,
it is safe to call Step::backward_unchecked(a, m)
for any m <= n
.
For any a
and n
, where no overflow occurs:
Step::backward_unchecked(a, n)
is equivalent to Step::backward(a, n)
Loading content...impl Step for char
[src]
🔬 This is a nightly-only experimental API. (step_trait
)
recently redesigned
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
unsafe fn forward_unchecked(start: char, count: usize) -> char
[src]
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
impl Step for i8
[src]
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
fn forward(start: i8, n: usize) -> i8
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
fn backward(start: i8, n: usize) -> i8
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait
)
recently redesigned
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
impl Step for i16
[src]
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
fn forward(start: i16, n: usize) -> i16
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
fn backward(start: i16, n: usize) -> i16
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait
)
recently redesigned
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
impl Step for i32
[src]
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
fn forward(start: i32, n: usize) -> i32
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
fn backward(start: i32, n: usize) -> i32
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait
)
recently redesigned
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
impl Step for i64
[src]
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
fn forward(start: i64, n: usize) -> i64
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
fn backward(start: i64, n: usize) -> i64
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait
)
recently redesigned
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
impl Step for i128
[src]
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
fn forward(start: i128, n: usize) -> i128
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
fn backward(start: i128, n: usize) -> i128
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait
)
recently redesigned
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
impl Step for isize
[src]
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
fn forward(start: isize, n: usize) -> isize
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
fn backward(start: isize, n: usize) -> isize
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait
)
recently redesigned
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
impl Step for u8
[src]
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
fn forward(start: u8, n: usize) -> u8
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
fn backward(start: u8, n: usize) -> u8
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait
)
recently redesigned
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
impl Step for u16
[src]
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
fn forward(start: u16, n: usize) -> u16
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
fn backward(start: u16, n: usize) -> u16
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait
)
recently redesigned
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
impl Step for u32
[src]
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
fn forward(start: u32, n: usize) -> u32
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
fn backward(start: u32, n: usize) -> u32
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait
)
recently redesigned
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
impl Step for u64
[src]
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
fn forward(start: u64, n: usize) -> u64
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
fn backward(start: u64, n: usize) -> u64
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait
)
recently redesigned
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
impl Step for u128
[src]
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
fn forward(start: u128, n: usize) -> u128
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
fn backward(start: u128, n: usize) -> u128
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait
)
recently redesigned
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
impl Step for usize
[src]
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
🔬 This is a nightly-only experimental API. (unchecked_math
)
niche optimization path
fn forward(start: usize, n: usize) -> usize
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
fn backward(start: usize, n: usize) -> usize
[src]
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait
)
recently redesigned
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
🔬 This is a nightly-only experimental API. (step_trait_ext
)
recently added
Loading content...