|
1 | | -{- | "Data.Thyme" is a speed-optimized rewrite (with a bit of extra type-safety) |
2 | | -of the excellent "Data.Time" module in the @time@ library. |
3 | | -
|
4 | | -= Design |
5 | | -
|
6 | | -== Implementation |
7 | | -
|
8 | | -The performance improvement of "Data.Thyme" comes chiefly from representing |
9 | | -times internally as primitive unlifted 'Data.Int.Int64' instead of |
10 | | -lifted 'Integer', as is done in "Data.Time". |
11 | | -
|
12 | | -The tradeoffs for this design can be generalized as: |
13 | | -
|
14 | | - * Data.Time.Clock.'Data.Time.Clock.DiffTime' has a precision |
15 | | - of /1 picosecond/. |
16 | | -
|
17 | | - - Data.Thyme.Clock.'Data.Thyme.Clock.DiffTime' has a precision |
18 | | - of /1 microsecond/. |
19 | | -
|
20 | | - * Data.Time.Clock.'Data.Time.Clock.UTCTime' has unbounded range. |
21 | | -
|
22 | | - - Data.Thyme.Clock.'Data.Thyme.Clock.UTCTime' has a range of about a |
23 | | - half million years, from /-290419-11-07 19:59:05.224192 UTC/ |
24 | | - to /294135-11-26 04:00:54.775807 UTC/. It is therefore not |
25 | | - Y294K-compliant. |
26 | | -
|
27 | | -
|
28 | | -
|
29 | | -"Data.Thyme" uses strict and unpacked tuples throughout, e.g. 'YearMonthDay' or |
30 | | -'Data.Thyme.Calendar.WeekDate.WeekDate'. Descriptive 'Int' synonyms such |
31 | | -as 'Year' and 'DayOfMonth' are also provided. |
32 | | -
|
33 | | -On platforms where 'Int' is 64-bits wide, types with an 'Enum' instance |
34 | | -such as 'Day' can be used as 'Data.IntMap.Key's for 'Data.IntMap.IntMap', preferably |
35 | | -via the @EnumMap@ wrapper provided by |
36 | | -<http://hackage.haskell.org/package/enummapset-th>. In any case the 'Ord' |
37 | | -instances are much faster, if you must use 'Data.Map.Map'. |
38 | | -
|
39 | | -== API |
40 | | -
|
41 | | -Conversions are provided as "Control.Lens.Iso"s from the |
42 | | -<http://hackage.haskell.org/package/lens lens> package, while |
43 | | -'Data.AdditiveGroup.AdditiveGroup', 'Data.VectorSpace.VectorSpace' and |
44 | | -'Data.AffineSpace.AffineSpace' from |
45 | | -<http://hackage.haskell.org/package/vector-space vector-space> allow for |
46 | | -more principled operations instead of 'Num', 'Fractional' & al. |
47 | | -
|
48 | | -"Data.Thyme.Time" is a drop-in replacement module compatible with |
49 | | -"Data.Time". |
50 | | -
|
51 | | -= Brief Tutorial By Example |
52 | | -
|
53 | | -===== Let's start by getting the current UTC date and time from the local system clock. |
54 | | -
|
55 | | -@ |
56 | | -import "Data.Thyme.Clock" |
57 | | -
|
58 | | -__t₀__ <- 'Data.Thyme.Clock.getCurrentTime' |
59 | | -'show' __t₀__ |
60 | | -@ |
61 | | -@ |
62 | | -"2016-04-06 03:50:11.159991 UTC" |
63 | | -@ |
64 | | -
|
65 | | -===== What date and time is it in my local time zone, formatted to my default locale? |
66 | | -
|
67 | | -@ |
68 | | -import "Control.Lens" |
69 | | -import "System.Locale" |
70 | | -import "Data.Thyme.LocalTime" |
71 | | -import "Data.Thyme.Format" |
72 | | -
|
73 | | -tz <- 'Data.Thyme.LocalTime.getCurrentTimeZone' |
74 | | -'Data.Thyme.Format.formatTime' 'System.Locale.defaultTimeLocale' \"%c\" $ (tz, __t₀__) 'Control.Lens.Operators.^.' 'Data.Thyme.LocalTime.zonedTime' |
75 | | -@ |
76 | | -@ |
77 | | -"Wed Apr 6 12:50:11 JST 2016" |
78 | | -@ |
79 | | -
|
80 | | -===== What wall-clock time will it be /1000/ seconds from now? |
81 | | -
|
82 | | -@ |
83 | | -import "Data.AffineSpace" |
84 | | -
|
85 | | -(tz, __t₀__ 'Data.AffineSpace.+^' 'Data.Thyme.Clock.fromSeconds'' 1000) 'Control.Lens.Operators.^.' 'Data.Thyme.LocalTime.zonedTime' . 'Data.Thyme.LocalTime._zonedTimeToLocalTime' . 'Data.Thyme.LocalTime._localTimeOfDay' |
86 | | -@ |
87 | | -@ |
88 | | -13:06:51.159991 |
89 | | -@ |
90 | | -
|
91 | | -===== About how long has it been since the Unix Era began at the Unix Epoch of /midnight, January first, 1970/? |
92 | | -
|
93 | | -@ |
94 | | -import "Data.Thyme.Format.Human" |
95 | | -import "Data.Thyme.Time.Core" |
96 | | -
|
97 | | -"We are about " ++ 'Data.Thyme.Format.Human.humanTimeDiff' (__t₀__ 'Data.AffineSpace..-.' 'Data.Thyme.Time.Core.mkUTCTime' ('Data.Thyme.Time.Core.fromGregorian' 1970 1 1) ('Data.Thyme.Clock.hhmmss' 0 0 0)) ++ " into the Unix Era." |
98 | | -@ |
99 | | -@ |
100 | | -"We are about 5 decades into the Unix Era." |
101 | | -@ |
102 | | -
|
103 | | -===== Two months from today, what day of the week will it be? |
104 | | -
|
105 | | -@ |
106 | | -import "Data.Thyme.Calendar" |
107 | | -
|
108 | | -'Data.Thyme.Format.formatTime' 'System.Locale.defaultTimeLocale' \"%A\" $ 'Control.Lens.Getter.view' 'Data.Thyme.Calendar.WeekDate.weekDate' $ 'Control.Lens.Setter.over' 'Data.Thyme.Calendar.gregorian' ('Data.Thyme.Calendar.gregorianMonthsClip' 2) $ 'Control.Lens.Getter.view' 'Data.Thyme.Clock._utctDay' __t₀__ |
109 | | -@ |
110 | | -@ |
111 | | -\"Monday\" |
112 | | -@ |
113 | | -
|
114 | | --} |
115 | | - |
| 1 | +-- | This simply re-exports some commonly-used modules. |
116 | 2 | module Data.Thyme |
117 | 3 | ( module Data.Thyme.Calendar |
118 | 4 | , module Data.Thyme.Clock |
|
0 commit comments