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.
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.
{ 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
DurationDeltaRecord
excludes week fieldDurationDeltaRecord
includes month fieldDurationDeltaRecord
includes year fieldDurationDeltaRecord
to a date.
The larger granularity fields are added before lower granularity fields
so Years are added before Months before Days etc.DurationDeltaRecord
will be positive or zero.DurationDeltaRecord
will be negative or zero.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.