Add trim_start, trim_end etc.; deprecate trim_left, trim_right, etc. in future

[varkor]

Adds the methods: trim_start, trim_end, trim_start_matches and trim_end_matches.
Deprecates trim_left, trim_right, trim_left_matches and trim_right_matches starting from Rust 1.33.0, three versions from when they'll initially be marked as being deprecated, using the future deprecation from #30785 and #51681.

Fixes #30459.

[rust-highfive]

r? @cramertj

(rust_highfive has picked a reviewer for you, use r? to override)

[cramertj]

Assigning someone on libs... r? @dtolnay

[dtolnay]

On my computer this example shows up like this:

The whitespace at the low byte positions of the string appear on the left, and the right-to-left characters in the high byte positions appear on the right. The documentation explains that trim_start trims the right side of right-to-left text, and in fact trimming is taking place, but as rendered it appears that no trimming has happened. Is this something that would be clear to people who regularly deal with right-to-left? Is there a way to make an example that is less ambiguous for people not experienced with right-to-left?

[varkor]

That's a good point. Examples are tricky with mixed text directions. I'll try to come up with a better example.

[varkor]

I've added whitespace to both sides. It should be clear to anyone that the leading whitespace is being trimmed, even if they don't realise which spaces are actually being removed. Anything more subtle requires actually explaining how mixed directional text is actually rendered, which we probably don't want to do here.

[dtolnay]

I believe we will want to land these methods as stable straight away. The #30785 future deprecation doesn't help if it takes us another 3 cycles to stabilize the replacement -- the idea was to leave 3 cycles of transition time during which both new and old are usable without warnings.

[varkor]

Oh, of course!

[dtolnay]

This can be removed here and in the doc tests if we are landing these as stable.

[varkor]

Whoops, fixed.

[dtolnay]

I don't think the fix has been pushed yet.

[varkor]

I just noticed I pushed the wrong branch. It's definitely fixed now 😅

[dtolnay]

@rust-lang/libs this PR adds stable methods intended as direct replacements for the existing str::trim_left, trim_right, trim_left_matches, trim_right_matches.

impl str {
    pub fn trim_start(&self) -> &str;

    pub fn trim_end(&self) -> &str;

    pub fn trim_start_matches<'a, P>(&'a self, pat: P) -> &'a str
    where
        P: Pattern<'a>;

    pub fn trim_end_matches<'a, P>(&'a self, pat: P) -> &'a str
    where
        P: Pattern<'a>,
        P::Searcher: ReverseSearcher<'a>;
}

The signatures are the same but the new names better describe the behavior on right-to-left input text. The old names will display a deprecation notice in the documentation but are not set to warn until 1.33.0.

@rfcbot fcp merge

[rfcbot]

Team member @dtolnay has proposed to merge this. The next step is review by the rest of the tagged teams:

• @Kimundi
• @SimonSapin
• @alexcrichton
• @dtolnay
• @sfackler
• @withoutboats

Concerns:

• deprecation-schedule resolved by Add trim_start, trim_end etc.; deprecate trim_left, trim_right, etc. in future #52994 (comment)

Once a majority of reviewers approve (and none object), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[withoutboats]

@rfcbot concern deprecation-schedule

I'm a big +1 on adding the more accurately named methods, but I'm uncertain that deprecating the old methods in 1.33 is the best decision. I don't see any discussion on that choice on this or the issue it closes. I'm not against it, I just want to raise it for discussion and see if anyone has anything to say about it before this goes into FCP.

I've checked my box so once I resolve this concern the PR will go into FCP.

[BurntSushi]

@withoutboats I have a vague unstructured opinion that we're a bit too quick to deprecate things in general, and I would probably apply it here too. But it's honestly a pretty weak opinion, particularly if we do add the new methods anyway. Here's a trichotomy to make my view a little clearer:

1. Do nothing. Keep current methods; don't add new methods.
2. Add new methods. Keep current methods and don't deprecate them.
3. Add new methods. Keep current methods and deprecate them.

On a small scale, I'd probably go with (3) (because clarifications like this are nice). On a larger scale, I'd probably go with (1) (because there's churn, and I think there is a lot more room to accept warts). Route (2) seems somewhat inconsistent with what we've done in the past. That is, I don't think we have a lot of "this thing is an exact alias to this other thing." So in that sense, if we definitely want these new methods, I'd probably just go ahead any deprecate the existing ones.

What thoughts did you have on this?

[varkor]

I don't see any discussion on that choice on this or the issue it closes.

👍I picked "3 releases from now" fairly arbitrarily, as a period that seemed somewhat reasonable. I probably should have clarified that — the FCP seems like as good a time as any to discuss it, though!

[withoutboats]

What thoughts did you have on this?

I really don't know. I guess I feel like these methods are widely used, and so deprecating them will be disruptive. So I'd like some headway before we start issuing warnings. As we can see, @varkor's already done at least some of that by implementing future deprecations & targeting 1.33 for deprecation, but is that enough? I'm not sure.

Some vague questions/thoughts:

• How will we communicate about this future deprecation prior to 1.33 to try to encourage people to switch over (at least for new code)?
• How do the future deprecated methods appear in docs? Does it successfully encourage people to switch? (I already asked varkor this on a separate thread) EDIT: Screenshot in Handle future deprecation annotations  #49179
• What other ways could we encourage people to switch before we start issuing warnings?

I also have no idea how to judge if 3 releases is the correct number.

[SimonSapin]

Considering that:

• Keeping a code base warning-free is generally nice / desired.
• The same code can often be compiled with a range of different Rust versions. For example a library supports the Stable channel, but when contributing to it I might use Nightly to take advantage of tooling (not language or libs) improvements.

I’ve generally argued for not emitting deprecation warnings in Nightly until the recommended replacement is available on stable. So that means a 2 release cycles delay. However that’s a minimum, increasing it to 3 doesn’t cost us much and makes things easier for projects that mostly track Stable but still pin to a specific version, leaving them some more time to upgrade. For example Firefox’s policy is to upgrade 2 weeks after a new Stable is released (modulo blocking bugs).

For projects that have a policy of keeping compat with a specific version older than Stable, they’ll likely not want to bump their requirement for a simple renaming like this and might use #[allow(deprecated)] instead. So I’d be fine with a longer delay before we start emitting warnings.

Does rustdoc show an API as deprecated even before we start emitting warnings based on since? If not I think it should.

[withoutboats]

Does rustdoc show an API as deprecated even before we start emitting warnings based on since? If not I think it should.

Yea, you can see a screenshot in #49179

[withoutboats]

@rfcbot resolve deprecation-schedule

Seems like there's no further progress to be made from discussing the deprecation schedule. Here's my solution:

1. I've opened an issue to discuss automating rename deprecations by adding a field to the attribute: Support cargo fix for rename deprecations #53802
2. We should make sure to include in the release notes all future deprecations, so that people will see them (that is, these will be in the release notes 3 times before the deprecation actually happens).

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[alexcrichton]

@bors: r+

[bors]

📌 Commit ff79670 has been approved by alexcrichton

[bors]

⌛ Testing commit ff79670 with merge 8b7f164...

[bors]

☀️ Test successful - status-appveyor, status-travis
Approved by: alexcrichton
Pushing 8b7f164 to master...

[dtolnay]

Tagging relnotes -- this a future deprecation in 1.33.0 so it will be noted in the next three release notes.