for more information visit the package's GitHub page
Package contains the following modules:
The 0.19 version of Elm introduced some important changes in the Time API which is now split into a separate package.
The DateTime package was inspired because date and time is a crucial part on our everyday lives and most of the projects we are working on rely heavily on the correct interpretation of both. This means that whenever we need to handle date or time we need to be sure that it is a valid DateTime. In order to guarantee the validity of the DateTime but also create a solid package we had to compromise on using UTC time.
This basically means that all the results that come from the DateTime package are based on UTC and therefore the consumer should be the one that implements timezone specific solutions. That approach makes the DateTime package easier to use without having the overhead of timezones or daylight saving and it also gave us the opportunity to focus on implementing generic DateTime handling functionality instead of having to focus on timezone specific solutions.
The main goal of this package is to serve as an extension of elm/time and to provide a DateTime type that is isomorphic to Time.Posix. This basically means that DateTime can be constructed by a Time.Posix type and it can be converted back to Time.Posix without losing any of it's integrity.
You can construct a DateTime in three different ways:
You can reliably create a DateTime either by providing a Posix or by combining a Calendar.Date and a Clock.Time.
You can also attempt to construct a DateTime by providing its' constituent parts as raw data.
You can create a Calendar.Date by providing a Posix. We should note here though, that since the Posix will contain the milliseconds that
form both a date and a time, the Calendar.Date will drop all the time related information. If you were to transform a
Calendar.Date back to Posix, it would represent the given Date
but it will always default on midnight hours, which means that it
may lose some of the information provided. We've decided that we will not allow a Calendar.Date to Time.Posix conversion since its not an isomorphic one.
You can instead get the milliseconds that represent the given Date
and combine them with the milliseconds that represent a given Time
.
You can attempt to construct a Calendar.Date by providing its' constituent parts as raw data as shown in the diagram below.
There could be some cases where you don't really care about the time but you only need to store the Dates. Of course this will mean that if you try to convert a Calendar.Date to a Posix Time it will always default to midnight hours (00:00:00.000). You can always combine a Calendar.Date with a Clock.Time to construct a DateTime in case you need to.
You can create a Clock.Time by providing a Posix. We should note here though, that since the Posix will contain the milliseconds that
form both a date and a time, the Clock.Time will drop all the date related information. If you were to transform a
Clock.Time back to Posix, it would represent the given Time
but it will always default on the Epoch date (1 Jan 1970), which means that it
may lose some of the information provided. We've decided that we will not allow a Clock.Time to Time.Posix conversion since its not an isomorphic one.
You can instead get the milliseconds that represent the given Time
and combine them with the milliseconds that represent a given Date
.
You can attempt to construct a Clock.Time by providing its' constituent parts as raw data as shown in the diagram below.
Building a timer app could be one of the cases where you don't really care about the Calendar.Date portion of DateTime. This would mean that you only need a Clock.Time in order to keep track of the time. Be very careful though if you want to get a valid Posix Time you would need to convert your Clock.Time to a DateTime by using a Calendar.Date as well.