PanagiotisGeorgiadis / elm-datetime / Clock

The Clock module was introduced in order to keep track of the Time concept. It has no notion of a Date or any of its parts and it represents Time as a 24-hour clock which consists of Hours, Minutes, Seconds and Milliseconds. You can construct a Time either by providing a Posix time or by using its Raw constituent parts. You can use a Time and the Clock's utilities as a standalone or you can combine a Time and a Date in order to get a DateTime which can then be converted into a Posix.

Type definition


type alias Time =
Internal.Time

A clock time.


type alias RawTime =
{ hours : Basics.Int
, minutes : Basics.Int
, seconds : Basics.Int
, milliseconds : Basics.Int 
}

An 'abstract' representation of Time and its constituent parts based on Integers.

Creating a Time

fromPosix : Time.Posix -> Time

Construct a Time from a Posix time. You can construct a Posix time from milliseconds using the millisToPosix function located in the elm/time package.

fromPosix (Time.millisToPosix 0)
-- Time { hours = Hour 0, minutes = Minute 0, seconds = Second 0, milliseconds = Millisecond 0 } : Time

fromPosix (Time.millisToPosix 1566795954000)
-- Time { hours = Hour 5, minutes = Minute 5, seconds = Second 54, milliseconds = Millisecond 0 } : Time

fromPosix (Time.millisToPosix 1566777600000)
-- Time { hours = Hour 0, minutes = Minute 0, seconds = Second 0, milliseconds = Millisecond 0 } : Time

Notice that in the first and third examples the timestamps that are used are different but the result Times are identical. This is because the Clock module only extracts the Hours, Minutes, Seconds and Milliseconds from the given Posix time given. This means that if we attempt to convert both of these Times back toMillis they will result in the same milliseconds. It is recommended using the fromPosix function provided in the DateTime module if you need to preserve both Date and Time.

fromRawParts : RawTime -> Maybe Time

Construct a clock Time from raw Hour, Minute, Second, Millisecond integers.

fromRawParts { hours = 23, minutes = 15, seconds = 45, milliseconds = 999 }
-- Just (Time { hours = Hour 23, minutes = Minute 15, seconds = Second 45, milliseconds = Millisecond 999 }) : Maybe Time

fromRawParts { hours = 24, minutes = 15, seconds = 45, milliseconds = 999 }
-- Nothing : Maybe Time

Notice that the second attempt to construct a time resulted in Nothing. This is because the upper limit for an Hour is 23.

The limits are as follows:

Conversions

toMillis : Time -> Basics.Int

Convert a Time to milliseconds since midnight.

time = fromRawParts { hours = 12, minutes = 30, seconds = 0, milliseconds = 0 }
Maybe.map toMillis time -- Just 45000000 : Maybe Int

want = 1566777600000 -- 26 Aug 2019 00:00:00.000
got = toMillis (fromPosix (Time.millisToPosix want)) -- 0 : Int

want == got -- False

Accessors

getHours : Time -> Basics.Int

Extract the Hours part of a Time.

-- time == 12:15:45.500
getHours time -- 12 : Int

getMinutes : Time -> Basics.Int

Extract the Minutes part of a Time.

-- time == 12:15:45.500
getMinutes time -- 15 : Int

getSeconds : Time -> Basics.Int

Extract the Seconds part of a Time.

-- time == 12:15:45.500
getSeconds time -- 45 : Int

getMilliseconds : Time -> Basics.Int

Extract the Millisecond part of a Time.

-- time == 12:15:45.500
getMilliseconds time -- 500 : Int

Setters

setHours : Basics.Int -> Time -> Maybe Time

Attempts to set the Hour on an existing time.

-- time == 15:45:54.250
setHours 23 time -- Just (23:45:54.250) : Maybe Time

setHours 24 time -- Nothing : Maybe Time

setMinutes : Basics.Int -> Time -> Maybe Time

Attempts to set the Minute on an existing time.

-- time == 15:45:54.250
setMinutes 36 time -- Just (15:36:54.250) : Maybe Time

setMinutes 60 time -- Nothing : Maybe Time

setSeconds : Basics.Int -> Time -> Maybe Time

Attempts to set the Second on an existing time.

-- time == 15:45:54.250
setSeconds 20 time -- Just (15:45:20.250) : Maybe Time

setSeconds 60 time -- Nothing : Maybe Time

setMilliseconds : Basics.Int -> Time -> Maybe Time

Attempts to set the Millisecond on an existing time.

-- time == 15:45:54.250
setMilliseconds 589 time -- Just (15:45:54.589) : Maybe Time

setMilliseconds 1000 time -- Nothing : Maybe Time

Increment values

incrementHours : Time -> ( Time, Basics.Bool )

Increments an Hour inside a Time. The Time will keep on cycling forward with a maximum time of 23:59:59.999. It also returns a Bool flag which indicates if the new Time has passed through the midnight hour ( 00:00:00.000 ). This flag can be used in order to notify that a Day has passed but it is advised to use the DateTime module for these kind of operations since it provides all the available helpers and takes care of any Calendar changes.

-- time == 12:15:45.750 incrementHours time -- (13:15:45.750, False) : (Time, Bool)

-- time2 == 23:00:00.000 incrementHours time2 -- (00:00:00.000, True) : (Time, Bool)

incrementMinutes : Time -> ( Time, Basics.Bool )

Increments a Minute inside a Time. The Time will keep on cycling around as mentioned in the incrementHours description.

-- time == 12:59:45.750 incrementMinutes time -- (13:00:45.750, False) : (Time, Bool)

-- time2 == 23:59:45.750 incrementMinutes time2 -- (00:00:45.750, True) : (Time, Bool)

incrementSeconds : Time -> ( Time, Basics.Bool )

Increments a Second inside a Time. The Time will keep on cycling around as mentioned in the incrementHours description.

-- time == 12:59:59.750 incrementSeconds time -- (13:00:00.750, False) : (Time, Bool)

-- time2 == 23:59:59.750 incrementSeconds time2 -- (00:00:00.750, True) : (Time, Bool)

incrementMilliseconds : Time -> ( Time, Basics.Bool )

Increments a Millisecond inside a Time. The Time will keep on cycling around as mentioned in the incrementHours description.

-- time == 12:59:59.999 incrementMilliseconds time -- (13:00:00.000, False) : (Time, Bool)

-- time2 == 23:59:59.999 incrementMilliseconds time2 -- (00:00:00.000, True) : (Time, Bool)

Decrement values

decrementHours : Time -> ( Time, Basics.Bool )

Decrements an Hour inside a Time. The Time will keep on cycling backwards with a minimum time of 00:00:00.000. It also returns a Bool flag which indicates if the new Time has passed through the midnight hour ( 00:00:00.000 ). This flag can be used in order to notify that a Day has passed but it is advised to use the DateTime module for these kind of operations since it provides all the available helpers and takes care of any Calendar changes.

-- time  == 13:15:45.750
decrementHours time -- (12:15:45.750, False) : (Time, Bool)

-- time2 == 00:59:59.999
decrementHours time2 -- (23:59:59.999, True) : (Time, Bool)

decrementMinutes : Time -> ( Time, Basics.Bool )

Decrements a Minute inside a Time. The Time will keep on cycling backwards as mentioned in the decrementHours description.

-- time  == 12:15:00.000
decrementMinutes time -- (12:14:00.000, False) : (Time, Bool)

-- time2 == 00:00:00.000
decrementMinutes time2 -- (23:59:00.000, True) : (Time, Bool)

decrementSeconds : Time -> ( Time, Basics.Bool )

Decrements a Second inside a Time. The Time will keep on cycling backwards as mentioned in the decrementHours description.

-- time  == 12:15:00.000
decrementSeconds time -- (12:14:59.000, False) : (Time, Bool)

-- time2 == 00:00:00.000
decrementSeconds time2 -- (23:59:59.000, True) : (Time, Bool)

decrementMilliseconds : Time -> ( Time, Basics.Bool )

Decrements a Millisecond inside a Time. The Time will keep on cycling backwards as mentioned in the decrementHours description.

-- time  == 12:15:00.000
decrementMilliseconds time -- (12:14:59.999, False) : (Time, Bool)

-- time2 == 00:00:00.000
decrementMilliseconds time2 -- (23:59:59.999, True) : (Time, Bool)

Compare values

compare : Time -> Time -> Basics.Order

Compare two Time values.

-- past   == 15:45:24.780
-- future == 15:45:24.800
compare past past -- EQ : Order

compare past future -- LT : Order

compare future past -- GT : Order

Utilities

sort : List Time -> List Time

Sorts a List of 'Time' based on their representation in milliseconds.

-- dawn     == 06:00:00.000
-- noon     == 12:00:00.000
-- dusk     == 18:00:00.000
-- midnight == 00:00:00.000

sort [ noon, dawn, dusk, midnight ]
-- [ 00:00:00.000, 06:00:00.000, 12:00:00.000, 18:00:00.000 ] : List Time

Constants

midnight : Time

Returns midnight time.

midnight == 00:00:00.000