RFC: Time Library 0.2

[Simon Marlow]

On 02 November 2005 07:08, Ashley Yakeley wrote:

> In article <slrndmetn6.i4l.jgoerzen at erwin.complete.org>,
>  John Goerzen <jgoerzen at complete.org> wrote:
> 
>> There are just a few functions that a lot of people need, and they
>> are: 
> 
> These can all be done easily if you use UTCTime for epoch time.
> 

[ good examples snipped ]

This discussion raises a good point, I think: the library is carefully
designed, but perhaps lacks something in accessibility.  Many of the
questions that John raised occurred to me when I browsed the docs, in
general it isn't obvious how to do the easy things.  You demonstrated
that the easy things are in fact easy to do, so it's just a problem of
presentation.

That can be addressed in two ways: 

  - change names to be more friendly.  If UTCTime is going to 
    be the "linear" time scale that everyone uses to do simple
    calculations, then we should call it something like ClockTime
    or Epoch (better suggestions welcome), noting in the documentation
    that it is UTC.  It should be the first thing that you find when
    you browse the docs, too.

  - write up some docs that describe how to do the simple things. (I'm 
    not necessarily expecting Ashley to do this, I hope someone else
    will volunteer).

Cheers,
	Simon

>> (C functions in parens)
>> 
>>  * Convert epoch time to a printable string (ctime)
> 
>   ctime :: UTCTime -> String
>   ctime t = show (utcToLocalTime utc t)
> 
> TODO: add a "Show UTCTime" instance, allowing
> 
>   ctime = show
> 
>>  * Convert epoch time to something like struct tm (localtime/gmtime)
> 
>   gmtime :: UTCTime -> ZonedTime
>   gmtime = zonedTimeFromUTC utc
> 
> TODO: rename zonedTimeFromUTC to utcToZonedTime.
> 
> Depending on exactly what you want it to do, localtime is one of
> these: 
> 
>   -- use time zone at given time
>   localtime :: UTCTime -> IO ZonedTime
>   localtime = utcToLocalZonedTime
> 
>   -- use time zone at current time
>   localtime' :: UTCTime -> IO ZonedTime
>   localtime' t = do
>     zone <- getCurrentTimeZone
>     zonedTimeFromUTC zone t
> 
> The current time zone is different at different times according to the
> summertime rule. It's possible to find out what it is for a given
> time. 
> 
>>  * Convert a struct tm to epoch time (mktime)
> 
>   mktime :: ZonedTime -> UTCTime
>   mktime = ztUTC
> 
> TODO: rename ztUTC to something more sensible.
> 
>>  * Convert a struct tm to a printable string (asctime)
> 
>   asctime = ZonedTime -> String
>   asctime = show
> 
>>  * Get the current time in epoch seconds (time)
> 
>   time :: IO UTCTime
>   time = getCurrentTime
> 
>> For many programmers, myself included, the Unix epoch is the most
>> common, pervasive, and useful way to work with time.  Calculations
>> are simple (no need for various TimeDiff sort of things -- just add
>> on x number of seconds), and it is used *everywhere* in the OS,
>> databases, etc.  Something that is based on that, such as the C API,
>> is a plus, IMHO.
> 
> Simon Marlow seems to be generally of the opinion that POSIX time is
> evil and should be expunged (because it's a broken representation of
> UTC). I do however have a few POSIX functions exposed.
> 
> My UTCTime is more or less the simplest correct representation
> (consisting of a day count and a time offset). I think UTCTime should
> remain the main representation of UTC time, but perhaps there should
> be another module (Data.Time.POSIX) for people who need to muck about
> with seconds since epoch. It would have POSIXTime with arithmetic,
> conversion to UTCTime, and getting the current time.
> 
> Thanks...