adius / vectual / TimeUtils.Duration

A Duration is a length of time that may vary with calendar date and time. It can be used to modify a date.

Represents a period of time expressed in human chronological terms in terms of a calendar which may have varying components based upon the dates involved in the math.

When modify dates using Durations (Day | Month | Week | Year) this module compensates for day light saving hour variations to minimize the scenarios that cause the Hour field in the result to be different to the input date. It can't completely avoid the hour changing as some hours are not a real world date and hence will modify the hour more than the Duration modified.

This behavior is modeled on moment.js so any observed behavior that is not the same as moment.js should be raised as an issue.

Note adding or subtracting 24 * Hour units from a date may produce a different answer to adding or subtracting a Day if day light saving transitions occur as part of the date change.

Warning

Be careful if you add Duration Delta to a Date as Duration contains months and Years which are not fixed elapsed times like Period Delta , however if you really need a relative number of months or years then it may meet your needs.

add : Duration -> Basics.Int -> Time.Posix -> Time.Posix

Add duration count to date.


type Duration
    = Millisecond
    | Second
    | Minute
    | Hour
    | Day
    | Week
    | Month
    | Year
    | Delta DurationDeltaRecord

A Duration is time period that may vary with with calendar and time.

Using Duration adding 24 hours can produce different result to adding 1 day.


type alias DurationDeltaRecord =
{ year : Basics.Int
, month : Basics.Int
, day : Basics.Int
, hour : Basics.Int
, minute : Basics.Int
, second : Basics.Int
, millisecond : Basics.Int 
}

A multi granularity duration delta. This does not contain week like Period.DeltaRecord. It does contain month and year.

durationToString : Duration -> String

Convert a Duration to a String. Especially helpful printing debugging information.

zeroDelta : DurationDeltaRecord

All zero delta. Useful as a starting point if you want to set a few fields only.

diff : Time.Posix -> Time.Posix -> DurationDeltaRecord

Return a Period representing date difference date1 - date2. If you add the result of this function to date2 with addend of 1 will not always return date1, this is because this module supports human calendar concepts like Day Light Saving, Months with varying number of days dependent on the month and leap years. So the difference between two dates is dependent on when those dates are. Differences to Period.diff

diffDays : Time.Posix -> Time.Posix -> Basics.Int

Returns date1 - date2 as number of days to add to date1 to get to day date2 is on. date1 - date2 in days. Only calculates days difference and ignores any field smaller than day in calculation.

addMonth : Basics.Int -> Time.Posix -> Time.Posix

Return a date with month count added to date. New version leveraging daysFromCivil does not loop over months so faster and only compensates at outer level for DST. Expects input in local time zone. Return is in local time zone.

addYear : Basics.Int -> Time.Posix -> Time.Posix

Return a date with year count added to date.

deltaToString : DurationDeltaRecord -> String

Convert a DurationDeltaRecord to a String to easily display it during testing.

positiveDiff : Time.Posix -> Time.Posix -> Basics.Int -> DurationDeltaRecord

Return diff between dates. It returns date1 - date2 in a DurationDeltaRecord. Precondition for this function is date1 must be after date2. Input multiplier is used to multiply output fields as needed for caller, this is used to conditionally negate them in initial use case.

positiveDiffDays : Time.Posix -> Time.Posix -> Basics.Int -> Basics.Int

Return number of days added to date1 to produce date2

requireDaylightCompensateInAdd : Duration -> Basics.Bool

Return true if this Duration unit compensates for crossing daylight saving boundaries. TODO: This may need to compensate for day light saving for all fields as all of them can cause the date to change the zone offset.