Fix typos “a”→“an”

[steffahn]

Fix typos in comments; found using a regex to find some easy instance of incorrect usage of a vs. an.

While automation was used to find these, every change was checked manually.

Changes in submodules get separate PRs:

• Fix typos “a”→“an” stdarch#1201
• Fix typos “a”→“an” cargo#9821
• Fix typos “a”→“an” miri#1874
• Fix typos “a”→“an” rls#1746
• minor: Fix typos “a”→“an” rust-analyzer#9984
  folks @ rust-analyzer are fast at merging…
  • minor: Fix another “a”/“an” typo rust-analyzer#9985
  • Fix two more “a”/“an” typos rust-analyzer#9987
  • Fix two more “a”/“an” typos (this time the other way) rust-analyzer#9989

For clippy, I don’t know if the changes should better better be moved to a PR to the original repo.

---

This has some overlap with #88226, but neither is a strict superset of the other.

If you want multiple commits, I can split it up; in that case, make sure to suggest a criterion for splitting.

[rust-highfive]

Some changes occured to the CTFE / Miri engine

cc @rust-lang/miri

Some changes occured to the CTFE / Miri engine

cc @rust-lang/miri

Some changes occurred in src/tools/clippy.

cc @rust-lang/clippy

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez

[rust-highfive]

r? @oli-obk

(rust-highfive has picked a reviewer for you, use r? to override)

[steffahn]

@rustbot label C-cleanup

[GuillaumeGomez]

I'd prefer a native english speaker to review it.

@pnkfelix

[steffahn]

Missed a test output that needed to be updated accordingly in src/test/ui/closures/2229_closure_analysis/migrations/insignificant_drop.fixed; added the change, lets see if CI is happy now.

(Diff of the force push:)

$ gd f3e105f..bf88b11
diff --git a/src/test/ui/closures/2229_closure_analysis/migrations/insignificant_drop.fixed b/src/test/ui/closures/2229_closure_analysis/migrations/insignificant_drop.fixed
index 982407e2e25..c82bc369f43 100644
--- a/src/test/ui/closures/2229_closure_analysis/migrations/insignificant_drop.fixed
+++ b/src/test/ui/closures/2229_closure_analysis/migrations/insignificant_drop.fixed
@@ -3,7 +3,7 @@
 #![deny(rust_2021_incompatible_closure_captures)]
 //~^ NOTE: the lint level is defined here
 
-// Test cases for types that implement a insignificant drop (stlib defined)
+// Test cases for types that implement an insignificant drop (stlib defined)
 
 // `t` needs Drop because one of its elements needs drop,
 // therefore precise capture might affect drop ordering

[oli-obk]

like in miri, I read this as "dash dash extern", so the "a" is correct, but I see how this change also can make sense

[steffahn]

Seems reasonable, I’ll remove the change.

[steffahn]

If we want to avoid commits touching the file, I can rebase the PR after review.

[steffahn]

Added another commit with more changes, this time matching some shorter (3-letter) words after the “a”.

[steffahn]

Now there’s two more commits handling the letter “u”. I’m done here for now ^^

[RalfJung]

FWIW I usually pronounce this "an ampersand unique", so "an" would be correct then.

But I guess when in doubt it makes more sense to defer to "a" as a default. 🤷

[steffahn]

oh, ampersand, … that makes sense. I’ve always only considered something like “ref” or the “ignore it completely” strategy.

[steffahn]

Rough search yields

with “a”

library/core/src/task/wake.rs
146:/// Currently, `Context` only serves to provide access to a `&Waker`
159:    /// Create a new `Context` from a `&Waker`.

library/core/src/any.rs
23://! converting the smart pointer into a `&dyn Any` instead, which will return

library/core/src/pin.rs
524:    /// must not be possible to obtain a `&mut P::Target` and then
539:    ///     mem::swap(&mut a, &mut b);
694:    /// it *is* possible to move a `T` out of a `&RefCell<T>`. However, this is

library/core/src/convert/mod.rs
313:/// An explicit conversion from a `&str` to a String is done as follows:

library/core/src/lib.rs
30://!   `fmt::Arguments`, a `&'static str`, and two `u32`'s. These four arguments

library/core/src/panic/panic_info.rs
65:    /// This will commonly, but not always, be a `&'static str` or [`String`].

library/core/src/str/converts.rs
24:/// If you need a `String` instead of a `&str`, consider

library/core/src/ops/bit.rs
86:///     // rhs is the "right-hand side" of the expression `a & b`
619:///     // rhs is the "right-hand side" of the expression `a &= b`
652:///     // `rhs` is the "right-hand side" of the expression `a &= b`.

library/core/src/panic/location.rs
94:    /// represent this directly as a `&Path`. The compiled code may run on a different system with

library/core/src/ptr/mod.rs
1363:/// This can be used to hash a `&T` reference (which coerces to `*const T` implicitly)

library/core/src/str/traits.rs
494:/// parse an `i32` with `FromStr`, but not a `&i32`. You can parse a struct that

library/core/src/str/pattern.rs
48:/// can be used as a string pattern for searching in a [`&'a str`][str].

library/core/src/sync/atomic.rs
319:    /// Get atomic access to a `&mut bool`.

library/core/src/panicking.rs
14://! allow for failing with a `Box<Any>` value. (`PanicInfo` just contains a `&(dyn Any + Send)`,

library/core/src/future/mod.rs
79:            // `.await` lowering will safely cast that back to a `&mut Context`.

library/core/src/borrow.rs
56:/// be possible to search using a [`&str`][`str`]. Thus, `insert` needs to
57:/// operate on a `String` while `get` needs to be able to use a `&str`.

library/core/src/slice/mod.rs
1949:    /// If you do not have a `&T`, but some other value that you can compare

library/core/src/char/methods.rs
558:    /// // as a &str, these two are encoded in UTF-8

library/core/src/str/mod.rs
928:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
955:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
981:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1010:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1058:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1105:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1232:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1270:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1322:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1367:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1416:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1469:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1554:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1591:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1633:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1676:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1948:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1992:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
2019:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
2046:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
2095:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
2132:    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a

library/core/src/intrinsics.rs
1016:    /// Turning an `&str` into a `&[u8]`:
2029:/// append(&mut a, &mut b);

library/core/src/marker.rs
419:/// becomes read-only, as if it were a `& &T`. Hence there is no risk

library/core/src/cell.rs
514:    /// Returns a `&Cell<T>` from a `&mut T`
559:    /// Returns a `&[Cell<T>]` from a `&Cell<[T]>`
1718:/// - If you create a safe reference with lifetime `'a` (either a `&T` or `&mut T`
1724:/// lifetime expires. Similarly, if you create a `&mut T` reference that is released to
1736:/// references, but not with a `&mut T`
1750:/// a `&mut T`.

library/core/src/iter/traits/iterator.rs
1928:    /// early returns. This is a `&mut self` method, so iteration needs to be

library/core/src/mem/maybe_uninit.rs
832:    /// // the `&mut MaybeUninit<[u8; 1024]>` to a `&mut [u8; 1024]`:

library/std/src/thread/local.rs
444:            // TLS, in which case there will be a `&` and `&mut` pointer to the same

library/std/src/path.rs
1887:    /// Yields a [`&str`] slice if the `Path` is valid unicode.

library/std/src/primitive_docs.rs
245:/// [`fmt::Result`]. Since this method takes a `&!` as an argument we know that it can never be
773:///     // First, we build a &[u8]...
1041:/// (`false`), but creating a `&bool` that points to an allocation containing

library/std/src/ffi/os_str.rs
566:    /// Yields a [`&str`] slice if the `OsStr` is valid Unicode.

library/std/src/ffi/c_str.rs
41:/// a [`&str`], since both implement that trait).
58:/// Alternatively, you can obtain a `&[`[`u8`]`]` slice from a
67:/// If you need a `&[`[`u8`]`]` slice *with* the nul terminator, you
123:/// array of bytes. It can be constructed safely from a `&[`[`u8`]`]`
1355:    /// Yields a [`&str`] slice if the `CStr` contains valid UTF-8.

library/std/src/fs.rs
80:/// Note that, although read and write methods require a `&mut File`, because
81:/// of the interfaces for [`Read`] and [`Write`], the holder of a `&File` can
85:/// by different processes. Avoid assuming that holding a `&File` means that the

library/std/src/lazy.rs
553:// We never create a `&F` from a `&SyncLazy<T, F>` so it is fine
555:// we do create a `&mut Option<F>` in `force`, but this is

library/std/src/os/windows/ffi.rs
34://! lets you create an [`OsString`] from a `&[u16]` slice; presumably

library/std/src/sys/sgx/abi/usercalls/alloc.rs
312:    /// Creates a `&UserRef<[T]>` from a raw pointer.
329:    /// Creates a `&mut UserRef<[T]>` from a raw pointer. See the struct
330:    /// documentation for the nuances regarding a `&mut UserRef<T>`.
406:    /// Creates a `&UserRef<[T]>` from a raw thin pointer and a slice length.
425:    /// Creates a `&mut UserRef<[T]>` from a raw thin pointer and a slice length.

library/std/src/sys_common/wtf8.rs
526:    /// Tries to convert the string to UTF-8 and return a `&str` slice.
788:    // memory layout of a &[u8] and &Wtf8 are the same

library/std/src/io/mod.rs
1153:/// It is semantically a wrapper around a `&[u8]`, but is guaranteed to be

library/alloc/src/vec/source_iter_marker.rs
132:        // - unlike most internal iteration methods, it only takes a &mut self

library/alloc/src/boxed.rs
1306:    /// Converts a `&[T]` into a `Box<[T]>`
1313:    /// // create a &[u8] which will be used to create a Box<[u8]>
1344:    /// Converts a `&str` into a `Box<str>`
1384:    /// // create a &[u8] which will be used to create a Box<[u8]>

compiler/rustc_traits/src/chalk/lowering.rs
46:/// Essentially an `Into` with a `&RustInterner` parameter

library/alloc/src/fmt.rs
435://! write!       // first argument is a &mut io::Write, the destination

compiler/rustc_errors/src/diagnostic_builder.rs
38:/// `diagnostic`, because the return type would be a `&Diagnostic`
39:/// instead of a `&DiagnosticBuilder<'a>`. This `forward!` macro makes

library/alloc/src/string.rs
91:/// append a [`&str`] with the [`push_str`] method:
146:/// function which takes a [`&str`] by using an ampersand (`&`):
156:/// This will create a [`&str`] from the `String` and pass it in. This
307:/// occur when converting a slice of [`u8`]s to a [`&str`]. In this sense, it's
453:    /// If you need a [`&str`] instead of a `String`, consider
1794:    /// occur when converting a slice of [`u8`]s to a [`&str`]. In this sense, it's
2158:/// let c = a + &b;
2494:    /// Converts a `&str` into a [`String`].
2506:    /// Converts a `&mut str` into a [`String`].
2518:    /// Converts a `&String` into a [`String`].
2837:    /// assert_eq!("a", &s[..]);

compiler/rustc_typeck/src/mem_categorization.rs
338:                    // The call to index() returns a `&T` value, which

compiler/rustc_typeck/src/check/regionck.rs
715:        // being borrowed is a `&mut` or `&uniq` borrow, borrowck requires

compiler/rustc_typeck/src/check/coercion.rs
378:            //     effectively a `&'b *x` expression (if you could

compiler/rustc_typeck/src/check/pat.rs
309:            // When encountering a `& mut? pat` pattern, reset to "by value".
369:                // This is because a `& &mut` cannot mutate the underlying value.

compiler/rustc_typeck/src/check/method/probe.rs
161:/// - Add a `&` (or `&mut`), converting the receiver from `T` to `&T` (or `&mut T`)
808:        // a `&self` method will wind up with an argument type like `&dyn Trait`.
1148:                // Insert a `&*` or `&mut *` if this is a reference type:

compiler/rustc_typeck/src/check/demand.rs
408:    /// `String` into a `&str` since a `&` would do the trick!
584:                // we may want to suggest removing a `&`.

library/stdarch/crates/core_arch/src/x86/sse42.rs
617:    // Currently one cannot `load` a &[u8] that is is less than 16

library/stdarch/crates/core_arch/src/x86/sse.rs
247:/// Computes `!a & b` for each bit in `a` and `b`.

compiler/rustc_mir_build/src/thir/pattern/const_to_pat.rs
398:                // `b"foo"` produces a `&[u8; 3]`, but you can't use constants of array type when

compiler/rustc_mir_build/src/build/matches/mod.rs
1790:        // then any pattern bindings of type T will map to a `&T`

compiler/rustc_mir_build/src/thir/cx/expr.rs
924:            // We encode uses of statics as a `*&STATIC` where the `&STATIC` part is

compiler/rustc_metadata/src/rmeta/table.rs
141:    // obtain a `&[u8]` entirely in safe code, for writing the bytes out.

compiler/rustc_ast/src/mut_visit.rs
286:/// Use a map-style function (`FnOnce(T) -> T`) to overwrite a `&mut T`. Useful

compiler/rustc_span/src/symbol.rs
1722:        // `from_utf8_unchecked` is safe since we just allocated a `&str` which is known to be
1901:/// - `&*ss` is a `&str` (and `match &*ss { ... }` is a common pattern).
1902:/// - `&ss as &str` is a `&str`, which means that `&ss` can be passed to a
1903:///   function expecting a `&str`.

compiler/rustc_ast/src/ast.rs
1371:    /// A referencing operation (`&a`, `&mut a`, `&raw const a` or `&raw mut a`).

compiler/rustc_ast_lowering/src/lib.rs
387:///   of a `&` (e.g., the missing lifetime in something like `&T`)
2692:    /// Report an error on illegal use of `'_` or a `&T` with no explicit lifetime;

compiler/rustc_hir/src/hir.rs
920:    /// will depend on whether we have skipped through a `&` reference
2223:    /// Like [`PrimTy::name`], but returns a &str instead of a symbol.

compiler/rustc_ast_pretty/src/pp.rs
161:    // In practice a string token contains either a `&'static str` or a

compiler/rustc_infer/src/infer/mod.rs
458:    /// Regions created by a `&P` or `[...]` pattern

compiler/rustc_middle/src/ty/adjustment.rs
100:    /// Take the address and produce either a `&` or `*` pointer.

compiler/rustc_middle/src/ty/closure.rs
392:    /// This is then illegal because you cannot mutate a `&mut` found
437:            // use `&mut`. It gives all the capabilities of a `&uniq`

compiler/rustc_middle/src/mir/tcx.rs
268:            // use `&mut`. It gives all the capabilities of a `&uniq`

compiler/rustc_lint/src/non_fmt_panic.rs
127:            // If this is a &str or String, we can confidently give the `"{}", ` suggestion.

compiler/rustc_lint/src/noop_method_call.rs
31:    /// calling `clone` on a `&T` where `T` does not implement clone, actually doesn't do anything

compiler/rustc_lint/src/builtin.rs
2716:    // FIXME: Technically, we could just store a &'tcx str here without issue; however, the

compiler/rustc_mir/src/interpret/validity.rs
860:                // a &[u8] that contains a pointer even though bytewise checking would

compiler/rustc_mir/src/borrow_check/diagnostics/mutability_errors.rs
235:            // Suggest removing a `&mut` from the use of a mutable reference.
349:            // We want to point out when a `&` can be readily replaced
849:            // Check if the user variable is a `&mut self` and we can therefore
887:// When we want to suggest a user change a local variable to be a `&mut`, there

compiler/rustc_mir/src/borrow_check/diagnostics/region_name.rs
489:                // is the region we are looking for -- if so, and we have a `&T`

compiler/rustc_mir/src/borrow_check/diagnostics/conflict_errors.rs
311:                    // If we have a `&mut` ref, we need to reborrow.
372:                    // We have a `&mut` ref, we need to reborrow on each iteration (#62112).

compiler/rustc_mir/src/transform/check_consts/ops.rs
388:/// A call to a `panic()` lang item where the first argument is _not_ a `&str`.

compiler/rustc_data_structures/src/steal.rs
12:/// So instead we have the query produce a `&'tcx Steal<mir::Body<'tcx>>`

compiler/rustc_data_structures/src/owning_ref/mod.rs
458:    ///         = owning_ref_a.map(|a| &a[0]);
461:    ///         = owning_ref_b.map(|a| &a[1].0);
706:    ///         = owning_ref_mut_a.map_mut(|a| &mut a[0]);
709:    ///         = owning_ref_mut_b.map_mut(|a| &mut a[1].0);

compiler/rustc_error_codes/src/error_codes/E0185.md
15:    // error, method `foo` has a `&self` declaration in the impl, but not in

compiler/rustc_error_codes/src/error_codes/E0614.md
16:// So here, `x` is a `&u32`, so we can dereference it:

compiler/rustc_error_codes/src/error_codes/E0186.md
15:    // error, method `foo` has a `&self` declaration in the trait, but not in

src/test/ui/cleanup-rvalue-scopes.rs
95:    // addr into a stack slot, either via `let ref` or via a `&` in

src/test/ui/borrowck/issue-85765.rs
6:    //~^ ERROR cannot borrow `*rofl` as mutable, as it is behind a `&` reference
7:    //~| NOTE `rofl` is a `&` reference, so the data it refers to cannot be borrowed as mutable
13:    //~^ ERROR cannot assign to `*r`, which is behind a `&` reference
14:    //~| NOTE `r` is a `&` reference, so the data it refers to cannot be written
20:    //~^ ERROR cannot assign to `*x`, which is behind a `&` reference
21:    //~| NOTE `x` is a `&` reference, so the data it refers to cannot be written
27:    //~^ ERROR cannot assign to `*y`, which is behind a `&` reference
28:    //~| NOTE `y` is a `&` reference, so the data it refers to cannot be written

src/test/ui/borrowck/issue-83309-ice-immut-in-for-loop.rs
12:        //~^ ERROR cannot assign to `*v`, which is behind a `&` reference
13:        //~| NOTE `v` is a `&` reference, so the data it refers to cannot be written

src/test/ui/borrowck/borrow-raw-address-of-deref-mutability.rs
1:// Check that `&raw mut` cannot be used to turn a `&T` into a `*mut T`.

src/test/ui/borrowck/borrowck-return-variable-on-stack-via-clone.rs
1:// Check that when we clone a `&T` pointer we properly relate the

src/test/ui/consts/const-trait-to-trait.rs
4:// Issue #24644 - block causes a &Trait -> &Trait coercion:

src/test/ui/consts/const-mut-refs/issue-76510.rs
8://~| ERROR: cannot borrow data in a `&` reference as mutable

src/test/ui/borrowck/borrowck-freeze-frozen-mut.rs
2:// Test that a `&mut` inside of an `&` is freezable.

src/test/ui/closures/2229_closure_analysis/diagnostics/mut_ref.rs
13:    //~^ ERROR: cannot borrow `**ref_mref_x` as mutable, as it is behind a `&` reference
27:    //~^ ERROR: cannot borrow `**mref_ref_x` as mutable, as it is behind a `&` reference

src/test/ui/closures/2229_closure_analysis/diagnostics/cant-mutate-imm-borrow.rs
14:    //~^ ERROR: cannot borrow `*z.0.0` as mutable, as it is behind a `&` reference

src/test/ui/did_you_mean/issue-38147-2.rs
8:        //~^ ERROR cannot borrow `*self.s` as mutable, as it is behind a `&` reference

src/test/ui/did_you_mean/issue-38147-3.rs
8:        //~^ ERROR cannot borrow `*self.s` as mutable, as it is behind a `&` reference

src/test/ui/impl-trait/region-escape-via-bound-contravariant.rs
4:// we are *actually* returning a `&'y u32`.

src/test/ui/impl-trait/region-escape-via-bound-contravariant-closure.rs
4:// we are *actually* returning a `&'y u32`.

src/test/ui/impl-trait/trait_type.rs
18:   //~^ ERROR method `fmt` has a `&self` declaration in the trait

src/test/ui/did_you_mean/issue-39544.rs
49:    //~^ ERROR cannot assign to `*x.0`, which is behind a `&` reference

src/test/ui/regions/regions-early-bound-trait-param.rs
125:    // to consume a value of type T and return a &T).  Easiest thing

src/test/ui/pattern/bindings-after-at/box-patterns.rs
16:            // bar is a &Option<Box<i32>>
22:            // bar is a &Box<i32> here

src/test/ui/nll/issue-51244.rs
4:    //~^ ERROR cannot assign to `*my_ref`, which is behind a `&` reference [E0594]

src/test/ui/nll/user-annotations/normalization.rs
1:// Test that we enforce a `&'static` requirement that is only visible

src/test/ui/nll/dont-print-desugared.rs
5:    //~^ ERROR cannot borrow data in a `&` reference as mutable [E0596]

src/test/ui/nll/issue-51191.rs
24:        //~^^ ERROR cannot borrow data in a `&` reference as mutable [E0596]

src/test/ui/staticness-mismatch.rs
8:    //~^ ERROR method `bar` has a `&self` declaration in the impl, but not in the trait

src/test/ui/methods/method-lookup-order.rs
139:    // is because we can get to a `&self` method by first a deref of the given

src/test/ui/numbers-arithmetic/num-wrapping.rs
171:            // also test that a &Wrapping<T> right-hand side is possible

src/test/ui/union/union-nonzero.rs
9:// For example, if a union `U` can contain both a `&T` and a `*const T`, there's definitely no

src/test/ui/async-await/dont-print-desugared-async.rs
6://~^ ERROR cannot borrow data in a `&` reference as mutable [E0596]

src/test/ui/issues/issue-51515.rs
6:    //~^ ERROR cannot assign to `*foo`, which is behind a `&` reference
11:    //~^ ERROR cannot assign to `*bar`, which is behind a `&` reference

src/test/ui/issues/issue-19163.rs
10:    //~^ ERROR cannot borrow data in a `&` reference as mutable

src/test/ui/span/borrowck-call-is-borrow-issue-12224.rs
26:    //~^ ERROR cannot borrow `*f` as mutable, as it is behind a `&` reference
35:    //~^ ERROR: cannot borrow `f.f` as mutable, as it is behind a `&` reference

src/test/ui/issues/issue-48276.rs
12:        //~^ ERROR: method `from` has a `&self` declaration in the impl, but not in the trait
21:        //~^ ERROR: method `from` has a `&self` declaration in the impl, but not in the trait
28:        //~^ ERROR: method `from` has a `&self` declaration in the impl, but not in the trait

src/test/ui/issues/issue-52240.rs
10:        //~^ ERROR cannot borrow data in a `&` reference as mutable

src/test/ui/issues/issue-61623.rs
7://~^ ERROR cannot borrow `*x.1` as mutable, as it is behind a `&` reference

src/test/ui/rfcs/rfc-2005-default-binding-mode/reset-mode.rs
2:// Test that we "reset" the mode as we pass through a `&` pattern.

src/doc/rust-by-example/src/flow_control/match/destructuring/destructure_pointers.md
31:    // What if you don't start with a reference? `reference` was a `&`

src/doc/rust-by-example/src/scope/lifetime/lifetime_coercion.md
16:// Here, we take in an `&'a i32` and return a `&'b i32` as a result of coercion.

src/doc/rust-by-example/src/std/str.md
122:    // Note that this is not actually a `&str`

src/doc/edition-guide/src/rust-2021/IntoIterator-for-arrays.md
77:    // x is a `&u8` in Rust 2015 and Rust 2018
90:    // x is a `&u8` in all editions

src/doc/rust-by-example/src/fn/closures/capture.md
46:    // A `mut` is required on `inc` because a `&mut` is stored inside. Thus,

compiler/rustc_error_codes/src/error_codes.rs
517://  E0190, // deprecated: can only cast a &-pointer to an &-object

src/tools/clippy/clippy_dev/src/lib.rs
269:/// * `start` is a `&str` that describes the delimiter line before the region you want to replace.
271:/// * `end` is a `&str` that describes the delimiter line until where the replacement should happen.

src/tools/miri/src/stacked_borrows.rs
236:/// F1: After creating a `&`, the parts outside `UnsafeCell` have our `SharedReadOnly` on top.

src/tools/clippy/tests/ui/search_is_some_fixable.fixed
23:    // caller of `find()` is a `&`static str`
56:    // caller of `find()` is a `&`static str`

src/tools/clippy/tests/ui/redundant_clone.fixed
146:    // join() creates a new owned PathBuf, does not take a &mut to x variable, thus the .clone() is

src/tools/clippy/tests/ui/redundant_clone.rs
146:    // join() creates a new owned PathBuf, does not take a &mut to x variable, thus the .clone() is

src/tools/clippy/tests/ui/expect_fun_call.rs
88:    //Issue #4912 - the receiver is a &Option

src/tools/clippy/tests/ui/ref_binding_to_reference.rs
29:    // Err, reference to a &String
35:    // Err, reference to a &String
45:    // Err, reference to a &String
51:    // Err, reference to a &String
57:// Err, reference to a &String
64:    // Err, reference to a &String
72:    // Err, reference to a &String

src/tools/clippy/tests/ui/needless_borrow_pat.rs
46:    // Ok, reference to a &mut String
58:    // Err, reference to a &String
64:    // Err, reference to a &String.
70:    // Err, reference to a &String
80:    // Err, reference to a &String
86:    // Err, reference to a &String
91:    // Err, reference to a &String
100:    // Err, reference to a &u32. Don't suggest adding a reference to the field access.
125:// Err, reference to a &String
132:    // Err, reference to a &String
140:    // Err, reference to a &String

src/tools/clippy/tests/ui/expect_fun_call.fixed
88:    //Issue #4912 - the receiver is a &Option

src/tools/clippy/tests/ui/search_is_some_fixable.rs
23:    // caller of `find()` is a `&`static str`
56:    // caller of `find()` is a `&`static str`

src/tools/miri/tests/run-pass/stacked-borrows/stacked-borrows.rs
56:// Create first a shared reference and then a raw pointer from a `&mut`

src/tools/miri/tests/compile-fail/stacked_borrows/load_invalid_mut.rs
4:// Make sure that we cannot load from memory a `&mut` that got already invalidated.

src/tools/miri/tests/compile-fail/stacked_borrows/pass_invalid_mut.rs
1:// Make sure that we cannot pass by argument a `&mut` that got already invalidated.

src/tools/miri/tests/compile-fail/stacked_borrows/pass_invalid_shr.rs
1:// Make sure that we cannot pass by argument a `&` that got already invalidated.

src/tools/miri/tests/compile-fail/stacked_borrows/load_invalid_shr.rs
4:// Make sure that we cannot load from memory a `&` that got already invalidated.

src/tools/miri/tests/compile-fail/stacked_borrows/return_invalid_shr.rs
1:// Make sure that we cannot return a `&` that got already invalidated.

src/tools/miri/tests/compile-fail/stacked_borrows/return_invalid_mut.rs
1:// Make sure that we cannot return a `&mut` that got already invalidated.

src/tools/miri/tests/compile-fail/stacked_borrows/return_invalid_mut_option.rs
1:// Make sure that we cannot return a `&mut` that got already invalidated, not even in an `Option`.

src/tools/miri/tests/compile-fail/stacked_borrows/return_invalid_shr_tuple.rs
1:// Make sure that we cannot return a `&` that got already invalidated, not even in a tuple.

src/tools/miri/tests/compile-fail/stacked_borrows/return_invalid_mut_tuple.rs
1:// Make sure that we cannot return a `&mut` that got already invalidated, not even in a tuple.

src/tools/miri/tests/compile-fail/stacked_borrows/return_invalid_shr_option.rs
1:// Make sure that we cannot return a `&` that got already invalidated, not even in an `Option`.

src/tools/clippy/clippy_lints/src/types/mod.rs
166:    /// Any `&Box<T>` can also be a `&T`, which is more

src/tools/clippy/clippy_lints/src/manual_strip.rs
169:// Tests if `expr` is a `&str`.

src/tools/clippy/clippy_lints/src/ptr.rs
39:    /// Other functions called from this function taking a `&String` or `&Vec`
45:    /// when called on a `Vec<Vec<T>>`. If a `&Vec` is passed to that method then
46:    /// it will compile, but if a `&[T]` is passed then it will not compile.

src/tools/clippy/clippy_lints/src/lifetimes.rs
115:/// The lifetime of a &-reference.

src/tools/clippy/clippy_lints/src/strings.rs
325:    /// When called on a `&str` it turns the `&str` into the owned variant `String`, which can be better

src/tools/clippy/clippy_lints/src/swap.rs
36:    /// std::mem::swap(&mut a, &mut b);
61:    /// std::mem::swap(&mut a, &mut b);

src/tools/clippy/clippy_lints/src/transmute/mod.rs
167:    /// Checks for transmutes from a `&[u8]` to a `&str`.

src/tools/rust-analyzer/crates/hir_ty/src/lower.rs
63:    /// passing around a `&mut TyLoweringContext`. The core problem is that

src/tools/rust-analyzer/crates/hir_ty/src/infer/pat.rs
125:            // When you encounter a `&pat` pattern, reset to Move.

src/tools/rust-analyzer/crates/hir_ty/src/infer.rs
196:    /// Take the address and produce either a `&` or `*` pointer.

src/tools/rust-analyzer/crates/hir_def/src/expr.rs
343:    /// will depend on whether we have skipped through a `&` reference

src/tools/rust-installer/src/util.rs
16:/// Converts a `&Path` to a UTF-8 `&str`.

src/tools/cargo/src/cargo/util/lev_distance.rs
37:/// is used to select a `&str` from the iterator to compare against `choice`.

src/doc/nomicon/src/send-and-sync.md
197:// Safety: Since there exists a public way to go from a `&Carton<T>` to a `&T`

with “an”

compiler/rustc_typeck/src/check/regionck.rs
742:                // The reference being reborrowed is either an `&mut T`. This is

compiler/rustc_typeck/src/check/generator_interior.rs
182:    // if a Sync generator contains an &'α T, we need to check whether &'α T: Sync),

compiler/rustc_typeck/src/check/coercion.rs
353:            // we've been considering, we have an `&mut` reference, so

compiler/rustc_typeck/src/check/upvar.rs
12://! will promote its borrow kind to mutable borrow. If we see an `&mut x`
1596:    /// the upvar must be borrowed using an `&mut` borrow.
1613:                    // assignment to deref of an `&mut`

compiler/rustc_mir_build/src/thir/cx/expr.rs
998:        // call returns an &T and we must add the deref so that the types

compiler/rustc_middle/src/mir/mod.rs
650:    /// This is then illegal because you cannot mutate an `&mut` found
652:    /// an `&mut` borrow:

compiler/rustc_serialize/src/json.rs
2155:/// Decodes a json value from an `&mut io::Read`

compiler/rustc_middle/src/ty/closure.rs
394:    /// an `&mut` borrow:
427:    /// Returns a mutability `m` such that an `&m T` pointer could be used to obtain this borrow

compiler/rustc_infer/src/infer/mod.rs
395:    /// When casting `&'a T` to an `&'b Trait` object,

compiler/rustc_mir/src/borrow_check/diagnostics/mutability_errors.rs
350:            // with an `&mut`.

compiler/rustc_mir/src/dataflow/impls/borrowed_locals.rs
40:    /// This includes `&mut` and pointers derived from an `&mut`, as well as shared borrows of

compiler/rustc_error_codes/src/error_codes.rs
517://  E0190, // deprecated: can only cast a &-pointer to an &-object

library/std/src/io/mod.rs
1020:/// It is semantically a wrapper around an `&mut [u8]`, but is guaranteed to be

library/std/src/ffi/os_str.rs
61:/// You can use the [`OsString::as_os_str`] method to get an `&`[`OsStr`] from

library/core/src/pin.rs
527:    /// For example, calling `Pin::new_unchecked` on an `&'a mut T` is unsafe because
828:        // 1) Once we give out a `Pin<&mut P::Target>`, an `&mut P::Target` will not be given out.

library/core/src/cell.rs
1699:/// alias or by transmuting an `&T` into an `&mut T`, is considered undefined behavior.
1722:/// `UnsafeCell<T>` and cast it to an `&T`, then the data in `T` must remain immutable
1741:/// Note that whilst mutating the contents of an `&UnsafeCell<T>` (even while other
1747:/// accesses (_e.g._, through an `&mut UnsafeCell<_>`): neither the cell nor the wrapped value

library/core/src/str/traits.rs
495:/// contains an `i32`, but not one that contains an `&i32`.

library/core/src/intrinsics.rs
991:    /// Turning a `*mut T` into an `&mut T`:
1003:    /// Turning an `&mut T` into an `&mut U`:
1016:    /// Turning an `&str` into a `&[u8]`:
1102:    /// // you an `&mut T` from an `&mut T` or `*mut T`.

compiler/rustc_plugin_impl/src/lib.rs
19:/// A plugin registrar function takes an `&mut Registry` and should call

src/doc/rust-by-example/src/std_misc/path.md
19:    // Create a `Path` from an `&'static str`

src/doc/rust-by-example/src/scope/borrow/ref.md
15:    // an `&` borrow on the right side.

src/doc/rust-by-example/src/scope/lifetime/lifetime_coercion.md
16:// Here, we take in an `&'a i32` and return a `&'b i32` as a result of coercion.

src/test/ui/objects-coerce-freeze-borrored.rs
2:// Test that we can coerce an `@Object` to an `&Object`

src/test/ui/consts/const-trait-to-trait.rs
14:// Issue #25748 - the cast causes an &Encoding -> &Encoding coercion:

src/test/ui/issues/issue-45697.rs
1:// Test that assignments to an `&mut` pointer which is found in a

src/test/ui/issues/issue-45697-1.rs
1:// Test that assignments to an `&mut` pointer which is found in a

src/test/ui/borrowck/borrowck-freeze-frozen-mut.rs
2:// Test that a `&mut` inside of an `&` is freezable.

src/test/ui/borrowck/borrowck-reborrow-from-shorter-lived-andmut.rs
1:// Test that assignments to an `&mut` pointer which is found in a

src/test/ui/borrowck/borrowck-assign-to-andmut-in-borrowed-loc.rs
1:// Test that assignments to an `&mut` pointer which is found in a

src/test/ui/borrowck/borrowck-assign-to-andmut-in-aliasable-loc.rs
1:// Test that assignments to an `&mut` pointer which is found in a

src/test/ui/borrowck/borrowck-borrow-mut-base-ptr-in-aliasable-loc.rs
1:// Test that attempt to reborrow an `&mut` pointer in an aliasable

src/test/ui/borrowck/borrowck-borrow-of-mut-base-ptr-safe.rs
5:// Test that freezing an `&mut` pointer while referent is

src/test/ui/borrowck/borrowck-closures-unique.rs
2:// of an `&mut` requires a "unique" borrow -- that is, the variable to

src/test/ui/borrowck/mut-borrow-in-loop-2.rs
13:// is passing an `&mut` to a method that must be expecting an `&mut`,

src/test/ui/regions/regions-reborrow-from-shorter-mut-ref.rs
1:// Issue #8624. Tests that reborrowing the contents of an `&'b mut`

src/test/ui/borrowck/mut-borrow-in-loop-2.fixed
13:// is passing an `&mut` to a method that must be expecting an `&mut`,

src/test/ui/methods/method-mut-self-modifies-mut-slice-lvalue.rs
2:// Test that an `&mut self` method, when invoked on a place whose

src/test/ui/mut/mutable-enum-indirect.rs
1:// Tests that an `&` pointer to something inherently mutable is itself

src/tools/miri/tests/run-pass/stacked-borrows/stacked-borrows.rs
21:// Make sure that reading from an `&mut` does, like reborrowing to `&`,

src/tools/miri/src/stacked_borrows.rs
241:/// F3: If an access happens with an `&` outside `UnsafeCell`,

src/tools/rust-analyzer/crates/hir_ty/src/infer/coerce.rs
296:            // we've been considering, we have an `&mut` reference, so

src/tools/rust-analyzer/crates/mbe/src/expander.rs
96:/// many is not a plain `usize`, but an `&[usize]`.

src/tools/rust-analyzer/bench_data/glorious_old_parser
1066:    /// Expects and consumes an `&`. If `&&` is seen, replaces it with a single
1067:    /// `&` and continues. If an `&` is not seen, signals an error.

So “a” is way more common, but “an” has some decent usage, too.

[steffahn]

I’ll let the handful of changes involving & stay in this PR unless someone asks me to revert them.

[camsteffen]

For clippy, I don’t know if the changes should better better be moved to a PR to the original repo.

Changes for Clippy right here is fine, especially for something minor like this.

[oli-obk]

I'd prefer a native english speaker to review it.

It's not very important to get this perfect, just to make sure people don't stumble over comments

It does change public library docs though, so

r? rust-lang/libs-api

[oli-obk]

Ok, I have it on good authority by libs-api that we can go ahead with this

@bors r+ rollup

[bors]

📌 Commit 2f9ddf3 has been approved by oli-obk

[steffahn]

Some changes occured to the CTFE / Miri engine

cc @rust-lang/miri

Some changes occured to the CTFE / Miri engine

cc @rust-lang/miri

Why is @rust-highfive saying this twice?

[oli-obk]

I think because you changed two different directories that were marked for the miri team ^^