Rollup merge of #140658 - dianne:lit-deref-pats-p2, r=oli-obk

`deref_patterns`: let string and byte string literal patterns peel references and smart pointers before matching

This follows up on #140028. Together, they allow using string and byte string literal patterns to match on smart pointers when `deref_patterns` is enabled. In particular, string literals can now match on `String`, subsuming the functionality of the `string_deref_patterns` feature.

More generally, this works by letting literals peel references (and smart pointers) before matching, similar to most other patterns, providing an answer to #44849. Though it's only partially implemented at this point: this doesn't yet let named const patterns peel before matching. The peeling logic is general enough to support named consts, but the typing rules for named const patterns would need adjustments to feel consistent (e.g. arrays would need rules to be usable as slices, and `const STR: &'static str` wouldn't be able to match on a `String` unless a rule was added to let it be used where a `str` is expected, similar to what #140028 did for literals).

This also allows string and byte string patterns to match on mutable references, following up on https://github.com/rust-lang/rust/pull/140028#discussion_r2053927512. Rather than forward the mutability of the scrutinee to literal patterns, I've opted to peel `&mut`s from the scrutinee. From a design point of view, this makes the behavior consistent with what would be expected from deref coercions using the methodology in the next paragraph. From a diagnostics point of view, this avoids labeling string and byte string patterns as "mutable references", which I think could be confusing. See [`byte-string-type-errors.rs`](https://github.com/rust-lang/rust/compare/master...dianne:rust:lit-deref-pats-p2?expand=1#diff-4a0dd9b164b67c706751f3c0b5762ddab08bcef05a91972beb0190c6c1cd3706) for how the diagnostics look.

At a high level, the peeling logic implemented here tries to mimic how deref coercions work for expressions: we peel references (and smart pointers) from the scrutinee until the pattern can match against it, and no more. This is primarily tested by [`const-pats-do-not-mislead-inference.rs`](https://github.com/rust-lang/rust/compare/master...dianne:rust:lit-deref-pats-p2?expand=1#diff-19afc05b8aae9a30fe4a3a8c0bc2ab2c56b58755a45cdf5c12be0d5e83c4739d). To illustrate the connection, I wasn't sure if this made sense to include in the test file, but I've translated those tests to make sure they give the same inference results as deref coercions: [(playground)](https://play.rust-lang.org/?version=stable&mode=debug&edition=2024&gist=1869744cb9cdfed71a686990aadf9fe1). In each case, a reference to the scrutinee is coerced to have the type of the pattern (under a reference).

Tracking issue for deref patterns: #87121

r? `@oli-obk`
cc `@Nadrieril`

1 files changed, 24 insertions, 7 deletions

diff --git a/src/doc/unstable-book/src/language-features/deref-patterns.md b/src/doc/unstable-book/src/language-features/deref-patterns.md
index 0cc7106da48..fb6df290cc1 100644
--- a/src/doc/unstable-book/src/language-features/deref-patterns.md
+++ b/src/doc/unstable-book/src/language-features/deref-patterns.md
@@ -65,15 +65,26 @@ let deref!(x) = Box::new(NoCopy) else { unreachable!() };
 drop::<NoCopy>(x);
 ```
 
-Additionally, when `deref_patterns` is enabled, string literal patterns may be written where `str`
-is expected. Likewise, byte string literal patterns may be written where `[u8]` or `[u8; _]` is
-expected. This lets them be used in `deref!(_)` patterns:
+Additionally, `deref_patterns` implements changes to string and byte string literal patterns,
+allowing then to be used in deref patterns:
 
 ```rust
 # #![feature(deref_patterns)]
 # #![allow(incomplete_features)]
-match ("test".to_string(), b"test".to_vec()) {
-    (deref!("test"), deref!(b"test")) => {}
+match ("test".to_string(), Box::from("test"), b"test".to_vec()) {
+    ("test", "test", b"test") => {}
+    _ => panic!(),
+}
+
+// This works through multiple layers of reference and smart pointer:
+match (&Box::new(&"test".to_string()), &&&"test") {
+    ("test", "test") => {}
+    _ => panic!(),
+}
+
+// `deref!("...")` syntax may also be used:
+match "test".to_string() {
+    deref!("test") => {}
     _ => panic!(),
 }
 
@@ -82,10 +93,16 @@ match *"test" {
     "test" => {}
     _ => panic!(),
 }
+match *b"test" {
+    b"test" => {}
+    _ => panic!(),
+}
+match *(b"test" as &[u8]) {
+    b"test" => {}
+    _ => panic!(),
+}
 ```
 
-Implicit deref pattern syntax is not yet supported for string or byte string literals.
-
 [`box_patterns`]: ./box-patterns.md
 [`string_deref_patterns`]: ./string-deref-patterns.md
 [smart pointers in the standard library]: https://doc.rust-lang.org/std/ops/trait.DerefPure.html#implementors