Rename `VecDeque::truncate` to greatly reduce ambiguity

Proposal

Problem statement

During the stabilization process for VecDeque::truncate_front, the team decided to rename it to retain_back so that the effect would be clearer. That change was good, but it increases some inconsistency and ambiguity.

Motivating examples or use cases

The API before was originally:

• truncate
• truncate_front

Since then, truncate_front was renamed to retain_back and stabilized.

Concurrently, an ACP was accepted for (unstable) truncate_to_range.

Thus, the API now is:

• truncate + #[doc(alias = "retain_front")] — stable in 1.16
• retain_back — stabilizing in 1.98
• truncate_to_range — unstable

It's quite clear what the retain_back method does, thanks to the new name, but the abandonment of the truncate_front name makes truncate more ambiguous.

When truncate_front was a nearby possibility, one could reasonably infer that since push_front and push_back exist, truncate must pair with truncate_front and that it actually meant to truncate the back but that it just wasn't called truncate_back due to a historical mistake. That clue has now been removed.

So the problems now with the name truncate are threefold:

0. ambiguous on whether it truncates the front or back
1. ambiguous on whether it drops N or keeps N
2. inconsistent with another stable method (retain_back)

I'm not saying that any one of those factors is significant enough to rename a stabilized API because I know there's a negative attitude toward API churn, but I'd suggest that the three factors together, taken as a whole, add up to an amount and variety of ambiguity that may push the issue over the line to where you'd like to take action.

Solution sketch

For truncate:

• rename truncate to retain_front (immediately stable)
• add a wrapper truncate that calls retain_front (immediately stable)
• mark truncate as #[deprecated(since = "1.101.0", ...)] or whatever future version you prefer

Then, so long as we're already here, for truncate_to_range:

• just rename it to retain_range, which is cool because it's unstable

I tried to discover the preferred process for this kind of refinement so as to conform my suggestion to it, but I trust my proposed plan will be corrected if I have omitted something.

Links and related work

• https://github.com/rust-lang/rust/issues/156215

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.

Start with this proposal and the related issue #156215, then read the linked feature lifecycle guidance to understand the libs-api review process. The immediate outcome is a libs-api decision on the naming and deprecation proposal; implementation should wait until that decision is made.