Add documentation for string->Cow conversions

Mostly, it's just to reassure everyone that these functions don't allocate.

Part of #51430

Auto merge of #82795 - m-ou-se:rollup-uzx0b92, r=m-ou-se

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

Rollup merge of #82787 - notriddle:main-js-cleanup, r=GuillaumeGomez

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 768d5e950953738a54480e530341964838d29da2

Rollup merge of #82773 - mgacek8:feature/add_diagnostic_item_to_Default_trait, r=oli-obk

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.

Rollup merge of #82770 - m-ou-se:assert-match, r=joshtriplett

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

Rollup merge of #82764 - m-ou-se:map-try-insert, r=Amanieu

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

Rollup merge of #82728 - calebsander:refactor/bufreader-buf, r=m-ou-se

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

Rollup merge of #82289 - SkiFire13:fix-issue-82282, r=m-ou-se

Fix underflow in specialized ZipImpl::size_hint

Fixes #82282

Rollup merge of #81939 - kper:fixing-81584-allocate-in-iter, r=davidtwco

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`

Rollup merge of #81136 - Xavientois:io_reader_size_hint, r=cramertj

Improved IO Bytes Size Hint

After trying to implement better `size_hint()` return values for `File` in [this PR](https://github.com/rust-lang/rust/pull/81044) and changing to implementing it for `BufReader` in [this PR](https://github.com/rust-lang/rust/pull/81052), I have arrived at this implementation that provides tighter bounds for the `Bytes` iterator of various readers including `BufReader`, `Empty`, and `Chain`.

Unfortunately, for `BufReader`, the size_hint only improves after calling `fill_buffer` due to it using the contents of the buffer for the hint. Nevertheless, the the tighter bounds  should result in better pre-allocation of space to handle the contents of the `Bytes` iterator.

Closes #81052

Rollup merge of #80763 - petrochenkov:pubusecrate, r=estebank

resolve: Reduce scope of `pub_use_of_private_extern_crate` deprecation lint

This lint was deny-by-default since July 2017, crater showed 7 uses on crates.io back then (https://github.com/rust-lang/rust/pull/42894#issuecomment-311921147).

Unfortunately, the construction `pub use foo as bar` where `foo` is `extern crate foo;` was used by an older version `bitflags`, so turning it into an error causes too many regressions.
So, this PR reduces the scope of the lint instead of turning it into a hard error, and only turns some more rarely used components of it into errors.

Rollup merge of #80723 - rylev:noop-lint-pass, r=estebank

Implement NOOP_METHOD_CALL lint

Implements the beginnings of https://github.com/rust-lang/lang-team/issues/67 - a lint for detecting noop method calls (e.g, calling `<&T as Clone>::clone()` when `T: !Clone`).

This PR does not fully realize the vision and has a few limitations that need to be addressed either before merging or in subsequent PRs:
* [ ] No UFCS support
* [ ] The warning message is pretty plain
* [ ] Doesn't work for `ToOwned`

The implementation uses [`Instance::resolve`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/instance/struct.Instance.html#method.resolve) which is normally later in the compiler. It seems that there are some invariants that this function relies on that we try our best to respect. For instance, it expects substitutions to have happened, which haven't yet performed, but we check first for `needs_subst` to ensure we're dealing with a monomorphic type.

Thank you to ```@davidtwco,``` ```@Aaron1011,``` and ```@wesleywiser``` for helping me at various points through out this PR ❤️.

Auto merge of #82777 - GuillaumeGomez:rollup-etcsupl, r=GuillaumeGomez

Rollup of 5 pull requests

Successful merges:

 - #76716 (Don't warn for `missing_doc_examples` when item is #[doc(hidden)])
 - #82088 (Shorten html::render)
 - #82690 (Update rustdoc documentation)
 - #82752 (Add a regression test for issue-81712)
 - #82765 (Fix polymorphization ICE on associated types in trait decls using const generics in bounds)

Failed merges:

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

Auto merge of #71481 - estebank:inherit-stability, r=nikomatsakis

Inherit `#[stable(..)]` annotations in enum variants and fields from its item

Lint changes for #65515. The stdlib will have to be updated once this lands in beta and that version is promoted in master.

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 768d5e950953738a54480e530341964838d29da2

Rollup merge of #82765 - oli-obk:polymorphization_regression, r=davidtwco

Fix polymorphization ICE on associated types in trait decls using const generics in bounds

r? `@davidtwco`

only the last commit actually changes something

Rollup merge of #82752 - JohnTitor:gat-ice-test, r=jackh726

Add a regression test for issue-81712

Fixes #81712, also fixes #79768 as duplicate.
r? `@jackh726`

Rollup merge of #82690 - jyn514:remove-pass-docs, r=Manishearth

Update rustdoc documentation

- Remove most of the information about passes. Passes are deprecated.
- Add `--document-private-items`; it was missing before.
- Update `--output-format json`; it was very outdated.
- Note that `--input-format` is deprecated.
- Move deprecated options to the very end.

Closes https://github.com/rust-lang/rust/issues/82675.

r? `@Manishearth`

Rollup merge of #82088 - Nicholas-Baron:shorten_html_render, r=GuillaumeGomez

Shorten html::render

The `mod.rs` for librustdoc's `html::render` was over 3,000 lines. This PR reduces it to around 2,300 by
1. Moving `Context` and associated `impl`s to a separate file
2. Moving the `print_item` function and its helpers to a separate file
3. Moving `write_shared` and `write_minify` to their own file

Related to issue #60302.
Edit 1: `SharedContext` and related `impl`s is only 72 lines and so will not be moved.

Rollup merge of #76716 - GuillaumeGomez:stop-complains-on-doc-hidden, r=jyn514

Don't warn for `missing_doc_examples` when item is #[doc(hidden)]

r? `@jyn514`

Add tracking issue for assert_matches.

Use cache access levels

No more need for borrow call

Pass TyCtxt directly instead of DocContext in librustdoc::visit_ast::inherits_doc_hidden

Move visibility check inside the should_have_doc_example function

Update missing code example test

Don't warn for `missing_doc_examples` when item is #[doc(hidden)]

Auto merge of #82747 - JohnTitor:pin-es-check-version, r=Mark-Simulacrum

Pin es-check version to prevent unrelated CI failures

es-check v5.2.1 causes a lot of unrelated CI failures on mingw-check, e.g. https://github.com/rust-lang/rust/pull/80723#issuecomment-790294196.
es-check v5.2.2 fixes it but let's pin its version to prevent further failures.

Update rustdoc documentation

- Remove most of the information about passes. Passes are deprecated.
- Add `--document-private-items`; it was missing before.
- Update `--output-format json`; it was very outdated.
- Note that `--input-format` is deprecated.
- Move deprecated options to the very end.
- Move `passes.html` to the end of the table of contents. Ideally it
  would be removed altogether, but that causes mdbook not to generate the
  docs.

Don't consume the expression in assert_matches!()'s failure case.

Corrected imports for render tests and mod files

Due to a rebase, some edits were needed in the mod file.

Moved `write_shared` to its own file

Fix comment with path to `symbols!` macro

Add diagnostic item to `Default` trait

Required to resolve #6562 rust-clippy issue.

Moved the `make_item_keywords` function to `context.rs` as it is only used there

Moved `print_item` and helpers to a separate file

Moved Context and its impls to a separate file

Fix assert_matches doc examples.

Add debug_assert_matches macro.

Allow for multiple patterns and a guard in assert_matches.

Add assert_matches!(expr, pat).

Add tracking issue for map_try_insert.

Remove unnecessary bound from HashMap::try_insert.

Fixes -Zpolymorphize for src/test/ui/const-generics/auxiliary/crayte.rs

Typo

Spread tracing instrumentation into the polymorphization logic

Ignore file length tidy warning in hash/map.rs.

Auto merge of #81451 - nikic:llvm-12, r=nagisa

Upgrade to LLVM 12

This implements the necessary adjustments to make rustc work with LLVM 12. I didn't encounter any major issues so far.

r? `@cuviper`

Implement Error for OccupiedError.

Improve Debug implementations of OccupiedError.

Add HashMap::try_insert and hash_map::OccupiedError.

Add BTreeMap::try_insert and btree_map::OccupiedError.

Remove a dead code path

Auto merge of #82756 - JohnTitor:rollup-e4ij7h6, r=JohnTitor

Rollup of 8 pull requests

Successful merges:

 - #80527 (Make rustdoc lints a tool lint instead of built-in)
 - #82310 (Load rustdoc's JS search index on-demand.)
 - #82315 (Improve page load performance in rustdoc)
 - #82564 (Revert `Vec::spare_capacity_mut` impl to prevent pointers invalidation)
 - #82697 (Fix stabilization version of move_ref_pattern)
 - #82717 (Account for macros when suggesting adding lifetime)
 - #82740 (Fix commit detected when using `download-rustc`)
 - #82744 (Pass `CrateNum` by value instead of by reference)

Failed merges:

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

Rollup merge of #82744 - camelid:cratenum-byval, r=GuillaumeGomez

Pass `CrateNum` by value instead of by reference

It's more idiomatic to pass a small Copy type by value and `CrateNum` is
half the size of `&CrateNum` on 64-bit systems. The memory use change is
almost certainly insignificant, but why not!

Rollup merge of #82740 - jyn514:proper-history, r=Mark-Simulacrum

Fix commit detected when using `download-rustc`

On reflection on the issue in https://github.com/rust-lang/rust/pull/79540#discussion_r572572280, I think the bug was actually using the `compiler/` filter, not using `--author=bors`. https://github.com/rust-lang/rust/commit/9a1d6174c925f54c923599e29b09d6855e6b3a78 has no CI artifacts because it was merged as part of a rollup:
```
$ curl -I https://ci-artifacts.rust-lang.org/rustc-builds/96e843ce6ae42e0aa519ba45e148269de347fd84/rust-std-nightly-x86_64-unknown-linux-gnu.tar.xz
HTTP/2 404
```
So 9a1d6174c925f54c923599e29b09d6855e6b3a78 is the correct commit to download, and that's what `--author=bors` does:

$ git log --author=bors 4aec8a5da5547d6e1c24e99dad0003b7cac107f5
commit 9a1d6174c925f54c923599e29b09d6855e6b3a78

Ideally it would look for "the most recent bors commit not followed by a change to `compiler/`", which would exclude things like documentation changes and avoid redownloading more than necessary, but
- Redownloading isn't the end of the world,
- That metric is hard to implement, and
- Documentation-only or library-only changes are very rare anyway since they're usually rolled up with changes to the compiler.

Helps with https://github.com/rust-lang/rust/issues/81930.

r? `@Mark-Simulacrum`

Rollup merge of #82717 - estebank:issue-70152, r=lcnr

Account for macros when suggesting adding lifetime

Fix #70152.

Rollup merge of #82697 - jplatte:patch-1, r=davidtwco

Fix stabilization version of move_ref_pattern

Both the [changelog](https://github.com/rust-lang/rust/blob/master/RELEASES.md#version-1490-2020-12-31) and the milestone of the [stabilization PR](https://github.com/rust-lang/rust/pull/76119) say 1.49.0, but the source says 1.48.0. I think the former is correct.

Rollup merge of #82564 - WaffleLapkin:revert_spare_mut, r=RalfJung

Revert `Vec::spare_capacity_mut` impl to prevent pointers invalidation

The implementation was changed in #79015.

Later it was [pointed out](https://github.com/rust-lang/rust/issues/81944#issuecomment-782849785) that the implementation invalidates pointers to the buffer (initialized elements) by creating a unique reference to the buffer. This PR reverts the implementation.

r? ```@RalfJung```

Rollup merge of #82315 - jsha:font-display-swap, r=GuillaumeGomez

Improve page load performance in rustdoc

Add an explicit height to icons (which already had an explicit width) to allow browsers to lay out the page more accurately before the icons have been loaded. https://web.dev/optimize-cls/.

Add min-width: 115px to the crate search dropdown. When the HTML first loads, this dropdown includes only the text "All crates." Later, JS loads the items underneath it, some of which are wider. That causes the dropdown to get wider, causing a distracting reflow. This sets a min-width based on the size that the dropdown eventually becomes based on the crates on doc.rust-lang.org, reducing page movement during load.

Add font-display: swap. Per https://web.dev/font-display/, this prevents "flash of invisible text" during load by using a system font until the custom font is available. I've noticed this flash of invisible text occasionally when reading Rust docs. Note that users without cached fonts will see text, and then see it reflow. For `docs.rust-lang.org`, [setting caching headers will help a lot](https://github.com/rust-lang/simpleinfra/issues/62).

Generated output at https://jacob.hoffman-andrews.com/rust/flow-improvements/std/string/struct.String.html.

Rollup merge of #82310 - jsha:rustdoc-search-onfocus, r=GuillaumeGomez

Load rustdoc's JS search index on-demand.

Instead of being loaded on every page, the JS search index is now loaded when either (a) there is a `?search=` param, or (b) the search input is focused.

This saves both CPU and bandwidth. As of Feb 2021, https://doc.rust-lang.org/search-index1.50.0.js is 273,838 bytes gzipped or 2,544,939 bytes uncompressed. Evaluating it takes 445 ms of CPU time in Chrome 88 on a i7-10710U CPU (out of a total ~2,100 ms page reload).

Tested on Firefox and Chrome.

New:
https://jacob.hoffman-andrews.com/rust/search-on-demand/std/primitive.slice.html
https://jacob.hoffman-andrews.com/rust/search-on-demand/std/primitive.slice.html?search=fn

Old:
https://jacob.hoffman-andrews.com/rust/search-on-load/std/primitive.slice.html
https://jacob.hoffman-andrews.com/rust/search-on-load/std/primitive.slice.html?search=fn

Rollup merge of #80527 - jyn514:rustdoc-lints, r=GuillaumeGomez

Make rustdoc lints a tool lint instead of built-in

- Rename `broken_intra_doc_links` to `rustdoc::broken_intra_doc_links` (and similar for other rustdoc lints; I don't expect any others to be used frequently, though).
- Ensure that the old lint names still work and give deprecation errors
- Register lints even when running doctests
- Move lint machinery into a separate file
- Add `declare_rustdoc_lint!` macro

Unblocks https://github.com/rust-lang/rust/pull/80300, https://github.com/rust-lang/rust/pull/79816, https://github.com/rust-lang/rust/pull/80965. Makes the strangeness in https://github.com/rust-lang/rust/pull/77364 more apparent to the end user (note that `missing_docs` is *not* moved to rustdoc in this PR). Closes https://github.com/rust-lang/rust/issues/78786.

## Current status

This is blocked on #82620 (see https://github.com/rust-lang/rust/pull/80527#issuecomment-787401519)

Add a regression test for issue-81712

Pin es-check version to prevent unrelated CI failures

Auto merge of #82304 - LeSeulArtichaut:unpretty-ast, r=spastorino

Add `-Z unpretty` flags for the AST

Implements rust-lang/compiler-team#408.
Builds on #82269, but if that PR is rejected or stalls out, I can implement this without #82269.
cc rust-lang/rustc-dev-guide#1062

Pass `CrateNum` by value instead of by reference

It's more idiomatic to pass a small Copy type by value and `CrateNum` is
half the size of `&CrateNum` on 64-bit systems. The memory use change is
almost certainly insignificant, but why not!

Fix commit detected when using `download-rustc`

On reflection on the issue in https://github.com/rust-lang/rust/pull/79540#discussion_r572572280,  I think the bug was actually using the `compiler/` filter, not using `--author=bors`. https://github.com/rust-lang/rust/commit/9a1d6174c925f54c923599e29b09d6855e6b3a78 has no CI artifacts because it was merged as part of a rollup:
```
$ curl -I https://ci-artifacts.rust-lang.org/rustc-builds/96e843ce6ae42e0aa519ba45e148269de347fd84/rust-std-nightly-x86_64-unknown-linux-gnu.tar.xz
HTTP/2 404
```
So 9a1d6174c925f54c923599e29b09d6855e6b3a78 is the correct commit to download, and that's what `--author=bors` does:

$ git log --author=bors 4aec8a5da5547d6e1c24e99dad0003b7cac107f5
commit 9a1d6174c925f54c923599e29b09d6855e6b3a78

Ideally it would look for "the most recent bors commit not followed by a change to `compiler/`", which would exclude things like documentation changes and avoid redownloading more than necessary, but
- Redownloading isn't the end of the world,
- That metric is hard to implement, and
- Documentation-only or library-only changes are very rare anyway since they're usually rolled up with changes to the compiler.

Auto merge of #81114 - bugadani:generator, r=estebank

Box generator-related Body fields

Might save some memory on functions that aren't generators.

Auto merge of #82702 - jyn514:downgrade-err, r=Manishearth

Change error about unknown attributes to a warning

Hard errors should go through a future-compatibility phase first, especially since these attributes only have no effect and don't actively cause bugs.

Follow-up to https://github.com/rust-lang/rust/pull/82662. Fixes ecosystem breakage like https://github.com/rust-lang/rust-clippy/issues/6832.

r? `@GuillaumeGomez`

Remove useless comparison since now self.index <= self.len is an invariant

Add test for underflow in specialized Zip's size_hint

Increment self.len in specialized ZipImpl to avoid underflow in size_hint

reworded message

Explicitly disable preinline during pgo-use test

We previously used -Os to disable this pass, but since
https://reviews.llvm.org/D91673 this no longer works. Explicitly
disable it using -Cllvm-args instead.

Schedule ThinLTOBuffer passes again after sanitizer passes

This works around a design defect in the LLVM 12 pass builder
implementation. In LLVM 13, the PreLink ThinLTO pipeline properly
respects the OptimizerLastEPCallbacks.

Auto merge of #82553 - tmiasko:update-tracing, r=Mark-Simulacrum

Update tracing to 0.1.25

* Update tracing from 0.1.18 to 0.1.25
* Update tracing-subscriber from 0.2.13 to 0.2.16
* Update tracing-tree from 0.1.6 to 0.1.8
* Add pin-project-lite to the list of allowed dependencies (it is now a direct dependency of tracing).

Avoid unnecessary Vec construction in BufReader

Update library/alloc/src/vec/mod.rs

Co-authored-by: Ralf Jung <post@ralfj.de>

Change error about unknown doc attributes to a warning

This prevents breakage across the ecosystem, since the error was just
introduced recently without first having a warning period.

Add `-Z unpretty` flags for the AST

Auto merge of #82704 - RalfJung:miri-atomic-minmax, r=oli-obk

enable atomic_min/max tests in Miri

Thanks to `@henryboisdequin` and `@GregBowyer,` Miri now supports these intrinsics. :)
Also includes the necessary Miri update.

Warn in doc test

Fix borrow and deref

Remove lint pass on borrow and deref

Move unrelated ui test back to what it was before

Allow noop_method_call in clippy ui test

Clean up code rightward drift

Increase accuracy of lint trigger

Improve error messages

Fix tidy error

Update error message

Fix tidy errors

Improve warning

Fix std tests

Only allow new lint when not bootstrapping - since beta doesn't know about the lint

Fix core tests

Fix ui-full-deps suite

Bless test where order of error message changed

Fix tests

Add tests and support two more noop methods