Fix documentation for `Iterator::count()`.
The documentation of std::core::Iterator::count() stated that the number returned is the number of times `next` is called on the iterator. However this is not true as the number of times `next` is called is exactly one plus the number returned by `count()`.
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
