Clarify documentation on char::MAX

[GKFX]

As mentioned in #91836 (comment), the documentation on char::MAX is not quite correct – USVs are not "only ones within a certain range", they are code points outside a certain range. I have corrected this and given the actual numbers as there is no reason to hide them.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @scottmcm (or someone else) soon.

Please see the contribution instructions for more information.

[scottmcm]

Hmm, I think part of the problem is that this is the wrong place to be having a conversation about USVs/UCPs. How about just removing that from the documentation of this const, since it's already there at the top of the documentation for char https://doc.rust-lang.org/std/primitive.char.html?

Here's a first stab towards that direction, feel free to take directly or make your own:

/// The highest possible value a `char` can have, `'\u{10FFFF}'`.
///
/// # Examples
///
/// ```
/// # fn something_which_returns_char() -> char { 'a' }
/// let c: char = something_which_returns_char();
/// assert_eq!(c.max(char::MAX), char::MAX);
///
/// let value_after_max = char::MAX as u32 + 1;
/// assert_eq!(char::from_u32(value_after_max), None);
/// ```

And then maybe another PR could refactor the documentation on the primitive to have more about USV vs UCP vs grapheme vs whatever, as well as mention validity invariants, exhaustive matching on char, ...

[GKFX]

It's an unusual constant because for all numeric types, all values in the range type::MIN..=type::MAX are valid values of that type. char breaks that expectation which I think is what brings the conversation in there. Certainly I think you could drop code points from this section and cut it to just stating the permitted range of values with:

The highest possible value a char can have. As a Unicode Scalar Value, a char may be any value in the ranges '\0' to '\u{D7FF}' and '\u{E000}' to '\u{10FFFF}' inclusive.

I like your examples although I would phrase the first assertion as assert!(c <= char::MAX); which means the same thing but is shorter.

[scottmcm]

a char may be any value in the ranges

I just think it's better to have that be a section on char, rather than saying it here, on char::from_u32, etc.

which means the same thing but is shorter

Good point; that's much better.

[GKFX]

I've updated the documentation pretty much as in your version, I'll make a new PR for the documentation directly on char.

[scottmcm]

Thanks for making these PRs!

@bors r+ rollup=always

[bors]

📌 Commit 9aaf52b has been approved by scottmcm