Clarification on Time.from* functions' behavior

[Skyb0rg007]

The documentation for Time.fromSeconds, Time.fromMilliseconds, Time.fromMicroseconds, and Time.fromNanoseconds is (emphasis mine):

These convert the number n to a time value denoting n seconds (respectively, milliseconds, microseconds, or nanoseconds). If the result is not representable by the time type, then the exception Time is raised.

The wording here makes it seem like an implementation should raise the Time exception when the time is too precise for the implementation, but this does not seem to be implemented in practice.

val t = Time.fromNanoseconds 1
val nsec = Time.toNanoseconds t
val () = TextIO.print ("Nanoseconds: " ^ LargeInt.toString nsec ^ "\n")

(* MLton *)
Nanoseconds: 1
(* SML/NJ *)
Nanoseconds: 0
(* Poly/ML *)
Nanoseconds: 0

Proposal:
Make clear what the expected behaviors of the Time conversion functions are.
This could be done by adding the sentence from the Time.fromReal function:

Depending on the resolution of time, fractions of a microsecond may be lost.

[JohnReppy]

I do not remember the rationale for that language, but I suspect that the intention was focused on overflowing the internal representation (rather than underflow).

It might also be useful to add a constant

val tick : time

to the interface that is minimum representable unit of time.

[JohnReppy]

See proposal 2024-001 (Clarification of Time module operations) for the companion proposal.

[dmacqueen]

The first bullet under the Discussion subheading is: This value is unrelated to the underlying operating systems of smallest time quanta. This sentence needs to be edited to make sense. Dave

On Nov 18, 2024, at 10:13 AM, John Reppy ***@***.***> wrote: See proposal 2024-001 (Clarification of Time module operations) <https://github.com/SMLFamily/BasisLibrary/wiki/2024-001-Clarification-of-Time-module-operations> for the companion proposal. — Reply to this email directly, view it on GitHub <#35 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAGXNPO2TCN2RHLOKATDZQL2BIU4JAVCNFSM6AAAAABSAILKESVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDIOBTG44DENJVGY>. You are receiving this because you are subscribed to this thread.

David MacQueen ***@***.***

[JohnReppy]

Thanks for pointing that out. I've removed the word "of", which should make it understandable.

[dmacqueen]

Yes, that and the apostrophe s make it ok. Dave

On Nov 19, 2024, at 11:23 AM, John Reppy ***@***.***> wrote: Thanks for pointing that out. I've removed the word "of", which should make it understandable. — Reply to this email directly, view it on GitHub <#35 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAGXNPJYEEE23F3PSMZDGGD2BOFZ7AVCNFSM6AAAAABSAILKESVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDIOBWGU3DKMJSHE>. You are receiving this because you commented.

David MacQueen ***@***.***

[Skyb0rg007]

I made the edits discussed yesterday to align the synopsis with the discussion sections