e1d3594fe70a106e44975836db46761d72165622
[haskell-report.git] / report / time.verb
1 %**<title>The Haskell 98 Library Report: Dates and Times</title>
2 %**~header
3 \section{Dates and Times}
4 \label{time}
5 \index{time}
6 \index{time of day}\index{clock time}
7
8 %% Note: HBC has Leap year calculations too.
9 %% My feeling is that these are unnecessary given the much stronger
10 %% ability here to find the differences between dates.
11
12 \outline {
13 \inputHS{lib-hdrs/Time}
14 }
15 \outline{
16 \inputHS{lib-hdrs/Time1}
17 }
18
19 The @Time@ library provides standard functionality for clock times,
20 including timezone information. It follows RFC~1129 in its use of
21 Coordinated Universal Time (UTC).
22
23 @ClockTime@ is an abstract type, used for the system's internal clock
24 time.  Clock times may be compared directly or converted to a calendar
25 time @CalendarTime@ for I/O or other manipulations.
26 @CalendarTime@ is a user-readable and manipulable representation of
27 the internal @ClockTime@ type.  The numeric fields have the following
28 ranges.
29 \outline{
30 \begin{tabbing}
31 \ignorehtml{
32 \ \ \ \=ctpicosec\ \ \ \ \=-maxInt\ \=\ldots\ \=$(10^{12})-1$\ \ \ \ \ \=\kill}
33 \>\underline{Value}\>\>\underline{Range}\>\>\underline{Comments} \\
34 \\
35 \>ctYear\>\>-maxInt\'$\ldots$\>maxInt\>Pre-Gregorian dates are inaccurate \\
36 \>ctDay\>\>1\'$\ldots$\>31 \\
37 \>ctHour\>\>0\'$\ldots$\>23\\
38 \>ctMin\>\>0\'$\ldots$\>59\\
39 \>ctSec\>\>0\'$\ldots$\>61\>Allows for two Leap Seconds\\
40 \>ctPicosec\>\>0\'$\ldots$\>$(10^{12})-1$ \\
41 \>ctYDay\>\>0\'$\ldots$\>365\>364 in non-Leap years \\
42 \>ctTZ\>\>-89999\'$\ldots$\>89999\>Variation from UTC in seconds
43 \end{tabbing}
44 }
45 The "ctTZName" field is the name of the time zone.  The "ctIsDST" field
46 is @True@ if Daylight Savings Time would be in effect, and @False@
47 otherwise.
48 The @TimeDiff@ type records the difference between two clock times in
49 a user-readable way.
50
51 Function @getClockTime@ returns the current time in its internal
52 representation.  The expression
53 @addToClockTime@~"d"~"t" adds a time difference "d" and a
54 clock time "t" to yield a new clock time.  The difference "d" may be either
55 positive or negative.  The expression @diffClockTimes@~"t1"~"t2"
56 returns the difference between two clock times "t1" and "t2" as a
57 @TimeDiff@. 
58
59 Function @toCalendarTime@~"t" converts "t" to a local time, modified
60 by the timezone and daylight savings time settings in force at the
61 time of conversion.  Because of this dependence on the local environment,
62 @toCalendarTime@ is in the @IO@ monad.
63
64 Function @toUTCTime@~"t" converts "t" into a @CalendarTime@
65 in standard UTC format.
66 @toClockTime@~"l" converts "l" into the corresponding internal
67 @ClockTime@ ignoring the contents of the "ctWDay", "ctYDay",
68 "ctTZName", and "ctIsDST" fields.
69
70 Function @calendarTimeToString@ formats
71 calendar times using local conventions and a formatting string.
72
73 \subsection{Library {\tt Time}}
74 \inputHS{lib-code/Time}
75
76 %**~header