From 742014e7e3576f3053e7c63fc930c4d5b5b7a477 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Tue, 3 Jun 2025 15:39:46 -0700 Subject: `Display`: Rework explanation of `FromStr`/`Display` round-tripping - Drop "usually a mistake" - Add phrasing from `FromStr` about round-tripping, and about how the inability to round-trip may surprise users. --- library/core/src/fmt/mod.rs | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/library/core/src/fmt/mod.rs b/library/core/src/fmt/mod.rs index c25ef9ba512..145e581d1fb 100644 --- a/library/core/src/fmt/mod.rs +++ b/library/core/src/fmt/mod.rs @@ -934,8 +934,13 @@ pub use macros::Debug; /// It may omit internal state, precision, or other information the type does not consider important /// for user-facing output, as determined by the type. As such, the output of `Display` might not be /// possible to parse, and even if it is, the result of parsing might not exactly match the original -/// value. Calling `.parse()` on the output from `Display` is usually a mistake, unless the type has -/// provided and documented additional guarantees about its `Display` and `FromStr` implementations. +/// value. +/// +/// However, if a type has a lossless `Display` implementation whose output is meant to be +/// conveniently machine-parseable and not just meant for human consumption, then the type may wish +/// to accept the same format in `FromStr`, and document that usage. Having both `Display` and +/// `FromStr` implementations where the result of `Display` cannot be parsed with `FromStr` may +/// surprise users. /// /// # Internationalization /// -- cgit 1.4.1-3-g733a5