PanagiotisGeorgiadis/elm-datetime - version: 1.3.0

for more information visit the package's GitHub page

Package contains the following modules:

DateTime

Latest version of the package Latest Elm version supported CircleCI Status of direct dependencies License of the package

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.

 

Constructing a DateTime

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.

Isomorphic DateTime construction

 

You can also attempt to construct a DateTime by providing its' constituent parts as raw data.

RawParts to Maybe DateTime

 

Constructing a Calendar.Date

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.

Posix to Calendar.Date

You can attempt to construct a Calendar.Date by providing its' constituent parts as raw data as shown in the diagram below.

RawParts to Calendar.Date

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.

 

Constructing a Clock.Time

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.

Posix to Clock.Time

You can attempt to construct a Clock.Time by providing its' constituent parts as raw data as shown in the diagram below.

RawParts to Clock.Time

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.