This module defines a time representation based on a Date and the time of day.
DateTime is the opaque type for all DateTime values. Values of this type represent a valid Date and a time offset from midnight.
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
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
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
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
{ 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
--> }
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