Skip to content

Commit

Permalink
Rollup merge of #122421 - CAD97:step-trait-docs, r=jhpratt
Browse files Browse the repository at this point in the history
Improve `Step` docs

It [came up on urlo](https://users.rust-lang.org/t/implement-trait-step-in-1-76-0/108204?u=cad97) that the unstable reason string isn't helpful, so just remove it; there's nothing meaningful to add here.

Also makes a couple drive-by improvements to the method docs -- removes incorrect references, changes `forward_checked`'s invariant formulation to match `backward_checked`'s, and adds a helpful corollary that `step_unchecked(a, 0)` is always safe.
  • Loading branch information
matthiaskrgr authored Mar 14, 2024
2 parents 0286591 + c527ec7 commit a0e50a4
Showing 1 changed file with 7 additions and 8 deletions.
15 changes: 7 additions & 8 deletions library/core/src/iter/range.rs
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ unsafe_impl_trusted_step![AsciiChar char i8 i16 i32 i64 i128 isize u8 u16 u32 u6
///
/// The *successor* operation moves towards values that compare greater.
/// The *predecessor* operation moves towards values that compare lesser.
#[unstable(feature = "step_trait", reason = "recently redesigned", issue = "42168")]
#[unstable(feature = "step_trait", issue = "42168")]
pub trait Step: Clone + PartialOrd + Sized {
/// Returns the number of *successor* steps required to get from `start` to `end`.
///
Expand Down Expand Up @@ -52,15 +52,12 @@ pub trait Step: Clone + PartialOrd + Sized {
/// 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)`
/// * `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)`
/// * Corollary: `Step::forward_checked(a, 0) == Some(a)`
fn forward_checked(start: Self, count: usize) -> Option<Self>;

/// Returns the value that would be obtained by taking the *successor*
Expand Down Expand Up @@ -106,6 +103,7 @@ pub trait Step: Clone + PartialOrd + Sized {
/// * 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:
///
Expand All @@ -128,8 +126,8 @@ pub trait Step: Clone + PartialOrd + Sized {
///
/// 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)`
/// * `Step::backward_checked(a, n) == (0..n).try_fold(a, |x, _| Step::backward_checked(x, 1))`
/// * Corollary: `Step::backward_checked(a, 0) == Some(a)`
fn backward_checked(start: Self, count: usize) -> Option<Self>;

/// Returns the value that would be obtained by taking the *predecessor*
Expand Down Expand Up @@ -175,6 +173,7 @@ pub trait Step: Clone + PartialOrd + Sized {
/// * 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`.
/// * Corollary: `Step::backward_unchecked(a, 0)` is always safe.
///
/// For any `a` and `n`, where no overflow occurs:
///
Expand Down

0 comments on commit a0e50a4

Please sign in to comment.