core::iter::Step - Rust
Description: API documentation for the Rust `Step` trait in crate `core`.
Keywords: rust, rustlang, rust-lang, Step

# [−][src]Trait core::iter::Step

    pub unsafe trait Step: Clone + PartialOrd + Sized {
        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 { ... }
    }

🔬 This is a nightly-only experimental API. (`step_trait` #42168)

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.

# Safety

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.

## Required methods

### `fn steps_between(start: &Self, end: &Self) -> Option<usize>`

🔬 This is a nightly-only experimental API. (`step_trait` #42168)

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).

# Invariants

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 wheen it would require more than `usize::MAX` steps to get to `b`
- `steps_between(&a, &b) == None` if `a > b`

### `fn forward_checked(start: Self, count: usize) -> Option<Self>`

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

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`.

# 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)`

### `fn backward_checked(start: Self, count: usize) -> Option<Self>`

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

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`.

# 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)`

Loading content...

## Provided methods

### `fn forward(start: Self, count: usize) -> Self`

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

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.

# 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`
- `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.

# 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 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` #42168)

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.

# 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`
- `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.

# 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 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...

## Implementors

### `impl Step for char`[src]

#### `fn steps_between(start: &char, end: &char) -> Option<usize>`[src]

🔬 This is a nightly-only experimental API. (`step_trait` #42168)

recently redesigned

#### `fn forward_checked(start: char, count: usize) -> Option<char>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward_checked(start: char, count: usize) -> Option<char>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `unsafe fn forward_unchecked(start: char, count: usize) -> char`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `unsafe fn backward_unchecked(start: char, count: usize) -> char`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

### `impl Step for i8`[src]

#### `unsafe fn forward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `unsafe fn backward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `fn forward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn steps_between(start: &Self, end: &Self) -> Option<usize>`[src]

🔬 This is a nightly-only experimental API. (`step_trait` #42168)

recently redesigned

#### `fn forward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

### `impl Step for i16`[src]

#### `unsafe fn forward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `unsafe fn backward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `fn forward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn steps_between(start: &Self, end: &Self) -> Option<usize>`[src]

🔬 This is a nightly-only experimental API. (`step_trait` #42168)

recently redesigned

#### `fn forward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

### `impl Step for i32`[src]

#### `unsafe fn forward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `unsafe fn backward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `fn forward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn steps_between(start: &Self, end: &Self) -> Option<usize>`[src]

🔬 This is a nightly-only experimental API. (`step_trait` #42168)

recently redesigned

#### `fn forward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

### `impl Step for i64`[src]

#### `unsafe fn forward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `unsafe fn backward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `fn forward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn steps_between(start: &Self, end: &Self) -> Option<usize>`[src]

🔬 This is a nightly-only experimental API. (`step_trait` #42168)

recently redesigned

#### `fn forward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

### `impl Step for i128`[src]

#### `unsafe fn forward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `unsafe fn backward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `fn forward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn steps_between(start: &Self, end: &Self) -> Option<usize>`[src]

🔬 This is a nightly-only experimental API. (`step_trait` #42168)

recently redesigned

#### `fn forward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

### `impl Step for isize`[src]

#### `unsafe fn forward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `unsafe fn backward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `fn forward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn steps_between(start: &Self, end: &Self) -> Option<usize>`[src]

🔬 This is a nightly-only experimental API. (`step_trait` #42168)

recently redesigned

#### `fn forward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

### `impl Step for u8`[src]

#### `unsafe fn forward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `unsafe fn backward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `fn forward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn steps_between(start: &Self, end: &Self) -> Option<usize>`[src]

🔬 This is a nightly-only experimental API. (`step_trait` #42168)

recently redesigned

#### `fn forward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

### `impl Step for u16`[src]

#### `unsafe fn forward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `unsafe fn backward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `fn forward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn steps_between(start: &Self, end: &Self) -> Option<usize>`[src]

🔬 This is a nightly-only experimental API. (`step_trait` #42168)

recently redesigned

#### `fn forward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

### `impl Step for u32`[src]

#### `unsafe fn forward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `unsafe fn backward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `fn forward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn steps_between(start: &Self, end: &Self) -> Option<usize>`[src]

🔬 This is a nightly-only experimental API. (`step_trait` #42168)

recently redesigned

#### `fn forward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

### `impl Step for u64`[src]

#### `unsafe fn forward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `unsafe fn backward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `fn forward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn steps_between(start: &Self, end: &Self) -> Option<usize>`[src]

🔬 This is a nightly-only experimental API. (`step_trait` #42168)

recently redesigned

#### `fn forward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

### `impl Step for u128`[src]

#### `unsafe fn forward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `unsafe fn backward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `fn forward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn steps_between(start: &Self, end: &Self) -> Option<usize>`[src]

🔬 This is a nightly-only experimental API. (`step_trait` #42168)

recently redesigned

#### `fn forward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

### `impl Step for usize`[src]

#### `unsafe fn forward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `unsafe fn backward_unchecked(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`unchecked_math`)

niche optimization path

#### `fn forward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward(start: Self, n: usize) -> Self`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn steps_between(start: &Self, end: &Self) -> Option<usize>`[src]

🔬 This is a nightly-only experimental API. (`step_trait` #42168)

recently redesigned

#### `fn forward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

#### `fn backward_checked(start: Self, n: usize) -> Option<Self>`[src]

🔬 This is a nightly-only experimental API. (`step_trait_ext` #42168)

recently added

Loading content...