A valid and unambiguous point in time in some time zone.

The local time of this TZTime.

The time zone of this TZTime.

The offset observed in this time zone at this moment in time.

Returns the current time with the local time zone information based on the TZ and TZDIR environment variables.

See tzset(3) for details, but basically:

• If TZ environment variable is unset, we use /etc/localtime.
• If TZ is set, but empty, we use utc.
• If TZ is set and not empty, we use loadFromSystem to read that file.

Converts a UTCTime to the given time zone.

Converts a POSIXTime to the given time zone.

Converts a ZonedTime to UTC and then to the given time zone.

Constructs a TZTime from a local time in the given time zone.

• If the local time lands on a "gap" (e.g. when the clocks are set forward in spring and a local time is skipped), we shift the time forward by the duration of the gap.
• If it lands on an "overlap" (e.g. when the clocks are set back in autumn and a local time happens twice), we use the earliest offset.

Similar to fromLocalTime, but returns a TZError if the local time is ambiguous/invalid.

Similar to fromLocalTime, but throws a TZError in MonadThrow if the local time is ambiguous/invalid.

Similar to fromLocalTime, but throws an error if the local time is ambiguous/invalid.

Attempted to construct a TZTime from an invalid or ambiguous LocalTime.

Converts this moment in time to the universal time-line.

Converts this moment in time to a POSIX timestamp.

Converts this moment in time to a ZonedTime (discarding time zone rules).

Converts this moment in time to some other time zone.

If this local time happens to be on an overlap, switch to the earliest of the two offsets.

>>> atEarliestOffset [tz|2022-11-06 01:30:00 -06:00 [America/Winnipeg]|]
2022-11-06 01:30:00 -05:00 [America/Winnipeg]

If this local time happens to be on an overlap, switch to the latest of the two offsets.

>>> atLatestOffset [tz|2022-11-06 01:30:00 -05:00 [America/Winnipeg]|]
2022-11-06 01:30:00 -06:00 [America/Winnipeg]

Changes the time to the earliest time possible on that day.

This is usually 00:00, but, if, on that day:

• the clocks are turned, for example, from 23:59 to 01:00 and midnight is skipped, this will return 01:00.
• the clocks are turned, for example, from 01:00 to 00:00 and midnight happens twice, this will return the first occurrence (i.e. midnight at the earliest offset).

Adds the given amount of seconds

>>> [tz|2022-03-04 10:15:00 [Europe/Rome]|] & addTime (hours 2 + minutes 20)
2022-03-04 12:35:00 +01:00 [Europe/Rome]

A standard hour of 3600 seconds.

A standard minute of 60 seconds.

Modifies the date/time on the local time-line.

The result may:

• Land on a "gap", e.g. when the clocks are set forward in spring and a local time is skipped. When this happens, we shift the time forward by the duration of the gap.

  For example, on the 13th, the clocks skip one hour, from 01:59 (at the -06:00 offset) straight to 03:00 (at the -05:00 offset):

  >>> [tz|2022-03-12 02:15:00 -06:00 [America/Winnipeg]|] & modifyLocal (addCalendarClip (calendarDays 1))
  2022-03-13 03:15:00 -05:00 [America/Winnipeg]
  

• Land on an "overlap", e.g. when the clocks are set back in autumn and a local time happens twice. When this happens, we attempt to preserve the offset of the original TZTime. This ensures that modifyLocal id == id. If this is not possible, use the earliest of the two offsets.

  For example, on the 6th, the clocks are set back one hour, from 01:59 (at the -05:00 offset) back to 01:00 (at the -06:00 offset). This means the time 01:15 happens twice, first at -05:00 and then again at -06:00.

  >>> [tz|2022-11-05 01:15:00 -05:00 [America/Winnipeg]|] & modifyLocal (addCalendarClip (calendarDays 1))
  2022-11-06 01:15:00 -05:00 [America/Winnipeg]
  

  >>> [tz|2022-11-07 01:15:00 -06:00 [America/Winnipeg]|] & modifyLocal (addCalendarClip (calendarDays -1))
  2022-11-06 01:15:00 -06:00 [America/Winnipeg]
  

This behaviour should be suitable for most use cases.

Note: modifyLocal (g . f) may not always be equivalent to modifyLocal g . modifyLocal f.

If modifyLocal f lands on a gap or an overlap, the time will be corrected as described above; but there's a chance modifyLocal (g . f) would skip right over the gap/overlap and no correction is needed. As a rule of thumb, apply all modifications to the local time-line in one go.

>>> import Control.Arrow ((>>>))
>>> :{
[tz|2022-03-04 10:15:00 +01:00 [Europe/Rome]|]
  & modifyLocal (
      addCalendarClip (calendarMonths 2 <> calendarDays 3) >>>
      atFirstDayOfWeekOnAfter Wednesday >>>
      atMidnight
    )
:}
2022-05-11 00:00:00 +02:00 [Europe/Rome]

Similar to modifyLocal, but returns a TZError if the result lands in a gap/overlap.

Similar to modifyLocal, but throws a TZError in MonadThrow if the result lands in a gap/overlap.

Add the given number of months first and then the given number of days, using the proleptic Gregorian calendar.

When adding months, days past the last day of the month are clipped to the last day. For instance, 2005-01-30 + 1 month = 2005-02-28.

Add the given number of months first and then the given number of days. using the proleptic Gregorian calendar.

When adding months, days past the last day of the month roll over to the next month. For instance, 2005-01-30 + 1 month = 2005-03-02.

Sets the year using the proleptic Gregorian calendar.

Sets the month using the proleptic Gregorian calendar. Invalid values will be clipped to the correct range.

Sets the day of month using the proleptic Gregorian calendar. Invalid values will be clipped to the correct range.

Sets the day.

Sets the time to 00:00.

Moves the date to the next given DayOfWeek. If the current date is already a match, then the current date is returned unmodified.

>>> tzt = [tz|2022-02-24 10:00:00 [Europe/London]|]
>>> tzt & modifyLocal (atFirstDayOfWeekOnAfter Thursday)
2022-02-24 10:00:00 +00:00 [Europe/London]
>>> tzt & modifyLocal (atFirstDayOfWeekOnAfter Wednesday)
2022-03-02 10:00:00 +00:00 [Europe/London]

Calculate the difference in seconds between two points in time.