Generated: Monday, November 14, 2011, 09:18:00 Copyright © 2011 , Kurt Nørmark The local LAML software home page

Reference Manual of the Time Library

Kurt Nørmark © normark@cs.aau.dk Department of Computer Science, Aalborg University, Denmark.

LAML Source file: lib/time.scm

This is the date and time library, on which many LAML facilities rely. Time is represented as an integer, which represents the number of seconds since January 1, 1970. This library contains functions which translate from seconds to year, month, day, hour, and second. Also the reverse translation is provided for. Besides this, the library provides functions for calculating the weekday and the week number. Weekday and month names can be returned in either Danish og English, depending on the variable language-preference. The language-preference binds at a late time, not loadning time. Be aware that you need to modify the variable time-zone-info when summer time (daylight saving time) is started and ended.

Table of Contents:
1. Time zone and Daylight Saving Time correction. 5. Week number and week day number. 9. Underlying time related constants and functions.
2. Basic time functions. 6. Time pretty printing. 10. Other time related functions.
3. Time selectors. 7. Time interval functions.
4. Week days. 8. Conventional string representation of time.

Alphabetic index:
brief-weekday (brief-weekday second-count) Given an integer, second-count, return the weekday as a brief string, of the time second-count.
danish-week-number (danish-week-number sc) Given a number sc, return the week number in which sc i located.
date-ok? (date-ok? x) Return whether x is a legal date string (of the form "ddmmyyyy").
date-string (date-string second-count) Return the date, in the format "ddmmyyyy" of second-count, which represents the time in seconds elapsed since January 1, 1970.
date-time (date-time second-count) Given an integer, second-cound, return a list of two strings: (date time).
date-time-one-string (date-time-one-string second-count) Return a single string that pretty prints the time represented by second count.
day-of-time (day-of-time decoded-time-list) Return the days of a decoded time list.
days-in-month (days-in-month month year) Return the number of days in month and year
emacs-lisp-time-to-second-count (emacs-lisp-time-to-second-count time-list) Given time-list, which is Emacs' representation of Universal time, return a single (large) integer that represents universal time.
get-month-name (get-month-name month-number) Return the month name of month-number.
hour-of-time (hour-of-time decoded-time-list) Return the hour of a decoded time list.
hours-minutes-decode-string (hours-minutes-decode-string hour-minute-string) Decode a string of the form "h:m" or "h.m" to a list of the form (h m).
hours-minutes-seconds-decode (hours-minutes-seconds-decode second-count) Return a list of (hours minutues seconds) given an integer second-count.
leap-year (leap-year y) Return whether y is a leap year.
minute-of-time (minute-of-time decoded-time-list) Return the minutes of a decoded time list.
month-of-time (month-of-time decoded-time-list) Return the month of a decoded time list.
present-time-interval (present-time-interval second-count) Return a string which presens the number of years, months, weeks, days, hours, minutes, and seconds of second-count
second-count (second-count y mo d h mi s) Given date and time in terms of year y, month mo, day d, hour h, minutes mi, and seconds s, caluculate the second count.
second-count-to-emacs-lisp-time (second-count-to-emacs-lisp-time second-count) Given a second count, which represents a point in time as a single large integer, return a list of three 16 bit numbers that corresponds to Emacs's representation.
second-of-time (seconds-of-time decoded-time-list) Return the seconds of a decoded time list.
seconds-in-a-day seconds-in-a-day The number of seconds in a day.
seconds-in-a-leap-year seconds-in-a-leap-year The number of seconds in a leap year.
seconds-in-a-normal-month seconds-in-a-normal-month The number of seconds in a 30-day month.
seconds-in-a-normal-year seconds-in-a-normal-year The number of seconds in a non-leap year.
seconds-in-a-week seconds-in-a-week The number of seconds in a week.
seconds-in-an-hour seconds-in-an-hour The number of seconds in an hour.
time-decode (time-decode n) Given an integer n, which is the number of second since january 1, 1970, return a list: (year month day minutes seconds).
time-encode (time-encode y mo d h mi s) An alias of second-count - encode year, month, day, hour, minutes, and seconds to an integer.
time-interval (time-interval second-count) Return the number of years, months, weeks, days, hours, minutes, and seconds from second-count.
time-ok? (time-ok? x) Return whether x is a legal time string (of the form "hhmm")
time-string (time-string second-count) Return the date, in the format "ddmmyyyy" of second-count, which represents the time in seconds elapsed since January 1, 1970.
time-zone-info time-zone-info Defines the time-zone.
transform-year-month-day-hour-minutes-strings (transform-year-month-day-hour-minutes-strings date time) Transform date and time strings to a second count (a large integer number of seconds elapsed since january 1, 1970).
weekday (weekday second-count) Given an integer, second-count, return the weekday of the time second-count.
weekday-number (weekday-number second-count) return the weekday-number of second-count (an integer).
when-generated (when-generated) Return a string that describes the current time as generation time.
year-month-day-decode-string (year-month-day-decode-string year-month-day-string) Decode a string of the form "y-m-d" to a list of the form (y m d).
year-of-time (year-of-time decoded-time-list) Return the year of a decoded time list.


1 Time zone and Daylight Saving Time correction.

time-zone-info
Form time-zone-info
Description Defines the time-zone. We also use this variable to adjust for daylight saving time. This is, however, kind of a hack. How many hours in front relative to Greenwich, England. The US east coast: 5. California 8. Denmark -1. If the encoded time is already corrected on your system, time-zone-info must be 0.
See also Scheme source file time-zone-info


2 Basic time functions.
According to the conventions used in LAML, the function current-time is assumed to return the current time, represented as the number of seconds elapsed since January 1, 1970, 00:00:00. In this section there are functions that encode and decode a number of seconds to and from a conventional time representation (in terms of year, month, day, hour, minutes, second).

time-decode
Form (time-decode n)
Description Given an integer n, which is the number of second since january 1, 1970, return a list: (year month day minutes seconds). The opposite function is called second-count
Examples (time-decode 1141249251) => (2006 3 1 21 40 51)
(time-decode 0) => (1970 1 1 0 0 0)
(time-decode tm0) => (2006 3 1 0 0 0)
(time-decode tmn) => (2006 3 1 23 59 59)
(time-decode (emacs-lisp-time-to-second-count (list 17414 9407 300383))) => (2006 3 1 22 48 31)
See also Scheme source file time-decode

second-count
Form (second-count y mo d h mi s)
Description Given date and time in terms of year y, month mo, day d, hour h, minutes mi, and seconds s, caluculate the second count. The second-count function compensates for time zone. The opposite function is called date-time.
Examples (= (second-count 2006 3 1 0 0 0) tm0) => #t
(= (- (second-count 2006 3 2 0 0 0) 1) tmn) => #t
See also Scheme source file second-count

time-encode
Form (time-encode y mo d h mi s)
Description An alias of second-count - encode year, month, day, hour, minutes, and seconds to an integer.
Examples (weekday (time-encode 2006 3 1 0 0 0)) => "Wednesday"
See also Scheme source file time-encode


3 Time selectors.
The selectors in this section work on decoded time lists. It means that the selectors just return a given element from the decoded list representation of time.

year-of-time
Form (year-of-time decoded-time-list)
Description Return the year of a decoded time list. An integer greater or equal to 1970.
Examples (year-of-time (list 2006 3 1 23 59 58)) => 2006
See also Scheme source file year-of-time

month-of-time
Form (month-of-time decoded-time-list)
Description Return the month of a decoded time list. An integer in the interval 1..12
Examples (month-of-time (list 2006 3 1 23 59 58)) => 3
See also Scheme source file month-of-time

day-of-time
Form (day-of-time decoded-time-list)
Description Return the days of a decoded time list. An integer in the interval 1..31
Examples (day-of-time (list 2006 3 1 23 59 58)) => 1
See also Scheme source file day-of-time

hour-of-time
Form (hour-of-time decoded-time-list)
Description Return the hour of a decoded time list. An integer in the interval 0..23
Examples (hour-of-time (list 2006 3 1 23 59 58)) => 23
See also Scheme source file hour-of-time

minute-of-time
Form (minute-of-time decoded-time-list)
Description Return the minutes of a decoded time list. An integer in the interval 0..59.
Examples (minute-of-time (list 2006 3 1 23 59 58)) => 59
See also Scheme source file minute-of-time

second-of-time
Form (seconds-of-time decoded-time-list)
Description Return the seconds of a decoded time list. An integer in the interval 0..59.
Examples (second-of-time (list 2006 3 1 23 59 58)) => 58
See also Scheme source file second-of-time


4 Week days.
The functions in this section deal with week days. Both English and Danish week day names are supported via use of the variable language-preference in laml-fundamental.scm.

weekday
Form (weekday second-count)
Description Given an integer, second-count, return the weekday of the time second-count. Returns a string.
Examples (weekday 1141249251) => "Wednesday"
(weekday tm0) => "Wednesday"
(weekday tmn) => "Wednesday"
(weekday (time-encode 2006 3 1 0 0 0)) => "Wednesday"
See also Scheme source file weekday

brief-weekday
Form (brief-weekday second-count)
Description Given an integer, second-count, return the weekday as a brief string, of the time second-count. Returns a string.
Examples (brief-weekday 1141249251) => "We"
See also Scheme source file brief-weekday


5 Week number and week day number.
The functions in this section deal with week numbering and, more simple, week day numbering.

danish-week-number
Form (danish-week-number sc)
Description Given a number sc, return the week number in which sc i located. Weeknumbers are treated by means of Danish weeknumber rules
Examples (danish-week-number 1141249251) => 9
See also Scheme source file danish-week-number

weekday-number
Form (weekday-number second-count)
Description Return the weekday-number of second-count (an integer). Monday is day number 1 in the week, sunday is day number 7.
Examples (weekday-number 1141249251) => 3
See also Scheme source file weekday-number


6 Time pretty printing.
The functions in this section return pretty printed string representation of time.

date-time
Form (date-time second-count)
Description Given an integer, second-cound, return a list of two strings: (date time). This is useful in cases you need to print the data or time as a string. Takes the variable language preference into account.
Examples (date-time 1141249251) => ("March 1, 2006" "21:40:51")
See also Scheme source file date-time

date-time-one-string
Form (date-time-one-string second-count)
Description Return a single string that pretty prints the time represented by second count. Takes the variable language preference into account.
Examples (date-time-one-string 1141249251) => "March 1, 2006, 21:40:51"
See also Scheme source file date-time-one-string

when-generated
Form (when-generated)
Description Return a string that describes the current time as generation time. Takes the variable language-preference into account.
See also Scheme source file when-generated
similar function in xhtml1.0-convenience.scm when-modified


7 Time interval functions.

time-interval
Form (time-interval second-count)
Description Return the number of years, months, weeks, days, hours, minutes, and seconds from second-count. In this function, months are uniformly counted as 30 days, and a year is counted as 365 days. Due to this, a year is not exactly counted as 12 months, and therefore slightly unexpected results may occur. A list of seven integers is returned.
Examples (time-interval 3600) => (0 0 0 0 1 0 0)
(time-interval (* 24 3600)) => (0 0 0 1 0 0 0)
(time-interval 1) => (0 0 0 0 0 0 1)
(time-interval (* 30 (* 24 3600))) => (0 1 0 0 0 0 0)
(time-interval (* 7 (* 24 3600))) => (0 0 1 0 0 0 0)
(time-interval (* 365 (* 24 3600))) => (1 0 0 0 0 0 0)
(time-interval (- (* 365 (* 24 3600)) 1)) => (0 12 0 4 23 59 59)
See also Scheme source file time-interval

present-time-interval
Form (present-time-interval second-count)
Description Return a string which presens the number of years, months, weeks, days, hours, minutes, and seconds of second-count
Examples (present-time-interval (* 365 (* 24 3600))) => "1 years "
(present-time-interval (- (* 365 (* 24 3600)) 1)) => "12 months 4 days 23 hours 59 minutes 59 seconds "
(present-time-interval (* 30 (* 24 3600))) => "1 months "
(present-time-interval (* 7 (* 24 3600))) => "1 weeks "
(present-time-interval (* 24 3600)) => "1 days "
See also Scheme source file present-time-interval


8 Conventional string representation of time.
This section contains a number of functions that deal with dates and time as strings in the formats such as "ddmmyyyy" and "hhmm". The seconds are not part of the string representation.

transform-year-month-day-hour-minutes-strings
Form (transform-year-month-day-hour-minutes-strings date time)
Description Transform date and time strings to a second count (a large integer number of seconds elapsed since january 1, 1970). The date parameter is a string of the form "ddmmyyyy" (eight ciffers). The time parameter is of the form "hhmm" (four ciffers). Assumes as a prefix that date and time represent a legal point in time. Use date-ok? and time-ok? to assure this. Return #f if date is blank (or if both date and time is blank).
Examples (transform-year-month-day-hour-minutes-strings "01032006" "0000") => 1141171200
(transform-year-month-day-hour-minutes-strings "01032006" "2359") => 1141257540
See also Scheme source file transform-year-month-day-hour-minutes-strings

date-string
Form (date-string second-count)
Description Return the date, in the format "ddmmyyyy" of second-count, which represents the time in seconds elapsed since January 1, 1970.
Examples (date-string 1141257540) => "01032006"
See also Scheme source file date-string

time-string
Form (time-string second-count)
Description Return the date, in the format "ddmmyyyy" of second-count, which represents the time in seconds elapsed since January 1, 1970.
Examples (time-string 1141257540) => "2359"
See also Scheme source file time-string

date-ok?
Form (date-ok? x)
Description Return whether x is a legal date string (of the form "ddmmyyyy"). Exact determination, including february and leap years. Uses days-in-month from the time library.
Examples (date-ok? "01032006") => #t
(date-ok? "28022006") => #t
(date-ok? "29022006") => #f
(date-ok? "01012006") => #t
(date-ok? "31012006") => #t
(date-ok? "32012006") => #f
(date-ok? "31042006") => #f
(date-ok? "30042006") => #t
(date-ok? "31132006") => #f
(date-ok? "31122006") => #t
See also Scheme source file date-ok?

time-ok?
Form (time-ok? x)
Description Return whether x is a legal time string (of the form "hhmm")
Examples (time-ok? "00") => #f
(time-ok? "0000") => #t
(time-ok? "0160") => #f
(time-ok? "0159") => #t
(time-ok? "2359") => #t
(time-ok? "2459") => #f
(time-ok? "2360") => #f
See also Scheme source file time-ok?

hours-minutes-decode-string
Form (hours-minutes-decode-string hour-minute-string)
Description Decode a string of the form "h:m" or "h.m" to a list of the form (h m). Does also accept the juxtaposition "hm" in which case m is taken as the last two ciffers. Given for instance "12:35", "12.35" or "1235" return (12 35).
Examples (hours-minutes-decode-string "10.65") => (10 65)
(hours-minutes-decode-string "2231") => (22 31)
(hours-minutes-decode-string "22.31") => (22 31)
See also Scheme source file hours-minutes-decode-string

year-month-day-decode-string
Form (year-month-day-decode-string year-month-day-string)
Description Decode a string of the form "y-m-d" to a list of the form (y m d). A proper list of three integers. Given for instance "2005-9-12", return the list (2005 9 12) representing September 12, 2005.
Examples (year-month-day-decode-string "2006-3-1") => (2006 3 1)
See also Scheme source file year-month-day-decode-string


9 Underlying time related constants and functions.
In this section there is a number of auxiliary time functions. In addition, we document a number of time related constants.

seconds-in-a-normal-year
Form seconds-in-a-normal-year
Description The number of seconds in a non-leap year.
See also Scheme source file seconds-in-a-normal-year

seconds-in-a-leap-year
Form seconds-in-a-leap-year
Description The number of seconds in a leap year.
See also Scheme source file seconds-in-a-leap-year

seconds-in-a-normal-month
Form seconds-in-a-normal-month
Description The number of seconds in a 30-day month.
See also Scheme source file seconds-in-a-normal-month

seconds-in-a-week
Form seconds-in-a-week
Description The number of seconds in a week.
See also Scheme source file seconds-in-a-week

seconds-in-a-day
Form seconds-in-a-day
Description The number of seconds in a day.
See also Scheme source file seconds-in-a-day

seconds-in-an-hour
Form seconds-in-an-hour
Description The number of seconds in an hour.
See also Scheme source file seconds-in-an-hour

get-month-name
Form (get-month-name month-number)
Description Return the month name of month-number. January is number one. The result depends on the free variable language-preference.
Examples (get-month-name 1) => "January"
(get-month-name 12) => "December"
See also Scheme source file get-month-name
applied variable language-preference

leap-year
Form (leap-year y)
Description Return whether y is a leap year.
Examples (leap-year 2006) => #f
(leap-year 2000) => #t
(leap-year 1900) => #f
(leap-year 2004) => #t
(leap-year 2003) => #f
See also Scheme source file leap-year

days-in-month
Form (days-in-month month year)
Description Return the number of days in month and year
Examples (days-in-month 1 2006) => 31
(days-in-month 2 2006) => 28
(days-in-month 2 2004) => 29
(days-in-month 5 2004) => 31
(days-in-month 12 2004) => 31
See also Scheme source file days-in-month

hours-minutes-seconds-decode
Form (hours-minutes-seconds-decode second-count)
Description Return a list of (hours minutues seconds) given an integer second-count.
See also Scheme source file hours-minutes-seconds-decode


10 Other time related functions.

emacs-lisp-time-to-second-count
Form (emacs-lisp-time-to-second-count time-list)
Description Given time-list, which is Emacs' representation of Universal time, return a single (large) integer that represents universal time.
Parameters time-list A list of three 16 bit integers (high low microsec) which represents a point in time after 1969.
Returns high * 2**16 + low
Examples (emacs-lisp-time-to-second-count (list 17414 9407 300383)) => 1141253311
(time-decode (emacs-lisp-time-to-second-count (list 17414 9407 300383))) => (2006 3 1 22 48 31)
(second-count-to-emacs-lisp-time (emacs-lisp-time-to-second-count (list 17414 9407))) => (17414 9407 0)
(second-count-to-emacs-lisp-time (emacs-lisp-time-to-second-count (list 17414 9407 300383))) => (17414 9407 0)
(emacs-lisp-time-to-second-count (list 0 0)) => 0
See also Scheme source file emacs-lisp-time-to-second-count

second-count-to-emacs-lisp-time
Form (second-count-to-emacs-lisp-time second-count)
Description Given a second count, which represents a point in time as a single large integer, return a list of three 16 bit numbers that corresponds to Emacs's representation.
Parameters second-count An integer - the number of seconds elapsed since Jan 1, 1970.
Returns A list of three 16 bit integers (high low 0), for which high * 2**16 + low = second-count.
Examples (second-count-to-emacs-lisp-time (emacs-lisp-time-to-second-count (list 17414 9407))) => (17414 9407 0)
(second-count-to-emacs-lisp-time (emacs-lisp-time-to-second-count (list 17414 9407 300383))) => (17414 9407 0)
See also Scheme source file second-count-to-emacs-lisp-time

Generated: Monday, November 14, 2011, 09:18:01
Generated by LAML SchemeDoc using LAML Version 38.0 (November 14, 2011, full)