search

haskell / time

A time library
http://hackage.haskell.org/package/time
Other
118 stars 78 forks source link

Explain how NominalDiffTime works with LocalTime #169

Closed tomjaguarpaw closed 3 years ago

tomjaguarpaw commented 3 years ago

I couldn't understand how NominalDiffTime works with LocalTime without looking at the source code. I thought it would be helpful to add this comment to save future users from confusion.

(I'm not even completely convinced that NominalDiffTime should work with LocalTime at all; I would prefer the API to force explicit conversion to UTC, but that's another debate.)

AshleyYakeley commented 3 years ago

I don't think there's any assumption about UTC?

If you add "one hour" to "5pm on January 23rd", you get "6pm on January 23rd". That's all.

tomjaguarpaw commented 3 years ago

Hmm, perhaps I am misunderstanding LocalTime. To me, "local time" sounds like the time used in in a particular place. In Europe/London if you add "one hour" to "12:30am on March 28th" you get "2:30am on March 28th" not "1:30am on March 28th". Using addLocalTime for this purpose would be wrong. That makes me think that either addLocalTime is misleadingly named or (more likely) my understanding of what LocalTime represents is wrong.

Could you clarify? If it is my understanding of what LocalTime is that is faulty then I think LocalTime's semantics could bear greater explanation in the Haddock. Why is it called "local" if it does not represent the time used in a particular place?

AshleyYakeley commented 3 years ago

LocalTime is just a date and a time-of-day. It's only an actual time if you also have a time-zone offset. addLocalTime adds time for LocalTimes with the same time-zone offset. Thus, "12:30am on March 28th" plus "one hour" is "1:30am on March 28th", in any given time-zone offset.

You may be thinking of ZonedTime, which is a LocalTime together with a TimeZone.

tomjaguarpaw commented 3 years ago

Doesn't it strike you that LocalTime is a misleading name for "just a date and a time-of-day"? To me "local time" has a well-defined meaning. When the plan lands the captain says "the local time is 10:32". I don't interpret that as meaning "10:32 is just a date and time-of-day". I interpret it as meaning "the inhabitants of this place have 10:32 on their clocks".

tomjaguarpaw commented 3 years ago

Java also uses LocalTime for the same thing as the time library, so maybe this is established terminology, but if so I really do think it bears more explanation.

AshleyYakeley commented 3 years ago

LocalTime is exactly a time that can appear on clocks (I mean, if they have also a date function), I guess?

tomjaguarpaw commented 3 years ago

Aha, thanks, that's very helpful. I will take that into account and submit another PR for your consideration.