RFC: Time Library 0.3

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

RFC: Time Library 0.3

Ashley Yakeley
Please take a look at my third draft of a replacement for the standard
time library.
http://semantic.org/TimeLib/

Take a look at the Haddock documentation:
http://semantic.org/TimeLib/doc/html/

Download the source:
http://semantic.org/TimeLib/TimeLib-0.3.tar.gz

Or keep up-to-date:
darcs get http://semantic.org/TimeLib/TimeLib/

It needs GHC 6.4.1. (I haven't tested with 6.4 or other compilers.) It
consists of two separate Cabal packages, "fixed" and "time", which can
be installed in the usual way. See the README file.

This release should be close to being ready to become part of the
libraries distributed with some future version of GHC. I'm interested in
any remaining issues.

Major changes since 0.2:

* The code has been reorganised into two separate packages, "fixed",
containing only Data.Fixed for fixed-point arithmetic, and "time",
containing everything else.

* The modules in "time" have been reorganised. The three "first level"
modules, Data.Time.*, contain functionality that most ordinary users
want. The "root" module, Data.Time simply re-exports these three. The
"second level" modules, Data.Time.*.*, contain more specialised
functionality.
http://semantic.org/TimeLib/doc/html/

Some points (largely repeated from the 0.2 RFC):

1.  There is no leap second table provided, though there is a type
(LeapSecondTable) for such things. Any software compiled with a fixed
table would soon become out of date.

2. There is no table of time-zones provided, since these also change.
However, if there's a good way of getting this from the TZ database on
the machine, I'll add that.

It is actually possible to get the local time-zone for any given time,
indeed one of the test programs finds your local summertime transitions.
The Timezone type includes name, minutes of offset, and a "summertime"
flag.

3. The TimeLocale type comes from the already existing System.Locale.

4. The "fixed" package includes Data.Fixed which provides a fixed-point
arithmetic type (wrapper around Integer). It allows dealing with seconds
as a single thing, rather than as an integer/picoseconds pair. It should
probably be merged into base.

5. I don't have any text-parsing functionality for times. This is a fair
amount of work, so it would be good to know sensible requirements.

6. Time as measured by the CPU since system startup remains in
System.CPUTime, which TimeLib does not intend to replace.

--
Ashley Yakeley, Seattle WA

_______________________________________________
Libraries mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/libraries
Reply | Threaded
Open this post in threaded view
|

Re: RFC: Time Library 0.3

Ross Paterson
On Mon, Feb 06, 2006 at 12:00:44AM -0800, Ashley Yakeley wrote:
> Please take a look at my third draft of a replacement for the standard
> time library.
> http://semantic.org/TimeLib/

It looks very clean.

One oddity I noted was that the Gregorian counterparts of the functions
in Data.Time.Calendar.Julian are split between Data.Time.Calendar
and Data.Time.Calendar.OrdinalDate, the latter having different names.
Data.Time.Calendar.Gregorian?  Then someone will want you to take Julian
and Gregorian out of the function names, I suppose.  You might want to
throw in Julian versions of the startWeek functions for completeness.
There's also the question of replacing some tuples by records.

Might the Clock and LocalTime modules belong under System?

_______________________________________________
Libraries mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/libraries
Reply | Threaded
Open this post in threaded view
|

Re: RFC: Time Library 0.3

Simon Marlow-5
In reply to this post by Ashley Yakeley
Ashley Yakeley wrote:
> Please take a look at my third draft of a replacement for the standard
> time library.
> http://semantic.org/TimeLib/
>
> Take a look at the Haddock documentation:
> http://semantic.org/TimeLib/doc/html/

The changes look really good, nice work!

I propose swapping out the Data.Time library with this one in GHC 6.6,
leaving the old one available as "Time" (in the haskell98 package).
Also, I'm going to propose it for inclusion in Haskell'.

I think the documentation would benefit greatly from a list of examples
(as has been mentioned before).  Anyone like to do this?

Cheers,
        Simon
_______________________________________________
Libraries mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/libraries
Reply | Threaded
Open this post in threaded view
|

Re: RFC: Time Library 0.3

Bjorn Bringert-2
In reply to this post by Ashley Yakeley
Ashley Yakeley wrote:
> Please take a look at my third draft of a replacement for the standard
> time library.
> http://semantic.org/TimeLib/
> ...
> 5. I don't have any text-parsing functionality for times. This is a fair
> amount of work, so it would be good to know sensible requirements.
> ...

I have a simple date/time parsing library here:
http://www.cs.chalmers.se/~bringert/darcs/parsedate/

Perhaps it can be used as a starting point?

This is the main date parsing function:

-- | Parse a date string as formatted by 'formatCalendarTime'.
--
--   The resulting 'CalendarTime' will only have those fields set that
--   are represented by a format specifier in the format string,
--   and those fields will be set to the values given in the date
--   string. If the same field is specified multiple times, the
--   rightmost occurence takes precedence.
--
--   The resulting date is not neccessarily a valid date. For example,
--   if there is no day of the week specifier in the format string,
--   the value of 'ctWDay' will most likely be invalid.
--
--   Format specifiers are % followed by some character. All other
--   characters are treated literally. Whitespace in the format string
--   matches zero or more arbitrary whitespace characters.
--
--   Format specifiers marked with * are matched, but do not set any
--   field in the output.
--
--   Some of the format specifiers are marked as space-padded or
--   zero-padded. Regardless of this, space-padded, zero-padded
--   or unpadded inputs are accepted. Note that strings using
--   unpadded fields without separating the fields may cause
--   strange parsing.
--
--   Supported format specfiers:
--
--    [%%]   a % character.
--
--    [%a]   locale's abbreviated weekday name (Sun ... Sat)
--
--    [%A]   locale's full weekday name (Sunday .. Saturday)
--
--    [%b]   locale's abbreviated month name (Jan..Dec)
--
--    [%B]   locale's full month name (January..December)
--
--    [%c]   locale's date and time format
--           (Thu Mar 25 17:47:03 CET 2004)
--
--    [%C]   century [00-99]
--
--    [%d]   day of month, zero padded (01..31)
--
--    [%D]   date (%m\/%d\/%y)
--
--    [%e]   day of month, space padded ( 1..31)
--
--    [%h]   same as %b
--
--    [%H]   hour, 24-hour clock, zero padded (00..23)
--
--    [%I]   hour, 12-hour clock, zero padded (01..12)
--
--    [%j]   day of the year, zero padded (001..366)
--
--    [%k]   hour, 24-hour clock, space padded ( 0..23)
--
--    [%l]   hour, 12-hour clock, space padded ( 1..12)
--
--    [%m]   month, zero padded (01..12)
--
--    [%M]   minute, zero padded (00..59)
--
--    [%n]   a newline character
--
--    [%p]   locale's AM or PM indicator
--
--    [%r]   locale's 12-hour time format (hh:mm:ss AM\/PM)
--
--    [%R]   hours and minutes, 24-hour clock (hh:mm)
--
--    [%s]   * seconds since '00:00:00 1970-01-01 UTC'
--
--    [%S]   seconds, zero padded (00..59)
--
--    [%t]   a horizontal tab character
--
--    [%T]   time, 24-hour clock (hh:mm:ss)
--
--    [%u]   numeric day of the week (1=Monday, 7=Sunday)
--
--    [%U]   * week number, weeks starting on Sunday,
--             zero padded (01-53)
--
--    [%V]   * week number (as per ISO-8601),
--             week 1 is the first week with a Thursday,
--             zero padded, (01-53)
--
--    [%w]   numeric day of the week, (0=Sunday, 6=Monday)
--
--    [%W]   * week number, weeks starting on Monday,
--             zero padded (01-53)
--
--    [%x]   locale's preferred way of printing dates (%m\/%d\/%y)
--
--    [%X]   locale's preferred way of printing time. (%H:%M:%S)
--
--    [%y]   year, within century, zero padded (00..99)
--
--    [%Y]   year, including century. Not padded
--           (this is probably a bug, but formatCalendarTime does
--           it this way). (0-9999)
--
--    [%Z]   time zone abbreviation (e.g. CET) or RFC-822 style numeric
--           timezone (-0500)
parseCalendarTime ::
     TimeLocale            -- ^ Time locale
     -> String             -- ^ Date format
     -> String             -- ^ String to parse
     -> Maybe CalendarTime -- ^ 'Nothing' if parsing failed.


/Björn
_______________________________________________
Libraries mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/libraries
Reply | Threaded
Open this post in threaded view
|

Re: RFC: Time Library 0.3

Bulat Ziganshin
In reply to this post by Ashley Yakeley
Hello Ashley,

Monday, February 06, 2006, 11:00:44 AM, you wrote:

AY> Please take a look at my third draft of a replacement for the standard
AY> time library.
AY> http://semantic.org/TimeLib/

afai understand, your library should replace "getClockTime"
functionality, but it's not obvious what function what function one
should use. how i can

1) print difference between two wallclock times in form "Elapsed 3.024 seconds"
2) convert CTime (returned by stat() function) to the ClockTime analog
and back. May be that is not intended use of your library, but i does
it in order to "touch" files and print file's datetime stamp in the
human-readable form

at the current moment your library really omits docs. that you have is
comments to functions, why docs should be task-oriented

--
Best regards,
 Bulat                            mailto:[hidden email]



_______________________________________________
Libraries mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/libraries
Reply | Threaded
Open this post in threaded view
|

Re: RFC: Time Library 0.3

Ashley Yakeley
In reply to this post by Ross Paterson
In article <[hidden email]>,
 Ross Paterson <[hidden email]> wrote:

> On Mon, Feb 06, 2006 at 12:00:44AM -0800, Ashley Yakeley wrote:
> > Please take a look at my third draft of a replacement for the standard
> > time library.
> > http://semantic.org/TimeLib/
>
> It looks very clean.

Thank you. This was a design goal.

> One oddity I noted was that the Gregorian counterparts of the functions
> in Data.Time.Calendar.Julian are split between Data.Time.Calendar
> and Data.Time.Calendar.OrdinalDate, the latter having different names.
> Data.Time.Calendar.Gregorian?  Then someone will want you to take Julian
> and Gregorian out of the function names, I suppose.

Julian calendar functions are likely to be rarely used, so I put that in
a second-level module as part of my scheme to keep the common stuff in
Data.Time.* and the less common stuff in Data.Time.*.*.

>  You might want to
> throw in Julian versions of the startWeek functions for completeness.

I may do this. I may also promote isLeapYear from .Calendar.OrdinalDate
to .Calendar if it doesn't screw up the dependencies too much
(.Calendar.Gregorian exists but is hidden: it depends on
.Calendar.OrdinalDate). I suppose I could have isLeapYear in both.

> There's also the question of replacing some tuples by records.

OK, currently we have this:

  toGregorian :: Day -> (Integer, Int, Int)
  fromGregorian :: Integer -> Int -> Int -> Day
    -- clips to ranges

In version 0.1 I had a record type instead:

  data GregorianDay = MkGregorianDay {
    gregorianYear :: Integer,
    gregorianMonth :: Int,
    gregorianDay :: Day
  }

This is a completely new type that is almost, but not quite, isomorphic
to Day. As such, I made it an instance of most of the same classes as
Day. It isn't quite isomorphic, however, since it allows invalid days,
and these needed to be dealt with in all the code that used it.

And it doesn't actually gain us anything. The useful parts of
GregorianDay are the constructor and the access functions, not the type
itself, and it's easier to do that with functions on Day.

I had a class for types such as GregorianDay that were isomorphic to
Day. It just confused people.

> Might the Clock and LocalTime modules belong under System?

Not the whole modules, no, I'd rather keep the pure calculation under
Data. There might be a case for putting the FFI-using functions under
System (getCurrentTime, getPOSIXTime, getTimeZone, getCurrentTimeZone,
getZonedTime, utcToLocalZonedTime) since they all call system functions,
but we'd have to pick a module name. I'll only do it if a lot of people
think it's a good idea, otherwise I'm happy with keeping everything
under Data.Time.

--
Ashley Yakeley, Seattle WA
WWED? http://www.cs.utexas.edu/users/EWD/

_______________________________________________
Libraries mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/libraries
Reply | Threaded
Open this post in threaded view
|

Re: RFC: Time Library 0.3

Ashley Yakeley
In reply to this post by Bulat Ziganshin
In article <[hidden email]>,
 Bulat Ziganshin <[hidden email]> wrote:

> AY> Please take a look at my third draft of a replacement for the standard
> AY> time library.
> AY> http://semantic.org/TimeLib/
>
> afai understand, your library should replace "getClockTime"
> functionality, but it's not obvious what function what function one
> should use. how i can
>
> 1) print difference between two wallclock times in form "Elapsed 3.024
> seconds"

  do
    t0 <- getCurrentTime
    foo
    t1 <- getCurrentTime
    putStrLn ("Elapsed " ++ (show (diffUTCTime t1 t0)) ++ " seconds")

Of course, this will be off if the clock has had a leap-second step in
between.

> 2) convert CTime (returned by stat() function) to the ClockTime analog
> and back. May be that is not intended use of your library, but i does
> it in order to "touch" files and print file's datetime stamp in the
> human-readable form

  import Data.Time.Clock.POSIX
  type Time_t = Integer
  fromTimeStamp :: Time_t -> UTCTime
  fromTimeStamp = posixSecondsToUTCTime . fromInteger
  toTimeStamp :: UTCTime -> Time_t
  toTimeStamp = truncate . utcTimeToPOSIXSeconds

> at the current moment your library really omits docs. that you have is
> comments to functions, why docs should be task-oriented

I have some use-cases here:
<http://semantic.org/TimeLib/TimeLib/time/test/UseCases.lhs>

--
Ashley Yakeley, Seattle WA
WWED? http://www.cs.utexas.edu/users/EWD/

_______________________________________________
Libraries mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/libraries
Reply | Threaded
Open this post in threaded view
|

Re: RFC: Time Library 0.3

Ashley Yakeley
In reply to this post by Simon Marlow-5
In article <[hidden email]>,
 Simon Marlow <[hidden email]> wrote:

> Ashley Yakeley wrote:
> > Please take a look at my third draft of a replacement for the standard
> > time library.
> > http://semantic.org/TimeLib/
> >
> > Take a look at the Haddock documentation:
> > http://semantic.org/TimeLib/doc/html/
>
> The changes look really good, nice work!

Thanks!

> I propose swapping out the Data.Time library with this one in GHC 6.6,
> leaving the old one available as "Time" (in the haskell98 package).
> Also, I'm going to propose it for inclusion in Haskell'.

Should I create a new package as http://darcs.haskell.org/packages/time 
? The source is already in a darcs repository, but it might not be
arranged in the right way.

> I think the documentation would benefit greatly from a list of examples
> (as has been mentioned before).  Anyone like to do this?

I'm not sure of the best way to publish these. Should they just appear
in the haddock?

--
Ashley Yakeley, Seattle WA
WWED? http://www.cs.utexas.edu/users/EWD/

_______________________________________________
Libraries mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/libraries
Reply | Threaded
Open this post in threaded view
|

Re: RFC: Time Library 0.3

Simon Marlow-5
Ashley Yakeley wrote:
> In article <[hidden email]>,
>  Simon Marlow <[hidden email]> wrote:
>>I propose swapping out the Data.Time library with this one in GHC 6.6,
>>leaving the old one available as "Time" (in the haskell98 package).
>>Also, I'm going to propose it for inclusion in Haskell'.
>
> Should I create a new package as http://darcs.haskell.org/packages/time 
> ? The source is already in a darcs repository, but it might not be
> arranged in the right way.

Sure, just add it there.  I don't think you have an account on
darcs.haskell.org, right?  Send me an SSH public key and I'll set you up
with one.

>>I think the documentation would benefit greatly from a list of examples
>>(as has been mentioned before).  Anyone like to do this?
>
> I'm not sure of the best way to publish these. Should they just appear
> in the haddock?

Yes, the Haddock is the best place IMO.  Better not to have too many
places to put documentation.

Cheers,
        Simon
_______________________________________________
Libraries mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/libraries