Update README.md

See merge request !1

Rollup of 7 pull requests

Successful merges:

 - #80845 (Make ItemKind::ExternCrate looks like hir::ItemKind::ExternCrate to make transition over hir::ItemKind simpler)
 - #82708 (Warn on `#![doc(test(...))]` on items other than the crate root and use future incompatible lint)
 - #82714 (Detect match arm body without braces)
 - #82736 (Bump optimization from mir_opt_level 2 to 3 and 3 to 4 and make "release" be level 2 by default)
 - #82782 (Make rustc shim's verbose output include crate_name being compiled.)
 - #82797 (Update tests names to start with `issue-`)
 - #82809 (rustdoc: Use substrings instead of split to grab enum variant paths)

Failed merges:

r? `@ghost`
`@rustbot` modify labels: rollup

rustdoc: Use substrings instead of split to grab enum variant paths

Both versions are about equally readable, but this version avoids scanning the entire path and building an intermediate array (`split()` in Rust is a lazy iterator, but not in JavaScript).

Update tests names to start with `issue-`

See ``@JohnTitor's`` [comment](https://github.com/rust-lang/rust/pull/82720#discussion_r586488083)

``@rustbot`` label +C-cleanup

Rollup merge of #82782 - pnkfelix:include-crate-being-compiled-in-bootstrap-verbose-output, r=Mark-Simulacrum

Make rustc shim's verbose output include crate_name being compiled.

This change is mainly motivated by an issue with the environment printing I added in PR 82403: multiple rustc invocations progress in parallel, and the environment output, spanning multiple lines, gets interleaved in ways make it difficult to extra the enviroment settings.

(This aforementioned difficulty is more of a hiccup than an outright show-stopper, because the environment variables tend to be the same for all of the rustc invocations, so it doesn't matter too much if one mixes up which lines one is looking at. But still: Better to fix it.)

Bump optimization from mir_opt_level 2 to 3 and 3 to 4 and make "release" be level 2 by default

r? `@oli-obk`

Detect match arm body without braces

Fix #82524.

Warn on `#![doc(test(...))]` on items other than the crate root and use future incompatible lint

Part of #82672.

This PR does multiple things:
 * Create a new `INVALID_DOC_ATTRIBUTE` lint which is also "future incompatible", allowing us to use it as a warning for the moment until it turns (eventually) into a hard error.
 * Use this link when `#![doc(test(...))]` isn't used at the crate level.
 * Make #82702 use this new lint as well.

r? ``@jyn514``

Make ItemKind::ExternCrate looks like hir::ItemKind::ExternCrate to make transition over hir::ItemKind simpler

It was surprisingly difficult to make this change, mostly because of two issues:

* We now store the `ExternCrate` name in the parent struct (`clean::Item`), which forced me to modify the json conversion code a bit more than expected.
* The second problem was that, since we now have a `Some(name)`, it was trying to render it, ending up in a panic because we ended up in a `unreachable` statement. The solution was simply to add `!item.is_extern_crate()` in `formats::renderer` before calling `cx.item(item, &cache)?;`.

I'll continue to replace all the `clean::ItemKind` variants one by one until it looks exactly like `hir::ItemKind`. Then we'll simply discard the rustdoc type. Once this done, we'll be able to discard `clean::Item` too to use `hir::Item`.

r? ``@jyn514``

Improve slice.binary_search_by()'s best-case performance to O(1)

This PR aimed to improve the [slice.binary_search_by()](https://doc.rust-lang.org/std/primitive.slice.html#method.binary_search_by)'s best-case performance to O(1).

# Noticed

I don't know why the docs of `binary_search_by` said `"If there are multiple matches, then any one of the matches could be returned."`, but the implementation isn't the same thing. Actually, it returns the **last one** if multiple matches found.

Then we got two options:

## If returns the last one is the correct or desired result

Then I can rectify the docs and revert my changes.

## If the docs are correct or desired result

Then my changes can be merged after fully reviewed.

However, if my PR gets merged, another issue raised: this could be a **breaking change** since if multiple matches found, the returning order no longer the last one instead of it could be any one.

For example:
```rust
let mut s = vec![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
let num = 1;
let idx = s.binary_search(&num);
s.insert(idx, 2);

// Old implementations
assert_eq!(s, [0, 1, 1, 1, 1, 2, 2, 3, 5, 8, 13, 21, 34, 42, 55]);

// New implementations
assert_eq!(s, [0, 1, 1, 1, 2, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55]);
```

# Benchmarking

**Old implementations**
```sh
$ ./x.py bench --stage 1 library/libcore
test slice::binary_search_l1           ... bench:          59 ns/iter (+/- 4)
test slice::binary_search_l1_with_dups ... bench:          59 ns/iter (+/- 3)
test slice::binary_search_l2           ... bench:          76 ns/iter (+/- 5)
test slice::binary_search_l2_with_dups ... bench:          77 ns/iter (+/- 17)
test slice::binary_search_l3           ... bench:         183 ns/iter (+/- 23)
test slice::binary_search_l3_with_dups ... bench:         185 ns/iter (+/- 19)
```

**New implementations (1)**

Implemented by this PR.
```rust
if cmp == Equal {
    return Ok(mid);
} else if cmp == Less {
    base = mid
}
```
```sh
$ ./x.py bench --stage 1 library/libcore
test slice::binary_search_l1           ... bench:          58 ns/iter (+/- 2)
test slice::binary_search_l1_with_dups ... bench:          37 ns/iter (+/- 4)
test slice::binary_search_l2           ... bench:          76 ns/iter (+/- 3)
test slice::binary_search_l2_with_dups ... bench:          57 ns/iter (+/- 6)
test slice::binary_search_l3           ... bench:         200 ns/iter (+/- 30)
test slice::binary_search_l3_with_dups ... bench:         157 ns/iter (+/- 6)

$ ./x.py bench --stage 1 library/libcore
test slice::binary_search_l1           ... bench:          59 ns/iter (+/- 8)
test slice::binary_search_l1_with_dups ... bench:          37 ns/iter (+/- 2)
test slice::binary_search_l2           ... bench:          77 ns/iter (+/- 2)
test slice::binary_search_l2_with_dups ... bench:          57 ns/iter (+/- 2)
test slice::binary_search_l3           ... bench:         198 ns/iter (+/- 21)
test slice::binary_search_l3_with_dups ... bench:         158 ns/iter (+/- 11)

```

**New implementations (2)**

Suggested by `@nbdd0121` in [comment](https://github.com/rust-lang/rust/pull/74024#issuecomment-665430239).
```rust
base = if cmp == Greater { base } else { mid };
if cmp == Equal { break }
```

```sh
$ ./x.py bench --stage 1 library/libcore
test slice::binary_search_l1           ... bench:          59 ns/iter (+/- 7)
test slice::binary_search_l1_with_dups ... bench:          37 ns/iter (+/- 5)
test slice::binary_search_l2           ... bench:          75 ns/iter (+/- 3)
test slice::binary_search_l2_with_dups ... bench:          56 ns/iter (+/- 3)
test slice::binary_search_l3           ... bench:         195 ns/iter (+/- 15)
test slice::binary_search_l3_with_dups ... bench:         151 ns/iter (+/- 7)

$ ./x.py bench --stage 1 library/libcore
test slice::binary_search_l1           ... bench:          57 ns/iter (+/- 2)
test slice::binary_search_l1_with_dups ... bench:          38 ns/iter (+/- 2)
test slice::binary_search_l2           ... bench:          77 ns/iter (+/- 11)
test slice::binary_search_l2_with_dups ... bench:          57 ns/iter (+/- 4)
test slice::binary_search_l3           ... bench:         194 ns/iter (+/- 15)
test slice::binary_search_l3_with_dups ... bench:         151 ns/iter (+/- 18)

```

I run some benchmarking testings against on two implementations. The new implementation has a lot of improvement in duplicates cases, while in `binary_search_l3` case, it's a little bit slower than the old one.

Both versions are about equally readable, but this version avoids scanning
the entire path and building an intermediate array (`split()` in Rust is
a lazy iterator, but not in JavaScript).

1. I added `--test` based on review feedback from simulacrum: I decided I would
rather include such extra context than get confused later on by its absence.
(However, I chose to encode it differently than how `[RUSTC-TIMING]` does... I
don't have much basis for doing so, other than `--test` to me more directly
reflects what it came from.)

2. I also decided to include `[RUSTC-SHIM]` at start of all of these lines
driven by the verbosity level, to make to clear where these lines of text
originate from. (Basically, I skimmed over the output and realized that a casual
observer might not be able to tell where this huge set of new lines were coming
from.)

Make ItemKind::ExternCrate looks like hir::ItemKind::ExternCrate to make transition over hir::ItemKind simpler

Rollup of 10 pull requests

Successful merges:

 - #80723 (Implement NOOP_METHOD_CALL lint)
 - #80763 (resolve: Reduce scope of `pub_use_of_private_extern_crate` deprecation lint)
 - #81136 (Improved IO Bytes Size Hint)
 - #81939 (Add suggestion `.collect()` for iterators in iterators)
 - #82289 (Fix underflow in specialized ZipImpl::size_hint)
 - #82728 (Avoid unnecessary Vec construction in BufReader)
 - #82764 (Add {BTreeMap,HashMap}::try_insert)
 - #82770 (Add assert_matches macro.)
 - #82773 (Add diagnostic item to `Default` trait)
 - #82787 (Remove unused code from main.js)

Failed merges:

r? `@ghost`
`@rustbot` modify labels: rollup

See @JohnTitor's [comment](https://github.com/rust-lang/rust/pull/82720#discussion_r586488083)

@rustbot label +C-cleanup

Remove unused code from main.js

It looks like `lev_distance` was used in a very old version of the function, since it was written but never read, and Blame reports that it was added before the `checkGenerics` function header itself.

`convertHTMLToPlaintext` is was removed by 768d5e95

Add diagnostic item to `Default` trait

This PR adds diagnostic item to `Default` trait to be used by rust-lang/rust-clippy#6562 issue.
Also fixes the obsolete path to the `symbols.rs` file in the comment.

Add assert_matches macro.

This adds `assert_matches!(expression, pattern)`.

Unlike the other asserts, this one ~~consumes the expression~~ may consume the expression, to be able to match the pattern. (It could add a `&` implicitly, but that's noticable in the pattern, and will make a consuming guard impossible.)

See https://github.com/rust-lang/rust/issues/62633#issuecomment-790737853

This re-uses the same `left: .. right: ..` output as the `assert_eq` and `assert_ne` macros, but with the pattern as the right part:

assert_eq:
```
assertion failed: `(left == right)`
  left: `Some("asdf")`,
 right: `None`
```
assert_matches:
```
assertion failed: `(left matches right)`
  left: `Ok("asdf")`,
 right: `Err(_)`
```

cc ```@cuviper```

Add {BTreeMap,HashMap}::try_insert

`{BTreeMap,HashMap}::insert(key, new_val)` returns `Some(old_val)` if the key was already in the map. It's often useful to assert no duplicate values are inserted.

We experimented with `map.insert(key, val).unwrap_none()` (https://github.com/rust-lang/rust/issues/62633), but decided that that's not the kind of method we'd like to have on `Option`s.

`insert` always succeeds because it replaces the old value if it exists. One could argue that `insert()` is never the right method for panicking on duplicates, since already handles that case by replacing the value, only allowing you to panic after that already happened.

This PR adds a `try_insert` method that instead returns a `Result::Err` when the key already exists. This error contains both the `OccupiedEntry` and the value that was supposed to be inserted. This means that unwrapping that result gives more context:
```rust
    map.insert(10, "world").unwrap_none();
    // thread 'main' panicked at 'called `Option::unwrap_none()` on a `Some` value: "hello"', src/main.rs:8:29
```

```rust
    map.try_insert(10, "world").unwrap();
    // thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value:
    // OccupiedError { key: 10, old_value: "hello", new_value: "world" }', src/main.rs:6:33
```

It also allows handling the failure in any other way, as you have full access to the `OccupiedEntry` and the value.

`try_insert` returns a reference to the value in case of success, making it an alternative to `.entry(key).or_insert(value)`.

r? ```@Amanieu```

Fixes https://github.com/rust-lang/rfcs/issues/3092

Avoid unnecessary Vec construction in BufReader

As mentioned in #80460, creating a `Vec` and calling `Vec::into_boxed_slice()` emits unnecessary calls to `realloc()` and `free()`. Updated the code to use `Box::new_uninit_slice()` to create a boxed slice directly. I think this also makes it more explicit that the initial contents of the buffer are uninitialized.

r? ``@m-ou-se``

Fix underflow in specialized ZipImpl::size_hint

Fixes #82282

Add suggestion `.collect()` for iterators in iterators

Closes #81584

```
error[E0515]: cannot return value referencing function parameter `y`
 --> main3.rs:4:38
  |
4 | ...                   .map(|y| y.iter().map(|x| x + 1))
  |                                -^^^^^^^^^^^^^^^^^^^^^^
  |                                |
  |                                returns a value referencing data owned by the current function
  |                                `y` is borrowed here
  |                                help: Maybe use `.collect()` to allocate the iterator
```

Added the suggestion: `help: Maybe use `.collect()` to allocate the iterator`