What is a "perfect" conversion, for the From trait?

[sunfishcode]

Location

This wording appears in the documentation for the From trait.

Summary

The From trait has this note:

Note: This trait must not fail. The From trait is intended for perfect conversions. If the conversion can fail or is not perfect, use TryFrom.

It's not clear what "perfect" means here. Is there an established meaning for "perfect"? Does it mean lossless, and/or unambiguous? Or does it mean something else?

[compiler-errors]

It means infallible, like it should be a conversion that does not need to return a Result and doesn't fail when called.

[sunfishcode]

If it means infallible, then it's confusing that it says "If the conversion can fail or is not perfect", which makes it sound like "can fail" is different from "is not perfect".

[scottmcm]

A couple heuristics that I use:

• It's the only plausible way to get one from other. If there are multiple reasonable-but-different ways, then the conversion is generally better done with named methods instead, so that people pick.

• The resulting value is the "same" in some not-rust-type-system category. Like 1_u8 and 1.0_f32 are the same real number, even though there's no "real number" type in Rust. And vec![1, 4, 2] and [1, 4, 2] are the same sequence, despite being different types.

• You can recover the original value via TryFrom, so A::try_from(B::from(a)).unwrap() == a.

[asquared31415]

which makes it sound like "can fail" is different from "is not perfect".

They are different intentionally, and the TryFrom trait, which is linked in From's docs, clarifies this a bit more:

Simple and safe type conversions that may fail in a controlled way under some circumstances.

and its example:

This is useful when you are doing a type conversion that may trivially succeed but may also need special handling. For example, there is no way to convert an i64 into an i32 using the From trait, because an i64 may contain a value that an i32 cannot represent and so the conversion would lose data.

It also links back to From using the same "perfect" wording:

The From trait is intended for perfect conversions, so the TryFrom trait informs the programmer when a type conversion could go bad and lets them decide how to handle it.

Here "perfect" means "without losing any information" in a very vague sense, or at least something along the lines of "every element in the source type has exactly one element in the target type and there is only one way to do this conversion".

I think that the current wording in the docs isn't amazing, but I'm not sure how else to explain it (ideally without duplicating too much documentation between the traits, that will fall out of sync).

[Dylan-DPC]

Closing this as this was more a clarification issue than a bug or any enhancement.

[scottmcm]

There's also now https://doc.rust-lang.org/stable/std/convert/trait.From.html#when-to-implement-from to elaborate on what this means, thanks to #114564