isaacseymour / deprecated-time / Time.DateTime

This module defines a time representation based on a Date and the time of day.

DateTimes


type DateTime

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

Constructing DateTimes

zero : Time.Internal.DateTimeData

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

import Time.Iso8601

dateTime zero
|> Time.Iso8601.fromDateTime
--> "0-01-01T00:00:00.000Z"

dateTime { zero | year = 2016 }
|> Time.Iso8601.fromDateTime
--> "2016-01-01T00:00:00.000Z"

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

epoch : DateTime

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

import Time.Iso8601

epoch
|> Time.Iso8601.fromDateTime
--> "1970-01-01T00:00:00.000Z"

dateTime : Time.Internal.DateTimeData -> DateTime

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

makeDateTime : Time.Date.Date -> Basics.Int -> DateTime

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

fromPosix : Time.Posix -> DateTime

fromPosix converts the elm/time Posix representation of a UNIX timestamp into a DateTime value.

import Time
0 |> Time.millisToPosix |> fromPosix
--> epoch

toPosix : DateTime -> Time.Posix

toPosix converts a DateTime value to the equivalent elm/time Posix representation.

import Time

epoch
|> toPosix
--> Time.millisToPosix 0

Inspecting DateTimes

date : DateTime -> Time.Date.Date

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 : DateTime -> Basics.Int

year returns a DateTime's year.

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

month : DateTime -> Basics.Int

month returns a DateTime's month.

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

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

day : DateTime -> Basics.Int

day returns a DateTime's day.

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

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

weekday : DateTime -> Time.Date.Weekday

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 : DateTime -> Basics.Int

hour returns a DateTime's hour.

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

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

minute : DateTime -> Basics.Int

minute returns a DateTime's minute.

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

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

second : DateTime -> Basics.Int

second returns a DateTime's second.

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

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

millisecond : DateTime -> Basics.Int

millisecond returns a DateTime's millisecond.

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

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

Manipulating DateTimes

setDate : Time.Date.Date -> DateTime -> DateTime

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 : Basics.Int -> DateTime -> DateTime

setYear sets a DateTime's year.

See also Time.Date.setYear.

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

setMonth : Basics.Int -> DateTime -> DateTime

setMonth sets a DateTime's month.

See also Time.Date.setMonth.

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

setDay : Basics.Int -> DateTime -> DateTime

setDay sets a DateTime's day.

See also Time.Date.setDay.

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

setHour : Basics.Int -> DateTime -> DateTime

setHour sets a DateTime's hour.

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

setMinute : Basics.Int -> DateTime -> DateTime

setMinute sets a DateTime's minute.

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

setSecond : Basics.Int -> DateTime -> DateTime

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

setMillisecond : Basics.Int -> DateTime -> DateTime

setMillisecond sets a DateTime's millisecond.

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

addYears : Basics.Int -> DateTime -> DateTime

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 : Basics.Int -> DateTime -> DateTime

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 : Basics.Int -> DateTime -> DateTime

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 : Basics.Int -> DateTime -> DateTime

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

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

addMinutes : Basics.Int -> DateTime -> DateTime

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

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

addSeconds : Basics.Int -> DateTime -> DateTime

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

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

addMilliseconds : Basics.Int -> DateTime -> DateTime

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

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

Comparing DateTimes

compare : DateTime -> DateTime -> Basics.Order

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


type alias DateTimeDelta =
{ years : Basics.Int
, months : Basics.Int
, days : Basics.Int
, hours : Basics.Int
, minutes : Basics.Int
, seconds : Basics.Int
, milliseconds : Basics.Int 
}

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 : DateTime -> DateTime -> DateTimeDelta

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
--> }

Helper functions

isValidTime : Basics.Int -> Basics.Int -> Basics.Int -> Basics.Int -> Basics.Bool

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