Editing Time (section)

= Data Types for Denoting Time =

So far our data have denoted occurrences of events by counting the number of days, or the number of seconds since some fixed reference epoch.  However, we usually tell time by using years, months, day of month, hours, minutes and seconds.  The following data types will assist with this more usual approach to telling time.

== Day ==

The <tt>Day</tt> data type is an abstract way of referring to a calendar date.  Due to time zone issues, the <tt>Day</tt> type does not necessarily refer to any specific 1-day long absolute time period.

The standard calender used to reference a date is the Gregorian calendar.  The <tt>toGregorian</tt> and <tt>fromGregorian</tt> functions will construct and deconstruct a <tt>Day</tt> from the usual year-month-day format.  There are other calendars, such as the Julian calendar, which are only used in unusual situations.

== TimeOfDay ==

<tt>TimeOfDay</tt> represents "wall-clock" time.  It consists of an hour of the day, a minute of the hour, and a second of the minute, including fractions of a second up to a resolution of 10^12.  The seconds could go up to 61 in order to accommodate leap seconds.

== LocalTime ==

A <tt>Day</tt> with a <tt>TimeOfDay</tt> forms a <tt>LocalTime</tt>.  This is contains the data that we normally denote time with: a year, month, day, hour, minute, and second.  However, it does not denote an absolute time because it contains no time zone information.

<tt>LocalTime</tt> is used represent date and time for printing and parsing; however it should be avoided for computation.  The biggest problem with <tt>LocalTime</tt> is that, due to daylight savings time, regularly the same time of day is repeated twice a day.  This means you cannot even use <tt>LocalTime</tt>s to reliably determine the relative order of events.

== TimeZone ==

Somewhat confusingly named, a <tt>TimeZone</tt> represents an offset from UTC measured in minutes.  It also contains ancillary data such as the timezone name and whether or not it is intended to be used for summer time only.  Eastern Standard Time (EST) or Pacific Daylight Time (PDT) are examples of timezone that could be represented by a <tt>TimeZone</tt> value. 

It does not represent the time zone of a region, such as Eastern Time, because regions often vary their offsets from UTC depending on the time of year.

The <tt>utc</tt> value is the value of the <tt>TimeZone</tt> with no offset from UTC.

== ZonedTime == 

A <tt>ZonedTime</tt> is a <tt>LocalTime</tt> together with a <tt>TimeZone</tt>.  This does refer to a specific event in absolute time and can be converted to a <tt>UTCTime</tt> with the <tt>zoneTimeToUTC</tt> function, and could be further converted into a <tt>AbsoluteTime</tt> if one has a leap second table.

There are, of course, many different <tt>ZonedTime</tt> values corresponding to the same absolute, <tt>UTCTime</tt>.  Given a <tt>TimeZone</tt> one can create a <tt>ZonedTime</tt> with that <tt>TimeZone</tt> by using the <tt>utcToZonedTime</tt> function.

<tt>ZonedTime</tt> is a common stop when converting between common year-month-day-hour-minute-second human time format and absolute <tt>UTCTime</tt> time.

== TimeZoneSeries ==

Almost nothing in the time library deals with regional time zones such as "Eastern Time" or "Pacific time".  For that we need to reach out to the timezone-series and timezone-olson packages.  The difficulty with regional time zones is, like leap seconds, that they are unpredictable and subject to be changed.  

A <tt>TimeZoneSeries</tt> is a series of <tt>TimeZone</tt>s, that is offsets from UTC, along with the absolute times where those <tt>TimeZone</tt>s are in effect.  This is a suitable structure for defining a regional time zone.  The functions in the timezone-olson package will allow you to create a <tt>TimeZoneSeries</tt> from an Olson time zone database file.

== getTimeZone ==

There is one set of functions in the time package that does deal with regional time zones.  The <tt>getTimeZone</tt> function will compute the timezone for a given <tt>UTCTime</tt>, but only the local region as set by the <tt>TZ</tt> environment variable.  The <tt>getCurrentTimeZone</tt>, <tt>getZonedTime</tt>, and <tt>utcToLocalZonedTime</tt> are functions derived from <tt>getTimeZone</tt>.

There is no functionality in the time package that will convert from a local regional time to <tt>UTCTime</tt>, owing to the fact that the same local regional time may refer to multiple different <tt>UTCTime</tt> due to daylight savings times.  <tt>localTimeToUTC'</tt> from the <tt>timezone-series</tt> packages will do this conversion given a <tt>TimeZoneSeries</tt>.