Have tidy ensure that we document all `unsafe` blocks in libcore
cc @rust-lang/libs
I documented a few and added ignore flags on the other files. We can incrementally document the files, but won't regress any files this way.
Add future incompatibility lint for `array.into_iter()`
This is for #65819. This lint warns when calling `into_iter` on an array directly. That's because today the method call resolves to `<&[T] as IntoIterator>::into_iter` but that would change when adding `IntoIterator` impls for arrays. This problem is discussed in detail in #65819.
We still haven't decided how to proceed exactly, but it seems like adding a lint is a good idea regardless?
Also: this is the first time I implement a lint, so there are probably a lot of things I can improve. I used a different strategy than @scottmcm describes [here](https://github.com/rust-lang/rust/pull/65819#issuecomment-548667847) since I already started implementing this before they commented.
### TODO
- [x] Decide if we want this lint -> apparently [we want](https://github.com/rust-lang/rust/pull/65819#issuecomment-548964818)
- [x] Open a lint-tracking-issue and add the correct issue number in the code -> https://github.com/rust-lang/rust/issues/66145
As we might want to add `IntoIterator` impls for arrays in the future,
and since that introduces a breaking change, this lint warns and
suggests using `iter()` instead (which is shorter and more explicit).
Improved std::iter::Chain documentation
Replaces `strings two iterators` by `links two iterators` in `std::iter::Chain` documentation.
I didn't find any meaning of `strings` which can be evaluated as `links` or `joins`.
I don't think that `std::iter:Chain` works as a stringer or plays billiards. (https://www.lexico.com/en/definition/string).
Document the unstable iter_order_by library feature
Tracking issue: #64295
Follow-up for: #62205
References the tracking issue and adds a page to the unstable book for the new unstable `iter_order_by` feature.
Add `cmp::{min_by, min_by_key, max_by, max_by_key}`
This adds the following functions to `core::cmp`:
- `min_by`
- `min_by_key`
- `max_by`
- `max_by_key`
`min_by` and `max_by` are somewhat trivial to implement, but not entirely because `min_by` returns the first value in case the two are equal (and `max_by` the second). `min` and `max` can be implemented in terms of `min_by` and `max_by`, but not as easily the other way around.
To give an example of why I think these functions could be useful: the `Iterator::{min_by, min_by_key, max_by, max_by_key}` methods all currently hard-code the behavior mentioned above which is an ever so small duplication of logic. If we delegate them to `cmp::{min_by, max_by}` methods instead, we get the correct behavior for free. (edit: this is now included in the PR)
I added `min_by_key` / `max_by_key` for consistency's sake but I wouldn't mind removing them. I don't have a particular use case in mind for them, and `min_by` / `max_by` seem to be more useful.
Tracking issue: #64460
Override `StepBy::{try_fold, try_rfold}`
Previous PR: https://github.com/rust-lang/rust/pull/51435
The previous PR was closed in favor of https://github.com/rust-lang/rust/pull/51601, which was later reverted. I don't think these implementations will make it harder to specialize `StepBy<Range<_>>` later, so we should be able to land this without any consequences.
This should fix https://github.com/rust-lang/rust/issues/57517 – in my benchmarks `iter` and `iter.step_by(1)` now perform equally well, provided internal iteration is used.
Because of a compiler bug that adding `Self: ExactSizeIterator` makes
the compiler forget `Self::Item` is `<I as Iterator>::Item`, we remove
this specialization for now.
Override Cycle::try_fold
It's not very pretty, but I believe this is the simplest way to correctly implement `Cycle::try_fold`. The following may seem correct:
```rust
loop {
acc = self.iter.try_fold(acc, &mut f)?;
self.iter = self.orig.clone();
}
```
...but this loops infinitely in case `self.orig` is empty, as opposed to returning `acc`. So we first have to fully iterate `self.orig` to check whether it is empty or not, and before _that_, we have to iterate the remaining elements of `self.iter`.
This should always call `self.orig.clone()` the same amount of times as repeated `next()` calls would.
r? @scottmcm
By default, closures inherit the generic parameters of their scope,
including `Self`. However, in most cases, the closures used to implement
iterators don't need to be generic on the iterator type, only its `Item`
type. We can reduce this genericity by redirecting such closures through
local functions.
This does make the closures more cumbersome to write, but it will
hopefully reduce duplication in their monomorphizations, as well as
their related type lengths.
