Add experimental fallible::FallibleVec

[ChrisDenton]

Tracking issue: #157392

There are a few things to be aware of here:

1. This is still experimental. It might be removed at any time so we have to be careful about any interdependency between this and Vec
2. Vec is a pretty crucial part of rust's standard library. We have to be extremely careful touching its code. We might regress performance or make debugging worse.

With that in mind, this PR does the minimum necessary for an MVP fallible::FallibleVec. The only actually new thing it adds is fallible push and push_mut methods. The rest just forwards to Vec equivalents. Further APIs can be added (carefully) afterwards.

I apologise for the number of lines changed in the PR but they are mostly copy/pasted docs (I wanted them for the testable examples mostly). We should probably find a better way of duplicating them but I think this works for a minimally intrusive experiment.

[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

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: libs
• libs expanded to 8 candidates
• Random selection from Mark-Simulacrum, jhpratt

[ChrisDenton]

 -	   = note: multiple `impl`s satisfying `Vec<_>: aux::Trait` found in the `unstable_impl_method_selection_aux` crate:
 -	           - impl aux::Trait for Vec<u32>;
 -	           - impl aux::Trait for Vec<u64>
 +	   = note: multiple `impl`s satisfying `std::vec::Vec<_>: aux::Trait` found in the `unstable_impl_method_selection_aux` crate:
 +	           - impl aux::Trait for std::vec::Vec<u32>;
 +	           - impl aux::Trait for std::vec::Vec<u64>

Ooph, that's unfortunate. Simplest thing is to rename this type. But I do wonder if that could be fixed.

[Mark-Simulacrum]

Let me know if this is actually waiting on a review -- for now since CI is failing I'll move it back to waiting on author.

[rustbot]

Any special-casing of Miri in the standard library requires review.

cc @rust-lang/miri

[ChrisDenton]

@Mark-Simulacrum sorry about the wait, I have more time to move this forward now. As a reminder to myself as much as you the naming "FallibleVec" is pretty much like "yeet", it's probably not what we end up with but it can act as a placeholder until we figure out that particular bikeshed. Also diagnostics need some work, but I'm told this isn't trivial so I'd rather that not be a blocker atm. As noted in the OP, this is intended to be a MVP. It's likely everything about this API will be argued over but I think we should start with something rather than wait until we've fully designed everything.

@rustbot ready

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[ChrisDenton]

I removed the Allocator API stuff. When I originally made this PR it had been more or less unchanged for ages but now it's had a lot of work done and is nearing stabilization so I want to avoid stepping on any toes. It's easy to add back the Allocator methods in a follow up PR once Allocator is properly stable and things have settled a bit.