Clarify sub-millisecond precision is allowed #805
Conversation
"Millisecond precision is required" could be interpreted as a requirement for input to be valid TOML. This commit adds examples of valid TOML time values that uses tens of second to remove the ambiguity.
|
I don't think this is necessary, but it certainly cannot hurt. |
|
However, upon reflection, I think a little more explanation in the text is necessary. We currently state that "millisecond precision is required," but it's unclear that we are referring to the parsers' level of support for precision, not the users' precision, which should be arbitrary. Perhaps we ought to change the precision text to read as follows:
Then, if it wouldn't be too much detail, we could indicate what the resulting values would look like by referring back to the examples, to make this crystal clear.
Thoughts? |
|
I would write "must support" instead of "should support", otherwise this sounds good. But I would tend not to the include the truncation example – I think the spec is perfectly clear even without it. Also keep in mind that we repeat this language three times (for each of the relevant date/time types), so brevity is important. I suppose you mean to include the truncation example just once. Sure, that would be possible, but I don't think it's necessary. |
|
It was intended to be succinct; I wrote it knowing that it would be repeated. We don't need to show the truncation example, but I do insist that we put emphasis on the word truncated. I didn't intend to relax the millisecond precision requirement, which I'm almost certain some implementations will do anyway. I was only trying to avoid saying "must" twice, and I forgot the phrases in RFC 2119 that meant the same thing. We technically aren't using RFC 2119 now, but #870 may push us that way. Let's return to the original wording somewhat for that first sentence.
|
There was a problem hiding this comment.
toml.md
Here are the changes to clarify that the sub-millisecond precision is a requirement specifically for the implementations to support. (I tried to find a way to request explicit changes, but it seems I can't do this, for whatever reason. You'll have to compare your version and the version I attached here for the differences.)
|
@pradyunsg This PR draws an important distinction and relieves some potential confusion. What are your thoughts? |
|
@pradyunsg This has been sitting dormant for four months. Does anything more need done? |
|
@pradyunsg It's been six months. What are your thoughts on this? Can we merge it for v1.1.0? |
|
Pleeeeese! |
"Millisecond precision is required" could be interpreted as a requirement for input to be valid TOML. This commit adds examples of valid TOML time values that uses tens of second to remove the ambiguity.
Refs: toml-rs/toml-rs#416
Co-Authored-By: Dave Ostroske [email protected]