DateTime is the opaque type for all DateTime values. Values of this type represent a valid Date and a time offset from midnight.

zero represents the first millisecond of the first day of the current era. Use it to construct DateTime values:

dateTime zero
|> toISO8601
--> "0-01-01T00:00:00.000Z"


dateTime { zero | year = 2016 }
|> toISO8601
--> "2016-01-01T00:00:00.000Z"


dateTime { zero | year = 2016, month = 5, day = 29, hour = 13 }
|> toISO8601
--> "2016-05-29T13:00:00.000Z"

epoch is the instant in time that represents the first millisecond of the UNIX Epoch.

epoch
|> toISO8601
--> "1970-01-01T00:00:00.000Z"

dateTime constructs a DateTime value given a date and a time. Invalid values are clamped to the nearest valid date and time.

import Time.Date


dateTime { year = 2018
         , month = 13   -- will be clamped
         , day = 25
         , hour = 0
         , minute = 0
         , second = 0
         , millisecond = 47
         }
|> date
--> Time.Date.date 2018 12 25


dateTime { year = 2018
         , month = 13
         , day = 25
         , hour = 0
         , minute = 0
         , second = 0
         , millisecond = 47
         }
|> millisecond
--> 47

date returns a DateTime's Date.

import Time.Date


dateTime { year = 2018
         , month = 0   -- will be clamped
         , day = 25
         , hour = 0
         , minute = 0
         , second = 0
         , millisecond = 47
         }
|> date
--> Time.Date.date 2018 1 25

year returns a DateTime's year.

dateTime { zero | year = 2015 }
|> year
--> 2015

month returns a DateTime's month.

dateTime { zero | month = 7 }
|> month
--> 7


dateTime { zero | month = 0 } -- will be clamped
|> month
--> 1

day returns a DateTime's day.

dateTime { zero | day = 31 }
|> day
--> 31


dateTime { zero | day = 32 } -- will be clamped
|> day
--> 31

weekday returns a DateTime's day of the week.

import Time.Date


dateTime { zero | year = 2018, month = 5, day = 27 }
|> weekday
--> Time.Date.Sun

hour returns a DateTime's hour.

dateTime { zero | hour = 23 }
|> hour
--> 23


dateTime { zero | hour = 24 } -- will be clamped
|> hour
--> 23

minute returns a DateTime's minute.

dateTime { zero | minute = 59 }
|> minute
--> 59


dateTime { zero | minute = 60 } -- will be clamped
|> minute
--> 59

second returns a DateTime's second.

dateTime { zero | second = 59 }
|> second
--> 59


dateTime { zero | second = 60 } -- will be clamped
|> second
--> 59

millisecond returns a DateTime's millisecond.

dateTime { zero | millisecond = 999 }
|> millisecond
--> 999


dateTime { zero | millisecond = 1000 } -- will be clamped
|> millisecond
--> 999

Create a DateTime given its date and millisecond offset

import Time.Date


makeDateTime (Time.Date.date 2018 13 26) 1047
|> date
--> Time.Date.date 2018 13 26


makeDateTime (Time.Date.date 2018 13 26) 1047
|> millisecond
--> 47


makeDateTime (Time.Date.date 2018 13 26) 1047
|> second
--> 1

setDate sets a DateTime's Date.

import Time.Date as TD


dateTime zero
|> setDate (TD.date 2018 5 27)
|> date
--> TD.date 2018 5 27

setYear sets a DateTime's year.

See also Time.Date.setYear.

dateTime zero
|> setYear 2018
|> year
--> 2018

setMonth sets a DateTime's month.

See also Time.Date.setMonth.

dateTime zero
|> setMonth 12
|> month
--> 12

setDay sets a DateTime's day.

See also Time.Date.setDay.

dateTime zero
|> setDay 31
|> day
--> 31

setHour sets a DateTime's hour.

dateTime zero
|> setHour 23
|> hour
--> 23

setMinute sets a DateTime's minute.

dateTime zero
|> setMinute 59
|> minute
--> 59

setSecond sets a DateTime's second. dateTime zero |> setSecond 59 |> second --> 59

setMillisecond sets a DateTime's millisecond.

dateTime zero
|> setMillisecond 999
|> millisecond
--> 999

addYears adds a relative number of years to a DateTime value.

See also Time.Date.addYears.

dateTime { zero | year = 2016 }
|> addYears 2
|> year
--> 2018

addMonths adds a relative number of months to a DateTime value.

See also Time.Date.addMonths.

dateTime { zero | month = 1 }
|> addMonths 1
|> month
--> 2

addDays adds a relative number of days to a DateTime value.

See also Time.Date.addDays.

dateTime { zero | day = 20 }
|> addDays -11
|> day
--> 9

addHours adds a relative number of hours to a DateTime value.

dateTime { zero | hour = 23 }
|> addHours 1
|> hour
--> 0

addMinutes adds a relative number of minutes to a DateTime value.

dateTime { zero | minute = 30 }
|> addMinutes 30
|> minute
--> 0

addSeconds adds a relative number of seconds to a DateTime value.

dateTime { zero | second = 59 }
|> addSeconds 1
|> second
--> 0

addMilliseconds adds an absolute number of milliseconds to a DateTime value.

dateTime { zero | second = 10, millisecond = 1 }
|> addMilliseconds 999
|> second
--> 11

compare two DateTimes.

import Basics exposing (Order(..))


epoch
|> addMilliseconds -1
|> Time.DateTime.compare (dateTime
                           { year = 1969
                           , month = 12
                           , day = 31
                           , hour = 23
                           , minute = 59
                           , second = 59
                           , millisecond = 999
                           }
                         )
--> EQ

DateTimeDelta represents the difference between two DateTime values in terms of each of the different "units".

See Time.DateTime.delta for an "aha!" example.

delta computes the relative difference between two DateTime values. See also Time.Date.delta.

upper : DateTime
upper = dateTime
    { year = 1970
    , month = 1
    , day = 1
    , hour = 0
    , minute = 0
    , second = 0
    , millisecond = 0
    }


upper
|> addYears -1
|> delta upper
--> { years = 1
--> , months = 12
--> , days = 365
--> , hours = 8760
--> , minutes = 525600
--> , seconds = 31536000
--> , milliseconds = 31536000000
--> }


-- Note what is counted is the number of transitions
-- to get from one unit to another.  Hence
-- the following shows that the difference of
-- 1 day makes a big difference when it separates
-- Dec 31 and Jan 1 as shown here.  Observe
-- that years, months, and days are the same because
-- each only requires one transition to get from
-- one date to the other.


upper
|> addDays -1
|> delta upper
--> { years = 1
--> , months = 1
--> , days = 1
--> , hours = 24
--> , minutes = 1440
--> , seconds = 86400
--> , milliseconds = 86400000
--> }

isValidTime returns True if the given hour, minute, second and millisecond represent a valid time of day.

isValidTime 24 0 0 0
--> False


isValidTime 23 59 59 999
--> True

toTimestamp converts a DateTime value to its UNIX timestamp representation as milliseconds.

epoch
|> toTimestamp
--> 0.0

fromTimestamp converts the millisecond representation of a UNIX timestamp into a DateTime value.

fromTimestamp 0.0
--> epoch

toTuple converts a DateTime into a (year, month, day, hour, miunte, second, millisecond) tuple.

DEPRECATED - unavailable in Elm 0.19

toTuple epoch
--> (1970, 1, 1, 0, 0, 0, 0)

fromTuple converts a (year, month, day, hour, minute, second, millisecond) tuple into a DateTime.

DEPRECATED - unavailable in Elm 0.19

fromTuple (1970, 1, 1, 0, 0, 0, 0)
--> epoch

toISO8601 renders a DateTime in ISO8601 format.

DEPRECATED: this is used as a hack for the compare function above; it is not exposed -- use the functionality in Iso8601 instead.