Add String<A> type with custom allocator parameter

[shua]

This change is part of the allocator_api feature set #32838 (also see wg-allocators roadmap or libs-team ACP).
The previous attempts at adding an allocator parameter to string are at rust-lang/rust#101551, and rust-lang/rust#79500 (I think those authors should get much of the credit here, I am re-writing what they worked out in those threads).

workaround

There is a type inference ambiguity introduced when adding a generic parameter to a type which previously had none, even when that parameter has a default value (more details in rust-lang/rust#98931). I've done the same workaround as rust-lang/rust#101551, which is to make alloc::string::String a type alias to String<Global>, but I've arranged the modules a bit differently to make rebase/merges a bit easier.

This workaround unfortunately changes the type name of the String language item, and that would be user-facing in error or diagnostic output. I understand from this comment that this change is acceptable.

changes to existing API

Most of the methods on the original String have been implemented for the generic version instead. I don't foresee anything more moving from String<Global> to String<A>, as the remaining methods are all constructors which implicitly use the Global allocator.

There are three general types of changes:

1. methods which don't allocate: here we just change impl Foo for String to impl<A: Allocator> Foo for String<A>
2. converting to/from other allocator generic types like Vec<u8, A> and Box<str, A>: here we can use the existing allocator from those types.
3. methods which clone from some other type with an allocator: here it's ambiguous whether the end result should be String<A>, String<Global>, or String<impl Allocator + Default>, etc; in general I try to leave these out of this change, but where some analogous change was made to Vec<T, A> I follow that.

new methods

Some methods have been added to String<A> which are not strictly necessary to land this change, but are considered helpful enough to users, and close enough to existing precedent in Vec<T, A>. Specifically, 4 new constructors (new_in, with_capacity_in, try_with_capacity_in, from_raw_parts_in), 1 destructor (into_raw_parts_with_alloc), and 1 getter (allocator). Technically, the updated from_utf8_unchecked should be sufficient for constructing, but we can add some safe constructors so users don't have to sully themselves.

not implemented

Variants of from_utf{8,16}* which internally allocate or use Cow have been punted on this PR, maybe a followup would make sense to either rewrite them, or add some *_in variant.

[rustbot]

The rustc-dev-guide subtree was changed. If this PR only touches the dev guide consider submitting a PR directly to rust-lang/rustc-dev-guide otherwise thank you for updating the dev guide with your changes.

cc @BoxyUwU, @jieyouxu, @Kobzol, @tshepang

This PR modifies tests/ui/issues/. If this PR is adding new tests to tests/ui/issues/,
please refrain from doing so, and instead add it to more descriptive subdirectories.

Some changes occurred in src/tools/clippy

cc @rust-lang/clippy

rust-analyzer is developed in its own repository. If possible, consider making this change to rust-lang/rust-analyzer instead.

cc @rust-lang/rust-analyzer

[rustbot]

r? @Mark-Simulacrum

rustbot has assigned @Mark-Simulacrum.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[shua]

maybe r? @Amanieu as the reviewer of the previous PR has more context

edit: whoops saw previous reviewer actually was Mark-Simulcrum, Amanieu was just last to leave a review. If it makes sense to swap it back, please do!

[rust-log-analyzer]

The job aarch64-gnu-llvm-20-2 failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)

##[endgroup]
[TIMING:end] tool::ToolBuild { build_compiler: Compiler { stage: 0, host: aarch64-unknown-linux-gnu, forced_compiler: false }, target: aarch64-unknown-linux-gnu, tool: "linkchecker", path: "src/tools/linkchecker", mode: ToolBootstrap, source_type: InTree, extra_features: [], allow_features: "", cargo_args: [], artifact_kind: Binary } -- 0.147
[TIMING:end] tool::Linkchecker { compiler: Compiler { stage: 0, host: aarch64-unknown-linux-gnu, forced_compiler: false }, target: aarch64-unknown-linux-gnu } -- 0.000
##[group]Testing stage1 Linkcheck (aarch64-unknown-linux-gnu)
book/print.html:1063: broken link - `std/string/struct.String.html`
book/ch02-00-guessing-game-tutorial.html:367: broken link - `std/string/struct.String.html`
checked links in: 21.7s
number of HTML files scanned: 46371
number of HTML redirects found: 14531
number of links checked: 2562010
number of links ignored due to external: 123104
number of links ignored due to exceptions: 24
number of intra doc links ignored: 9
errors found: 2
found some broken links
NOTE: if you are adding or renaming a markdown file in a mdBook, don't forget to register the page in SUMMARY.md
Command `/checkout/obj/build/aarch64-unknown-linux-gnu/stage1-tools-bin/linkchecker /checkout/obj/build/aarch64-unknown-linux-gnu/doc` failed with exit code 1
Created at: src/bootstrap/src/core/build_steps/tool.rs:1599:23
Executed at: src/bootstrap/src/core/build_steps/test.rs:170:77

Command has failed. Rerun with -v to see more details.
Bootstrap failed while executing `--stage 2 test --skip tests --skip coverage-map --skip coverage-run --skip library --skip tidyselftest`
Build completed unsuccessfully in 0:37:56
  local time: Wed Nov 26 07:48:06 UTC 2025
  network time: Wed, 26 Nov 2025 07:48:06 GMT
##[error]Process completed with exit code 1.

[bors]

☔ The latest upstream changes (presumably #147799) made this pull request unmergeable. Please resolve the merge conflicts.