datetime.icn

File datetime.icn

Summary

###########################################################################

	File:     datetime.icn

	Subject:  Procedures for date and time operations

	Author:   Robert J. Alexander and Ralph E. Griswold

	Date:     November 6, 1998

###########################################################################

   This file is in the public domain.

###########################################################################

	Notes:
		- the default value for function parameters named
		  "hoursFromGmt" is the value of global variable
		  "HoursFromGmt" if nonnull, or environment variable
		  "HoursFromGmt" if set, or 0.
		- The base year from which the "seconds" representation
		  of a date is calculated is by default 1970 (the ad hoc
		  standard used by both Unix and MS-Windows), but can be
		  changed by either setting the global variable
		  "DateBaseYear" or environment variable "DateBaseYear".
		- There are some procedures not mentioned in this summary
		  that are useful: DateRecToSec(), SecToDateRec(). See the
		  source code for details.

	ClockToSec(seconds)
		converts a time in the format of &clock to seconds past
		midnight.

	DateLineToSec(dateline,hoursFromGmt)
		converts a date in &dateline format to seconds since start of
		dateBaseYear.

	DateToSec(date,hoursFromGmt)
		converts a date string in Icon &date format (yyyy/mm/dd)
		to seconds past DateBaseYear.

	SecToClock(seconds)
		converts seconds past midnight to a string in the format of
		&clock.

	SecToDate(seconds,hoursFromGmt)
		converts seconds past DateBaseYear to a string in Icon
		&date format (yyyy/mm/dd).

	SecToDateLine(seconds,hoursFromGmt)
		produces a date in the same format as Icon's &dateline.

	SecToUnixDate(seconds,hoursFromGmt)
		returns a date and time in typical UNIX format:
		Jan 14 10:24 1991.

	IsLeapYear(year)
		succeeds if year is a leap year, otherwise fails.

	calendat(j)
		returns a record with the month, day, and year corresponding
		to the Julian Date Number j.

	date()	natural date in English.

	dayoweek(day, month, year)
		produces the day of the week for the given date

	full13th(year1, year2)
		generates records giving the days on which a full moon occurs
		on Friday the 13th in the range from year1 though year2.

	julian(m, d, y)
		returns the Julian Day Number for the specified
		month, day, and year.

	pom(n, phase)
		returns record with the Julian Day number of fractional
		part of the day for which the nth such phase since
		January, 1900.  Phases are encoded as:

			0 - new moon
			1 - first quarter
			2 - full moon
			3 - last quarter#

		GMT is assumed.

	saytime()
		computes the time in natural English.  If an argument is
		supplied it is used as a test value to check the operation
		 the program.

	walltime()
		produces the number of seconds since midnight.  Beware
		wrap-around when used in programs that span midnight.

###########################################################################

  See also:  datefns.icn

###########################################################################

  Acknowledgement:  Some of these procedures are based on an algorithm
  given in "Numerical Recipes; The Art of Scientific Computing";
  William H. Press, Brian P. Flannery, Saul A. Teukolsky, and William
  T. Vetterling;#  Cambridge University Press, 1986.

###########################################################################

Procedures: