A Date.T
is a moment in time, expressed according to the standard
(Gregorian) calendar, as observed in some time zone. A
Date.TimeZone
(or just a time zone) is an object that encapsulates
the rules for converting from UTC (universal coordinated time,
sometimes known as Greenwich mean time) to local time within a
particular jurisdiction, taking into account daylight time when
appropriate.
\index{calendar date}
\index{local time}
\index{time!local}
\index{time zone}
\index{time!zone}
\index{universal coordinated time}
\index{time!UTC (universal coordinated time)}
\index{Greenwich mean time}
\index{time!Greenwich mean time}
\index{time!Date interface@{\tt Date} interface}
INTERFACEA date'sDate ; IMPORT Time; TYPE T = RECORD year: CARDINAL; (* e.g., 1992 *) month: Month; day: [1 .. 31]; hour: [0 .. 23]; minute: [0 .. 59]; second: [0 .. 60]; offset: INTEGER; zone: TEXT; weekDay: WeekDay END; Month = {Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec}; WeekDay = {Sun, Mon, Tue, Wed, Thu, Fri, Sat};
offset
field specifies the difference in the readings of
two clocks, one set to UTC and one set to local time, at the moment
the date occurred, and thus reflects daylight time when
appropriate. This difference is specified in seconds, with
positive values corresponding to local zones behind (west of) UTC.
A date's zone
field specifies a name (often a three-letter
abbreviation) for the time zone in which the date is observed, for
example, ``PDT'' for Pacific Daylight Time.
TYPE TimeZone <: REFANY; VAR Local, UTC: TimeZone;
Local
is initialized to the time zone in which the computer running this program is located.UTC
is initialized to the time zone for universal coordinated time.
PROCEDURE FromTime(t: Time.T; z: TimeZone := NIL): T;
Return the date corresponding tot
, as observed in the time zonez
. Ifz
isNIL
,Local
is used.
EXCEPTION Error; PROCEDURE ToTime(READONLY d: T): Time.T RAISES {Error};
Return the time corresponding to the dated
, using the fieldoffset
rather thanzone
and ignoring the fieldweekDay
. RaiseError
ifd
cannot be represented as aTime.T
.
END Date.On POSIX systems,
FromTime(t, Local)
calls localtime(3)
. On
Win32 systems, it calls GetTimeZoneInformation
. Some systems
keep local time instead of UTC, and typically don't record the
identity of the local time zone. On such a system, FromTime(t,
Local)
always returns a result with offset
equal to zero and
zone
equal to {\tt "[Unknown zone]"}, and UTC
is
NIL
.