diff options
| -rw-r--r-- | library/core/src/fmt/mod.rs | 14 | ||||
| -rw-r--r-- | library/core/src/str/traits.rs | 14 |
2 files changed, 28 insertions, 0 deletions
diff --git a/library/core/src/fmt/mod.rs b/library/core/src/fmt/mod.rs index 5978cb660f6..145e581d1fb 100644 --- a/library/core/src/fmt/mod.rs +++ b/library/core/src/fmt/mod.rs @@ -928,6 +928,20 @@ pub use macros::Debug; /// [tostring]: ../../std/string/trait.ToString.html /// [tostring_function]: ../../std/string/trait.ToString.html#tymethod.to_string /// +/// # Completeness and parseability +/// +/// `Display` for a type might not necessarily be a lossless or complete representation of the type. +/// 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. +/// +/// 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 /// /// Because a type can only have one `Display` implementation, it is often preferable diff --git a/library/core/src/str/traits.rs b/library/core/src/str/traits.rs index 4baf9aacad7..b9559c83171 100644 --- a/library/core/src/str/traits.rs +++ b/library/core/src/str/traits.rs @@ -756,6 +756,20 @@ unsafe impl SliceIndex<str> for ops::RangeToInclusive<usize> { /// parse an `i32` with `FromStr`, but not a `&i32`. You can parse a struct that /// contains an `i32`, but not one that contains an `&i32`. /// +/// # Input format and round-tripping +/// +/// The input format expected by a type's `FromStr` implementation depends on the type. Check the +/// type's documentation for the input formats it knows how to parse. Note that the input format of +/// a type's `FromStr` implementation might not necessarily accept the output format of its +/// `Display` implementation, and even if it does, the `Display` implementation may not be lossless +/// so the round-trip may lose information. +/// +/// 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. +/// /// # Examples /// /// Basic implementation of `FromStr` on an example `Point` type: |