| File calendar.icn |
###########################################################################
File: calendar.icn
Subject: Procedures for data and time calculation and conversion
Author: Robert J. Alexander
Date: June 23, 2000
###########################################################################
This file is in the public domain.
###########################################################################
Procedures in this file supercede several procedures in datetime.icn.
###########################################################################
Setting up
----------
You will probably want to set a platform environment variable
"Cal_TimeZone" to an appropriate local time zone ID string
before using this library. Look at the time zone data at the
end of this source file and choose an ID for your locale.
Common ones for USA are "PST", "MST", "CST", and "EST", although
there are more specific ones such as "America/Arizona" that
handle special rules. If environment variables are not supported
for your platform or your implementation of Icon, explicitly specify
the default time zone in your program: e.g.
Cal_CurrentTimeZone := Cal_GetTimeZone("PST").
If your system uses a base year for date calculation that is
different from 1970, your can specify it in an environment
variable "Cal_DateBaseYear" or set it directly in the global
variable by the same name. Unix and Windows use the library's
default value of 1970, but Macintosh used to use 1984 (I'm
not sure if Apple have yet seen fit to conform to
the 1970 quasi-standard). This setting doesn't matter unless you
want your "seconds" values to be the same as your system's.
GMT and local time
------------------
GMT (Greenwich Mean Time) is a universal time standard (virtually
equivalent to "Coordinated Universal Time" (UTC), except for some
millisecond differences).
Time forms
----------
There are two fundamental date/time forms supported by this
library: a form in which computation is easy (the "seconds" form)
and a form in which formatting is easy (the "calendar record"
form).
- Seconds -- the time is be represented as an integer that is
the number of seconds relative to the beginning of
Cal_DateBaseYear, GMT. Cal_DateBaseYear is
usually 1970, but can be changed). The "seconds" form is
a universal time, independent of locale.
- Cal_Rec -- a "calendar record", which has fields for date and
time components: year, month, day, hour, minutes, seconds,and
day-of-week.
The "Cal_Rec" form is usually in terms of local time, including
accounting for daylight savings time according to local rules.
Notes
-----
- Several procedures have a final "timeZone" parameter. In those
procedures the timeZone parameter is optional and, if omitted,
Cal_CurrentTimeZone is used.
- The time zone table and list consume around 30KB that can be
"freed" by setting both Cal_TimeZoneTable and Cal_TimeZoneList
to &null. Procedures Cal_GetTimeZoneTable() and
Cal_GetTimeZoneList() will re-create the structures and assign
them back to their globals. For many applications, those
structures are no longer needed after program initialization.
- The global variables are automatically initialized by
the Cal_ procedures. However, if you want to use the globals
before using any procedures, they must be explicitly initialized
by calling Cal_Init().
- Time zone records in the time zone structures should be viewed
as read-only. If you want to make temporary changes to the
fields, copy() the time zone record.
Global variables
----------------
The following global variables are useful in date and time
operations (R/O means please don't change it):
- Cal_SecPerMin - (R/O) Seconds per minute.
- Cal_SecPerHour - (R/O) Seconds per hour.
- Cal_SecPerDay - (R/O) Seconds per day.
- Cal_SecPerWeek - (R/O) Seconds per week.
- Cal_MonthNames - (R/O) List of month names.
- Cal_DayNames - (R/O) List of day names.
- Cal_CurrentTimeZone - Current default time zone record --
can be changed at any time. Initialized
to the time zone whose ID is in
environment variable "Cal_TimeZone" if
set, or to GMT.
- Cal_TimeZoneGMT - (R/O) The GMT time zone record. Can be used
as a timeZone parameter to "turn off"
conversion to or from local.
- Cal_DateBaseYear - The base year from which the "seconds"
form is calculated, initialized to
the value of environment variable
"Cal_DateBaseYear" if set, or 1970 (the
year used by both Unix and MS-Windows)
- Cal_TimeZoneTable - A table of time zones keyed by the
time zone's ID string
- Cal_TimeZoneList - A list of time zones ordered by
increasing offset from GMT
Initialization procedure
------------------------
Cal_Init()
Initializes global variables. Called implicitly by
the Cal_ procedures.
Cal_Rec (calendar record) procedures
------------------------------------
Cal_Rec(year,month,day,hour,min,sec,weekday) =20
Cal_Rec record constructor. All values are integers in
customary US usage (months are 1-12, weekdays are 1-7 with
1 -> Sunday)
Cal_SecToRec(seconds,timeZone)
Converts seconds to a Cal_Rec, applying conversion rules
of "timeZone". To suppress conversion, specify timeZone =
Cal_TimeZoneGMT.
Cal_RecToSec(calRec,timeZone)
Converts a Cal_Rec to seconds, applying conversion rules
of "timeZone". To suppress conversion, specify timeZone =
Cal_TimeZoneGMT.
Time zone procedures
--------------------
Cal_GetTimeZone(timeZoneName)
Gets a time zone given a time zone ID string. Fails if
a time zone for the given ID cannot be produced.
Cal_GetTimeZoneList()
Returns the tine zone list that is the value of
Cal_TimeZoneList, unless that global has been explicitly
set to &null. If the global is null, a new list is built,
assigned to Cal_TimeZoneList, and returned.
Cal_GetTimeZoneTable()
Returns the tine zone table that is the value of
Cal_TimeZoneTable, unless that global has been explicitly
set to &null. If the global is null, a new table is built,
assigned to Cal_TimeZoneTable, and returned. In building
the table, Cal_GetTimeZoneList() is called so global
variable Cal_TimeZoneList is also set.
Date/time calculation procedures
--------------------------------
Cal_LocalToGMTSec(seconds,timeZone)
Converts seconds from local to GMT using the rules of
timeZone.
Cal_GMTToLocalSec(seconds,timeZone)
Converts seconds from GMT to local using the rules of
timeZone.
Cal_IsLeapYear(year)
Returns the number of seconds in a day if year is a leap
year, otherwise fails.
Cal_LeapYearsBetween(loYear,hiYear)
Returns the count of leap years in the range of years n
where loYear <= n < hiYear.
Cal_IsDST(seconds,timeZone)
Returns the DST offset in hours if seconds (local time)
is in the DST period, otherwise fails.
Cal_NthWeekdayToSec(year,month,weekday,n,fromDay)
Returns seconds of nth specified weekday of month, or fails
if no such day. This is mainly an internal procedure for
DST calculations, but might have other application.
Date/time formatting procedures
-------------------------------
Cal_DateLineToSec(dateline,timeZone)
Converts a date in something like Icon's &dateline format
(Wednesday, February 11, 1998 12:00 am) to "seconds" form.
Cal_DateToSec(date,timeZone)
Converts a date string in something like Icon &date format
(1998/02/11) to "seconds" form.
Cal_SecToDate(seconds,timeZone)
Converts "seconds" form to a string in Icon's
&date format (1998/02/11).
Cal_SecToDateLine(seconds,timeZone)
Converts "seconds" form to a string in Icon's &dateline
format (Wednesday, February 11, 1998 12:00 am).
Cal_SecToUnixDate(seconds,timeZone)
Converts "seconds" form to a string in typical UNIX
date/time format (Jan 14 10:24 1991).
Time-only formatting procedures
-------------------------------
Cal_ClockToSec(seconds)
Converts a time in the format of &clock (19:34:56) to
seconds past midnight.
Cal_SecToClock(seconds)
Converts seconds past midnight to a string in the format of
&clock (19:34:56).
###########################################################################
See also: datetime.icn, datefns.icn
###########################################################################
This file is part of the (main) package.
Source code.| Details |
| Procedures: |
Internal procedure to help process DST rules.
Converts a time in the format of &clock to seconds past midnight. : convert &date to seconds
Cal_DSTDayOfMonthToSec(year, month, mode, day, dayOfWeek)
Internal procedure to calculate seconds at the start of the day specified for DST start or end.
Cal_DateLineToSec(dateline, timeZone)
Converts a date in long form to seconds since start of DateBaseYear. : convert &dateline to seconds
Converts a date in Icon &date format (yyyy/mm/dd) do seconds past DateBaseYear. : convert &date to seconds
Cal_GMTToLocalSec(seconds, timeZone)
Gets the time zone record with ID "timeZoneName".
Builds a list of time zones ordered by increasing offset from GMT.
Builds a table of time zones with keys the time zone names and values the time zone records (Cal_TimeZoneRec).
Initialize the date globals -- although done automatically by many calls to date procedures, it's not a bad idea to call this explicitly before using. : initialize calendar globals
If "seconds" represents a time in the DST period for the specified time zone, returns the number of hours by which to adjust standard time to daylight savings time, otherwise fails. "seconds" are local, but not adjusted for DST. : determines if seconds (local) is DST
Fails unless year is a leap year. : determine if year is leap
Cal_LeapYearsBetween(loYear, hiYear)
Counts leap years in the range [loYear,hiYear).
Cal_LocalToGMTSec(seconds, timeZone)
Time zone data, ordered by increasing hoursFromGMT
Cal_NthWeekdayToSec(year, month, weekday, n, fromDay)
Calculates number of seconds on the "n"th "weekday" of "month" of "year"
following or preceding "fromDay" (e.g. the 3rd Wednesday of April 1998
on or following the 5th).
If n is negative, n is counted from the end of the month. Fails if
the day does not exist (i.e., n is out of range for that month).
The "time window" in which the day counting takes place, in the
absense of a "fromDay", is the entire month specified. By providing a
nonnull "fromDay", the window can be restricted to days including and
following "fromDay" (if it is positive), or preceding (and not including,
if it is negative).
Examples:
For first Sunday in April on or after the 5th:
NthWeekdayToSec(1998,4,1,1,5)
For last Sunday in October, 1998:
NthWeekdayToSec(1998,10,1,-1)
: gets seconds of nth specified weekday of month
Cal_RecToSec(calRec, timeZone)
Converts a Cal_Rec to seconds since start of DateBaseYear.
Converts seconds past midnight to a string in the format of &clock. : convert seconds to &clock
Cal_SecToDate(seconds, timeZone)
Converts seconds past DateBaseYear to a &date in Icon date format (yyyy,mm,dd). : convert seconds to &date
Cal_SecToDateLine(seconds, timeZone)
Produces a date in the same format as Icon's &dateline. : convert seconds to &dateline
Cal_SecToRec(seconds, timeZone)
Produces a date record computed from the seconds since the start of DateBaseYear.
Cal_SecToUnixDate(seconds, timeZone)
Returns a date and time in UNIX format: Jan 14 10:24 1991 : convert seconds to UNIX time
| Records: |
Cal_Rec(year, month, day, hour, min, sec, weekday)
Cal_TimeZoneRec(id, hoursFromGMT, data)
| Global variables: |