ACP: Add `char::to_u32` to access underlying value

[okaneco]

Proposal

Problem statement

There's no explicit char method to access the underlying 4-bytes of data which backs the type.

An as cast, TryFrom/TryInto, or From<u32> must be used to convert to another type. into() has its own issues of usually requiring more type annotations because it cannot be inferred.

edit: I originally wrote that the From<char> for u32 impl was not visible on the char docs, but it does exist. As pointed out, it's here.

Motivating examples or use cases

When casting from char, it's common to blindly as u32 or as u8 since it's the most ergonomic/lazy way to currently write it. When reading or writing code, as casts are generally to be treated with suspicion so having an explicit to_u32() method would lessen the cognitive load of reviewing code with these conversions.

The currently unstable core::ascii::Char type has a to_u8 method.

As of this writing, there are 11 code uses (2 doc comments) of <char> as u32 and 4 uses of <char> as u8 in library\core\src\char\methods.rs. With the unstable truncation methods, we can explicitly write the u8 conversion as <char>.to_u32().truncate::<u8>().

The current documentation of char::from_u32 teaches readers to use an as cast for char to u32 conversion:

Converts a u32 to a char.

Note that all chars are valid u32s, and can be cast to one with as.

Solution sketch

impl char {
    /// Returns the value of `self` as a `u32`.
    pub const fn to_u32(self) -> u32 {
        self as u32
    }
}

Alternatives

1. Do nothing. There are ways to do this today but they're not as explicit except for u32::from.
2. Use the new, unstable truncate/extend API to allow for conversion from char to integers. I was prompted to write this ACP because I realized I mainly still used as casts for floats and from char to u8 for ASCII character processing. I would like to be able to use more explicit casting but it didn't seem appropriate to implement truncate and extend as a one-way conversion from char since it's really not like the other integers. This proposal would be a more minimal library addition.

[cuviper]

The From/Into conversion to u32 is not displayed on the char documentation page,

It is here: https://doc.rust-lang.org/std/primitive.char.html#impl-From%3Cchar%3E-for-u32

[okaneco]

Thanks, I've updated that part of the proposal.

[tgross35]

Note that if accepted, this should probably take self rather than &self (small Copy value)

[okaneco]

Changed to take by value instead of reference.

I know that's a longstanding issue but couldn't remember which was preferred. I think there are a few issues from the fallout of AsciiExt.

Relevant issues on inconsistency
rust-lang/rust#77593
rust-lang/rust#57307

[orlp]

Would it not be better if this function had a meaningful name? E.g.

fn encode_utf32(self) -> u32 { ... }

?

[kpreid]

Whether that is a meaningful name depends on the use case. In particular, if your use case is “I want to 'do arithmetic' on individual Unicode scalar values”, then mentioning encoding (to UTF-32 or otherwise) is a distraction and may lead readers to conclude it is not the right function. Also, the opposite function is already named from_u32().

(Tangentially, it would be good if the documentation for char and its functions mentioned the equivalence between u32 scalar values and UTF-32. Right now, most of the char documentation mentions scalar values but there is one mention of UTF-32 instead, in the documentation of impl TryFrom<char> for usize.)