Skip to content

Commit 5745e1b

Browse files
committed
FromStr: Rework explanation of FromStr/Display round-tripping
- Drop the phrasing "usually a mistake". - Mention that `Display` may not be lossless. - Drop a misplaced parenthetical about round-tripping that didn't fit the paragraph it was in.
1 parent 5f82fb7 commit 5745e1b

File tree

1 file changed

+5
-6
lines changed

1 file changed

+5
-6
lines changed

library/core/src/str/traits.rs

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -752,20 +752,19 @@ unsafe impl SliceIndex<str> for ops::RangeToInclusive<usize> {
752752
/// parse an `i32` with `FromStr`, but not a `&i32`. You can parse a struct that
753753
/// contains an `i32`, but not one that contains an `&i32`.
754754
///
755-
/// # Input format
755+
/// # Input format and round-tripping
756756
///
757757
/// The input format expected by a type's `FromStr` implementation depends on the type. Check the
758758
/// type's documentation for the input formats it knows how to parse. Note that the input format of
759759
/// a type's `FromStr` implementation might not necessarily accept the output format of its
760-
/// `Display` implementation; thus, calling `.parse()` on the output from `Display` is usually a
761-
/// mistake, unless the type has provided and documented additional guarantees about its `Display`
762-
/// and `FromStr` implementations.
760+
/// `Display` implementation, and even if it does, the `Display` implementation may not be lossless
761+
/// so the round-trip may lose information.
763762
///
764-
/// If a type happens to have a lossless `Display` implementation whose output is meant to be
763+
/// However, if a type has a lossless `Display` implementation whose output is meant to be
765764
/// conveniently machine-parseable and not just meant for human consumption, then the type may wish
766765
/// to accept the same format in `FromStr`, and document that usage. Having both `Display` and
767766
/// `FromStr` implementations where the result of `Display` cannot be parsed with `FromStr` may
768-
/// surprise users. (However, the result of such parsing may not have the same value as the input.)
767+
/// surprise users.
769768
///
770769
/// # Examples
771770
///

0 commit comments

Comments
 (0)