stabilize int_error_matching

[eopb]

• PR: Make ParseIntError and IntErrorKind fully public #55705
• Tracking issue: ParseIntError and ParseFloatError does not allow to introspect the cause #22639

The original PR was my first std contribution. Since then a few people have called for it to be stabilized. See discussion on #22639

A significant number of people seem to be using this feature in their projects https://github.com/search?p=2&q=%23%21%5Bfeature%28int_error_matching%29%5D&type=Code

Unanswered questions

If this is to be stabilized, I think that the terminology has to be improved: IntErrorKind uses Underflow to refer to negative overflow, but underflow usually means when the absolute value of a floating-point number is so small it becomes 0 (or a subnormal).

Originally posted by @tspiteri in #22639 (comment)

Maybe PosOverflow and NegOverflow?

Originally posted by @JarrettBillingsley in #22639 (comment)

I personally don't think it needs to change as in this position underflow is clearly associated with integers and seems consistent with other uses of the word underflow in std. I am interested to hear others thoughts.

[rust-highfive]

r? @KodrAus

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

[KodrAus]

I definitely don’t think we should call the variant Underflow, because even though we’re not really consistent internally, the term does refer to a specific failure mode that doesn’t apply here. I don’t think that’s a reason to repurpose the term, just so that we don’t leave any doubt for callers trying to interpret these error messages.

In general though I think this is a useful stabilization! I’ll kick off the FCP and add my concern for underflow to let others weigh in.

@rfcbot fcp merge

[rfcbot]

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

• @Amanieu
• @KodrAus
• @dtolnay
• @sfackler
• @withoutboats

Concerns:

• underflow vs negative overflow (stabilize int_error_matching #76455 (comment))

Once a majority of reviewers approve (and at most 2 approvals are outstanding), 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.

[KodrAus]

@rfcbot concern underflow vs negative overflow

See #76455 (comment) I think we should use an accurate name for the negative overflow variant, rather than repurposing the term underflow, which has a specific meaning for floating point numbers.

[withoutboats]

I've always used the term "underflow" for ints wrapping beyond their lower bound and didn't realize this was not common usage.

[KodrAus]

I actually didn’t even know underflow had a special meaning and used it the same way until I think I got assigned a docs PR once to use overflow for integers that would exceed their upper or lower bound. It turns out underflow specifically refers to floating point numbers that are too close to zero to distinguish from it.

[bors]

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

Note that reviewers usually do not review pull requests until merge conflicts are resolved! Once you resolve the conflicts, you should change the labels applied by bors to indicate that your PR is ready for review. Post this as a comment to change the labels:

@rustbot modify labels: +S-waiting-on-review -S-waiting-on-author

[Darksonn]

This was discussed on the users forum: link.

[eopb]

I will open a new PR soon addressing these issues rather than continuing this one.

I will also need to take a good look at the parsing code to ensure it produces the correct errors.

As I am rather busy right now I will have an update within the next few weeks.

[KodrAus]

Thanks for working through all this @ethanboxx!

If you don't need to make many changes then we could probably continue on this PR, since it's already got its FCP going.

[eopb]

Closing in favour of #77640