Commit Graph

120179 Commits

Author SHA1 Message Date
Chris Denton 2fd504ce2f Suggest installing VS Build Tools in more situations
When MSVC's `link.exe` wasn't found but another `link.exe` was, the error message given can be impenetrable to many users. The usual suspect is GNU's `link` tool. In this case, inform the user that they may need to install VS build tools.

This only applies when Microsoft's link tool is expected. Not `lld-link` or other MSVC compatible linkers.
2020-05-20 15:04:11 +01:00
bors 7faeae0d38 Auto merge of #72135 - oli-obk:const_prop_deaggregates, r=wesleywiser
Propagate locals, even if they have unpropagatable assignments somewhere

Second try for https://github.com/rust-lang/rust/pull/71946#discussion_r422967292

r? @wesleywiser

cc @rust-lang/wg-mir-opt @RalfJung
2020-05-17 09:18:12 +00:00
bors e7f230dfd2 Auto merge of #72208 - tmandry:fix-fuchsia-solink, r=Mark-Simulacrum
Don't pass --dynamic-linker for Fuchsia dylibs

This was causing a PT_INTERP header in Fuchsia dylibs (implying that
they're executable when they're not).

r? @Mark-Simulacrum
cc @frobtech @petrhosek
2020-05-17 05:58:54 +00:00
Wesley Wiser 27c818bc56 Bless mir-opt tests to account for #72220 2020-05-16 22:13:50 -04:00
bors 09739c22db Auto merge of #72286 - Dylan-DPC:rollup-n3rk6df, r=Dylan-DPC
Rollup of 4 pull requests

Successful merges:

 - #72233 (Fix {:#?} representation of proc_macro::Literal)
 - #72277 (emphasize that ManuallyDrop is safe-to-access and unsafe-to-drop)
 - #72281 (Fix whitespace in `?Sized` structured suggestion)
 - #72282 (Fix issue number typo in note)

Failed merges:

r? @ghost
2020-05-17 01:31:15 +00:00
Dylan DPC 1d09a7b693 Rollup merge of #72282 - jonas-schievink:issue-typo, r=Dylan-DPC
Fix issue number typo in note
2020-05-17 01:51:35 +02:00
Dylan DPC 770b1f35de Rollup merge of #72281 - estebank:fix-ws-sugg, r=Dylan-DPC
Fix whitespace in `?Sized` structured suggestion
2020-05-17 01:51:33 +02:00
Dylan DPC 444f449d10 Rollup merge of #72277 - RalfJung:manually-drop-docs, r=Mark-Simulacrum
emphasize that ManuallyDrop is safe-to-access and unsafe-to-drop

This seems to sometimes confused people, and generally seems reasonable to state in the top-level summary of the type.
2020-05-17 01:51:31 +02:00
Dylan DPC fc91043d24 Rollup merge of #72233 - dtolnay:literal, r=petrochenkov
Fix {:#?} representation of proc_macro::Literal

Before:

```rust
TokenStream [
    Ident {
        ident: "name",
        span: #0 bytes(37..41),
    },
    Punct {
        ch: '=',
        spacing: Alone,
        span: #0 bytes(42..43),
    },
    Literal { lit: Lit { kind: Str, symbol: "SNPP", suffix: None }, span: Span { lo: BytePos(44), hi: BytePos(50), ctxt: #0 } },
    Punct {
        ch: ',',
        spacing: Alone,
        span: #0 bytes(50..51),
    },
    Ident {
        ident: "owner",
        span: #0 bytes(56..61),
    },
    Punct {
        ch: '=',
        spacing: Alone,
        span: #0 bytes(62..63),
    },
    Literal { lit: Lit { kind: Str, symbol: "Canary M Burns", suffix: None }, span: Span { lo: BytePos(64), hi: BytePos(80), ctxt: #0 } },
]
```

After:

```rust
TokenStream [
    Ident {
        ident: "name",
        span: #0 bytes(37..41),
    },
    Punct {
        ch: '=',
        spacing: Alone,
        span: #0 bytes(42..43),
    },
    Literal {
        kind: Str,
        symbol: "SNPP",
        suffix: None,
        span: #0 bytes(44..50),
    },
    Punct {
        ch: ',',
        spacing: Alone,
        span: #0 bytes(50..51),
    },
    Ident {
        ident: "owner",
        span: #0 bytes(56..61),
    },
    Punct {
        ch: '=',
        spacing: Alone,
        span: #0 bytes(62..63),
    },
    Literal {
        kind: Str,
        symbol: "Canary M Burns",
        suffix: None,
        span: #0 bytes(64..80),
    },
]
```
2020-05-17 01:51:30 +02:00
bors 0ec4b06524 Auto merge of #72178 - tmiasko:inliner-lifetimes, r=nikic
Consistently use LLVM lifetime markers during codegen

Ensure that inliner inserts lifetime markers if they have been emitted during
codegen. Otherwise if allocas from inlined functions are merged together,
lifetime markers from one function might invalidate load & stores performed
by the other one.

Fixes #72154.
2020-05-16 22:16:48 +00:00
Jonas Schievink 9271f998d1 Fix issue number typo in note 2020-05-16 22:15:37 +02:00
Esteban Küber 47034db851 Fix whitespace in ?Sized structured suggestion 2020-05-16 12:56:21 -07:00
Ralf Jung 993c4480ac emphasize that ManuallyDrop is safe-to-access and unsafe-to-drop 2020-05-16 19:50:09 +02:00
bors dd927a5b0f Auto merge of #72276 - RalfJung:rollup-nkfu3is, r=RalfJung
Rollup of 5 pull requests

Successful merges:

 - #72045 (Incomplete features can also be unsound)
 - #72047 (Literal error reporting cleanup)
 - #72060 (move `ty::List` into a new submodule)
 - #72094 (cmdline: Make target features individually overridable)
 - #72254 (Remove redundant backtick in error message.)

Failed merges:

r? @ghost
2020-05-16 17:47:21 +00:00
Ralf Jung 12112f4d7d Rollup merge of #72254 - ehuss:double-backtick, r=dtolnay
Remove redundant backtick in error message.

The value passed in already has backticks surrounding the text.
2020-05-16 19:46:37 +02:00
Ralf Jung 4fe6d52d97 Rollup merge of #72094 - petrochenkov:overfeature, r=nikic
cmdline: Make target features individually overridable

Fixes https://github.com/rust-lang/rust/issues/56527

Previously `-C target-feature=+avx2 -C target-feature=+fma` was equivalent to `-C target-feature=+fma` because the later `-C target-feature` option fully overridden previous `-C target-feature`.
With this PR `-C target-feature=+avx2 -C target-feature=+fma` is equivalent to `-C target-feature=+avx2,+fma` and the options are combined.

I'm not sure where the comma-separated features in a single option came from (clang uses a scheme with single feature per-option), but logically these features are entirely independent options.
So they should be overridable individually as well to be more useful in hierarchical build system, and more consistent with other rustc options and clang behavior as well.

Target feature options have a few other issues (https://github.com/rust-lang/rust/issues/44815), but fixing those is going to be a bit more invasive.
2020-05-16 19:46:36 +02:00
Ralf Jung ae66c62245 Rollup merge of #72060 - lcnr:move-list, r=estebank
move `ty::List` into a new submodule

`rustc_middle/ty` is currently right below the 3000 lines tidy file length limit.

Moves `rustc_middle::ty::List` to the private module `rustc_middle::ty::list` and adds
a `pub use self::list::List` at its previous location.
2020-05-16 19:46:34 +02:00
Ralf Jung ec5610ff8c Rollup merge of #72047 - Julian-Wollersberger:literal_error_reporting_cleanup, r=petrochenkov
Literal error reporting cleanup

While doing some performance work, I noticed some code duplication in `librustc_parser/lexer/mod.rs`, so I cleaned it up.

This PR is probably best reviewed commit by commit.

I'm not sure what the API stability practices for `librustc_lexer` are. Four public methods in `unescape.rs` can be removed, but two are used by clippy, so I left them in for now.
I could open a PR for Rust-Analyzer when this one lands.

But how do I open a PR for clippy? (Git submodules are frustrating to work with)
2020-05-16 19:46:31 +02:00
Ralf Jung aecab5e603 Rollup merge of #72045 - RalfJung:incomplete-unsound, r=petrochenkov
Incomplete features can also be unsound

Some incomplete features do not just ICE, they are also currently unsound (e.g. https://github.com/rust-lang/rust/pull/72029, and also `specialization` -- which is not yet marked incomplete but [should be](https://github.com/rust-lang/rust/pull/71420)). This makes the message reflect that.

While at it I also added a link to the tracking issue, which hopefully should explain what is incomplete/unsound about the feature.
2020-05-16 19:46:29 +02:00
bors 6163394e1f Auto merge of #72262 - Dylan-DPC:rollup-x56q1jj, r=Dylan-DPC
Rollup of 7 pull requests

Successful merges:

 - #71625 (Improve the documentation for ManuallyDrop to resolve conflicting usage of terminology)
 - #71919 (Update transitive dependency to work towards removing syn <1.0 dep)
 - #72166 (Simpler slice `Iterator` methods)
 - #72216 (Remove `lang_items\(\).*\.unwrap\(\)`)
 - #72230 (Updated documentation of Prefix::VerbatimDisk)
 - #72234 (Implement Default for proc_macro::TokenStream)
 - #72258 (Fix typo Arbintrary to Arbitrary)

Failed merges:

r? @ghost
2020-05-16 14:15:18 +00:00
Dylan DPC e43dd47db2 Rollup merge of #72258 - Rustin-Liu:rustin-patch-typo, r=dtolnay
Fix typo Arbintrary to Arbitrary

Signed-off-by: Rustin-Liu <rustin.liu@gmail.com>

Closes #72122.
2020-05-16 12:43:08 +02:00
Dylan DPC 25c91ea206 Rollup merge of #72234 - dtolnay:default, r=petrochenkov
Implement Default for proc_macro::TokenStream

Hopefully this is uncontroversial. The only reason we've made it this far without is that proc-macro2 snuck this in for their TokenStream.
2020-05-16 12:43:06 +02:00
Dylan DPC 8b1cc10c60 Rollup merge of #72230 - SOF3:patch-1, r=kennytm
Updated documentation of Prefix::VerbatimDisk

PrefixComponent with Prefix::VerbatimDisk does not contain the trailing slash. The documentation here is also inconsistent with the documentation on other variants that reflect the `PrefixComponent::as_os_str()` return value.
2020-05-16 12:43:05 +02:00
Dylan DPC 1be88e6d1e Rollup merge of #72216 - doctorn:require-lang-item, r=lcnr
Remove `lang_items\(\).*\.unwrap\(\)`

Follows up #72170 to remove the remaining uses of `lang_items\(\).*\.unwrap\(\)` (avoids a bunch of potential ICEs when working in `#![no_core]`).

Resolves #72195
2020-05-16 12:43:03 +02:00
Dylan DPC e8f0fb1f13 Rollup merge of #72166 - nnethercote:simpler-slice-Iterator-methods, r=cuviper
Simpler slice `Iterator` methods

These reduce the amount of LLVM IR generated, helping compile times.

r? @cuviper
2020-05-16 12:43:01 +02:00
Dylan DPC 9dd7ad3ed2 Rollup merge of #71919 - Xanewok:bump-syn-1, r=Xanewok
Update transitive dependency to work towards removing syn <1.0 dep

This bumps a couple of transitive dependencies in hopes of eventually not transitively depending on syn <1.0 and friends. The only upstream changes that this is blocked on seems to be https://github.com/mattico/elasticlunr-rs/pull/27 and https://github.com/rust-lang/mdBook/pull/1210.

While working on https://github.com/rust-lang/rust/pull/71875 I noticed we still use syn 0.15 here and there so this is a drive-by PR which aims to help with things a bit.
2020-05-16 12:42:59 +02:00
Dylan DPC 9c32e7ac22 Rollup merge of #71625 - Diggsey:improve-manually-drop-docs, r=RalfJung
Improve the documentation for ManuallyDrop to resolve conflicting usage of terminology

cc @RalfJung

Follow-up from https://github.com/rust-lang/unsafe-code-guidelines/issues/233
2020-05-16 12:42:55 +02:00
bors 31add7e607 Auto merge of #71872 - nnethercote:less-aggressive-arena-growth, r=oli-obk
Be less aggressive with `DroplessArena`/`TypedArena` growth.

`DroplessArena` and `TypedArena` use an aggressive growth strategy: the first chunk is 4 KiB, the second is 8 KiB, and it keeps on doubling indefinitely. DHAT profiles show that sometimes this results in large chunks (e.g. 16-128 MiB) that are barely filled.

This commit changes things so that the doubling stops at 2 MiB. This is large enough that chunk allocations are still rare (you might get 100s instead of 10s of them) but avoids lots of unused space in the worst case. It makes the same change to `TypedArena`, too.
2020-05-16 10:32:46 +00:00
bors 584252bfb0 Auto merge of #71665 - RalfJung:miri-intern-no-ice, r=oli-obk
Miri interning: replace ICEs by proper errors

Fixes https://github.com/rust-lang/rust/issues/71316

I also did some refactoring, as I kept being confused by all the parameters to `intern_shallow`, some of which have invalid combinations (such as a mutable const). So instead `InternMode` now contains all the information that is needed and invalid combinations are ruled out by the type system.

Also I removed interpreter errors from interning. We already ignored almost all errors, and the `ValidationFailure` errors that we handled separately actually cannot ever happen here. The only interpreter failure that was actually reachable was the UB on dangling pointers -- and arguably, a dangling raw pointer is not UB, so the error was not even correct. It's just that the rest of the compiler does not like "dangling" `AllocId`.

It should be possible to review the 3 commits separately.

r? @oli-obk
Cc @rust-lang/wg-const-eval
2020-05-16 07:14:52 +00:00
Rustin-Liu 78eb64f35a Fix typo Arbintrary to Arbitrary
Signed-off-by: Rustin-Liu <rustin.liu@gmail.com>
2020-05-16 14:40:45 +08:00
bors 8453936049 Auto merge of #72079 - semarie:openbsd-stacker, r=Mark-Simulacrum
update stacker to 0.1.9 to unbreak build on OpenBSD

the version 0.1.8 of stacker (what is currently pinned in Cargo.lock) doesn't build on OpenBSD (see https://github.com/rust-lang/stacker/pull/34).

update the version to 0.1.9
2020-05-16 03:55:49 +00:00
Eric Huss 004f4f389e Remove redundant backtick in error message.
The value passed in already has backticks surrounding the text.
2020-05-15 20:51:12 -07:00
bors 163445ac80 Auto merge of #72251 - Dylan-DPC:rollup-4mik3o7, r=Dylan-DPC
Rollup of 9 pull requests

Successful merges:

 - #71662 (Implement FromStr for OsString)
 - #71677 (Add explicit references to the BuildHasher trait)
 - #71724 (Doc alias improvements)
 - #71948 (Suggest to await future before ? operator)
 - #72090 (rustc_driver: factor out computing the exit code)
 - #72206 (Cleanup stale 'FIXME(#64197)')
 - #72218 (make sure even unleashed miri does not do pointer stuff)
 - #72220 ([const-prop] Don't replace Rvalues that are already constants)
 - #72224 (doc: add links to rotate_(left|right))

Failed merges:

r? @ghost
2020-05-16 00:44:57 +00:00
Dylan DPC a27b1b68ed Rollup merge of #72224 - lzutao:links, r=Dylan-DPC
doc: add links to rotate_(left|right)
2020-05-16 02:37:29 +02:00
Dylan DPC 941dfb9545 Rollup merge of #72220 - wesleywiser:const_prop_eval_consts, r=oli-obk
[const-prop] Don't replace Rvalues that are already constants

This cleans up a few mir-opt tests which have slight changes to spans for `consts` as a result of replacing them with new Rvalues.
2020-05-16 02:37:28 +02:00
Dylan DPC 89866ce2c7 Rollup merge of #72218 - RalfJung:test-unleashed-ptrs, r=oli-obk
make sure even unleashed miri does not do pointer stuff

r? @oli-obk
2020-05-16 02:37:26 +02:00
Dylan DPC c1d5640a29 Rollup merge of #72206 - sergey-melnychuk:cleanup-stale-fixme, r=petrochenkov
Cleanup stale 'FIXME(#64197)'

(My first PR in rust-lang, any feedback is welcome. Please don't hesitate to let me know if I'm trying to do something pointless!)

Trivial cleanup of a stale `FIXME`, `StringReader.pos` is no longer exposed. For testing added `pos()` method that returns cloned value of `pos`.
2020-05-16 02:37:24 +02:00
Dylan DPC 040e242168 Rollup merge of #72090 - RalfJung:rustc_driver-exit-code, r=oli-obk
rustc_driver: factor out computing the exit code

In a recent Miri PR I [added a convenience wrapper](https://github.com/rust-lang/miri/pull/1405/files#diff-c3d602c5c8035a16699ce9c015bfeceaR125) around `catch_fatal_errors` and `run_compiler` that @oli-obk suggested I could upstream. However, after seeing what could be shared between `rustc_driver::main`, clippy and Miri, really the only thing I found is computing the exit code -- so that's what this PR does.

What prevents using the Miri convenience function in `rustc_driver::main` and clippy is that they do extra work inside `catch_fatal_errors`, and while I could abstract that away, clippy actually *computes the callbacks* inside there, and I fond no good way to abstract that and thus gave up. Maybe the clippy thing could be moved out, I am not sure if it ever can actually raise a `FatalErrorMarker` -- someone more knowledgeable in clippy would have to do that.
2020-05-16 02:37:23 +02:00
Dylan DPC badcf267df Rollup merge of #71948 - csmoe:issue-61076, r=oli-obk
Suggest to await future before ? operator

Closes https://github.com/rust-lang/rust/issues/71811
cc #61076
2020-05-16 02:37:21 +02:00
Dylan DPC 154db50d86 Rollup merge of #71724 - GuillaumeGomez:doc-alias-improvements, r=ollie27
Doc alias improvements

After [this message](https://github.com/rust-lang/rust/issues/50146#issuecomment-496601755), I realized that the **doc alias**. So this PR does the followings:

 * Align the alias discovery on items added into the search-index. It brings a few nice advantages:
   * Instead of cloning the data between the two (in rustdoc source code), we now have the search-index one and aliases which reference to the first one. So we go from one big map containing a lot of duplicated data to just integers...
 * In the front-end (main.js), I improved the code around aliases to allow them to go through the same transformation as other items when we show the search results.
 * Improve the search tester in order to perform multiple requests into one file (I think it's better in this case than having a file for each case considering how many there are...)
    * I also had to add the new function inside the tester (`handleAliases`)

Once this PR is merged, I intend to finally stabilize this feature.

r? @ollie27

cc @rust-lang/rustdoc
2020-05-16 02:37:19 +02:00
Dylan DPC 21d58a1d31 Rollup merge of #71677 - Mark-Simulacrum:hasher-docs, r=Amanieu
Add explicit references to the BuildHasher trait

Fixes #71652
2020-05-16 02:37:14 +02:00
Dylan DPC 86f48c5311 Rollup merge of #71662 - glandium:osstring_from_str, r=sfackler
Implement FromStr for OsString
2020-05-16 02:37:07 +02:00
Diggory Blake 7433c4ddf3 Improve the documentation for ManuallyDrop to resolve conflicting usage of terminology. 2020-05-15 19:53:05 +01:00
David Tolnay bea2c59ea5 Clarify use of format_args in Debug for Literal 2020-05-15 09:35:46 -07:00
David Tolnay d5ea925265 Implement Default for proc_macro::TokenStream 2020-05-15 09:12:41 -07:00
David Tolnay 4c4b4c4ab4 Add test of proc_macro::TokenStream's Debug 2020-05-15 09:04:00 -07:00
David Tolnay 45ee336007 Fix {:#?} representation of proc_macro::Literal
Before:

    TokenStream [
        Ident {
            ident: "name",
            span: #0 bytes(37..41),
        },
        Punct {
            ch: '=',
            spacing: Alone,
            span: #0 bytes(42..43),
        },
        Literal { lit: Lit { kind: Str, symbol: "SNPP", suffix: None }, span: Span { lo: BytePos(44), hi: BytePos(50), ctxt: #0 } },
        Punct {
            ch: ',',
            spacing: Alone,
            span: #0 bytes(50..51),
        },
        Ident {
            ident: "owner",
            span: #0 bytes(56..61),
        },
        Punct {
            ch: '=',
            spacing: Alone,
            span: #0 bytes(62..63),
        },
        Literal { lit: Lit { kind: Str, symbol: "Canary M Burns", suffix: None }, span: Span { lo: BytePos(64), hi: BytePos(80), ctxt: #0 } },
    ]

After:

    TokenStream [
        Ident {
            ident: "name",
            span: #0 bytes(37..41),
        },
        Punct {
            ch: '=',
            spacing: Alone,
            span: #0 bytes(42..43),
        },
        Literal {
            kind: Str,
            symbol: "SNPP",
            suffix: None,
            span: #0 bytes(44..50),
        },
        Punct {
            ch: ',',
            spacing: Alone,
            span: #0 bytes(50..51),
        },
        Ident {
            ident: "owner",
            span: #0 bytes(56..61),
        },
        Punct {
            ch: '=',
            spacing: Alone,
            span: #0 bytes(62..63),
        },
        Literal {
            kind: Str,
            symbol: "Canary M Burns",
            suffix: None,
            span: #0 bytes(64..80),
        },
    ]
2020-05-15 08:36:33 -07:00
SOFe 084cdde976 Updated documentation of Prefix::VerbatimDisk
PrefixComponent with Prefix::VerbatimDisk does not contain the trailing slash. The documentation here is also inconsistent with the documentation on other variants that reflect the `PrefixComponent::as_os_str()` return value.
2020-05-15 22:41:36 +08:00
Nathan Corbyn 00268be9da Remove lang_items\(\).*\.unwrap\(\) 2020-05-15 12:31:12 +01:00
bors ed084b0b83 Auto merge of #69659 - CAD97:step-rework-take-3, r=Amanieu
Rework the std::iter::Step trait

Previous attempts: #43127 #62886 #68807
Tracking issue: #42168

This PR reworks the `Step` trait to be phrased in terms of the *successor* and *predecessor* operations. With this, `Step` hopefully has a consistent identity that can have a path towards stabilization. The proposed trait:

```rust
/// 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 fulful the listed obligations.
pub unsafe trait Step: Clone + PartialOrd + Sized {
    /// 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(&a, n) == Some(b)`
    /// * `steps_between(&a, &b) == Some(n)` if and only if `Step::backward(&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 steps_between(start: &Self, end: &Self) -> Option<usize>;

    /// 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 forward_checked(start: Self, count: usize) -> Option<Self>;

    /// 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`
    fn forward(start: Self, count: usize) -> Self {
        Step::forward_checked(start, count).expect("overflow in `Step::forward`")
    }

    /// 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)`
    #[unstable(feature = "unchecked_math", reason = "niche optimization path", issue = "none")]
    unsafe fn forward_unchecked(start: Self, count: usize) -> Self {
        Step::forward(start, count)
    }

    /// 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)`
    fn backward_checked(start: Self, count: usize) -> Option<Self>;

    /// 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`
    fn backward(start: Self, count: usize) -> Self {
        Step::backward_checked(start, count).expect("overflow in `Step::backward`")
    }

    /// 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)`
    #[unstable(feature = "unchecked_math", reason = "niche optimization path", issue = "none")]
    unsafe fn backward_unchecked(start: Self, count: usize) -> Self {
        Step::backward(start, count)
    }
}
```

Note that all of these are associated functions and not callable via method syntax; the calling syntax is always `Step::forward(start, n)`. This version of the trait additionally changes the stepping functions to talk their arguments by value.

As opposed to previous attempts which provided a "step by one" method directly, this version of the trait only exposes "step by n". There are a few reasons for this:

- `Range*`, the primary consumer of `Step`, assumes that the "step by n" operation is cheap. If a single step function is provided, it will be a lot more enticing to implement "step by n" as n repeated calls to "step by one". While this is not strictly incorrect, this behavior would be surprising for anyone used to using `Range<{primitive integer}>`.
- With a trivial default impl, this can be easily added backwards-compatibly later.
- The debug-wrapping "step by n" needs to exist for `RangeFrom` to be consistent between "step by n" and "step by one" operation. (Note: the behavior is not changed by this PR, but making the behavior consistent is made tenable by this PR.)

Three "kinds" of step are provided: `_checked`, which returns an `Option` indicating attempted overflow; (unsuffixed), which provides "safe overflow" behavior (is allowed to panic, wrap, or saturate, depending on what is most convenient for a given type); and `_unchecked`, which is a version which assumes overflow does not happen.

Review is appreciated to check that:

- The invariants as described on the `Step` functions are enough to specify the "common sense" consistency for successor/predecessor.
- Implementation of `Step` functions is correct in the face of overflow and the edges of representable integers.
- Added tests of `Step` functions are asserting the correct behavior (and not just the implemented behavior).
2020-05-15 11:24:50 +00:00