(lispkit date-time)

Library (lispkit date-time) provides functionality for handling time zones, dates, and times. Time zones are represented by string identifiers referring to the region and corresponding city, e.g. "America/Los_Angeles". Dates and times are represented via date-time data structures. These encapsulate the following components:

  • time zone: the time zone of the date

  • date: the date consisting of its year, month, and day

  • time: the time on date consisting of the hour (>= 0, < 24), the minute (>= 0, < 60), the second (>= 60, <60), and the nano second.

The library uses a floating-point representation of seconds since 00:00 UTC on January 1, 1970, as a means to refer to specific points in time independent of timezones. This means that, for instance, for comparing date-times with each other, a user would have to convert them to seconds and then compare the seconds instead. Here is an example:

(define initial-time (date-time "Europe/Zurich"))
(define later-time (date-time "GMT"))
(date-time< initial-time later-time)
  ⇒  #t
; the following line is equivalent:
(< (date-time->seconds initial-time) (date-time->seconds later-time))
  ⇒  #t

For now, (lispkit date-time) assumes all dates are based on the Gregorian calendar, independent of the settings at the operating system-level.

Time zones

Time zones are represented by string identifiers referring to the region and corresponding city, e.g. "America/Los_Angeles". Procedure timezones returns a list of all supported time zone identifiers. Each time zone has a locale-specific name and an offset in seconds from Greenwhich Mean Time. Some time zones also have an abbreviation which can be used as an alternative way to identify a time zone.

Returns a list of string identifiers for all supported time zones. If filter is provided, it can either be set to #f, in which case a list of abbreviations is returned instead, or it is a string, and only time zone identifiers which contain filter are returned.

(timezones #f)
⇒  ("CEST" "GST" "NZDT" "BRST" "WEST" "AST" "MSD" "CDT" "WIT" "MSK" "COT" "IST" "EST" "BST" "CLST" "NDT" "TRT" "EET" "IRST" "EDT" "BRT" "ICT" "CST" "AKST" "BDT" "PHT" "SGT" "WET" "ART" "CLT" "CAT" "UTC" "EEST" "ADT" "JST" "HST" "PET" "MST" "NST" "NZST" "GMT" "MDT" "PKT" "WAT" "HKT" "AKDT" "KST" "PST" "CET" "PDT" "EAT")

Returns #t if obj is a valid time zone identifier or time zone abbreviation; returns #f otherwise.

Returns the identifier for the time zone specified by ident. ident can either be an identifier, an abbreviation or a GMT offset as a floating-point number or integer. If ident does not refer to a supported time zone, procedure timezone will fail.

Returns a locale-specific name for time zone tz. If locale is not specified, the current locale defined at the operating-system level is used. format specifies the name format. It can have one of the following symbolic values:

  • standard

  • standard-short

  • dst

  • dst-short

  • generic

  • generic-short

Returns a string representing a time zone abbreviation for tz; e.g. "PDT". If the time zone tz does not have an abbreviation, this function returns #f.

Returns the difference in seconds between time zone tz and Greenwich Mean Time. The difference is returned as a floating-point number (since seconds are always represented as such by this library).

Time stamps

Time stamps, i.e. discreet points in time, are represented as floating-point numbers corresponding to the number of seconds since 00:00 UTC on January 1, 1970.

Returns a floating-point number representing the number of seconds since 00:00 UTC on January 1, 1970.

Converts the given number of seconds secs into date-time format for the given time zone tz. secs is a floating-point number. It is interpreted as the number of seconds since 00:00 UTC on January 1, 1970. secs is negative if the date-time is earlier than 00:00 UTC on January 1, 1970. If tz is missing, the current, operating-system defined time zone is used.

Returns a floating-point number representing the number of seconds since 00:00 UTC on January 1, 1970 for the given date-time object dtime.

Date-times

Returns #t if obj is a date-time object; returns #f otherwise.

Constructs a date-time representation out of the given date time components. tz is the only string argument; it is referring to a time zone. All other arguments are numeric arguments. This procedure returns a date-time object for the specified time at the given date. If no date components are provided as arguments, procedure date-time returns a date-time for the current date and time.

Constructs a date-time representation out of the given date time components. tz is the only string argument; it is referring to a time zone. All other arguments are numeric arguments. Argument wday specifies the week day in the given week. Week days are given numbers from 1 (= Monday) to 7 (= Sunday). This procedure returns a date-time object for the specified time at the given date.

The difference to date-time is that this procedure does not refer to a month and day. It rather refers to the week number as well as the weekday within this specified week number.

Constructs a date-time representation of the same point in time like dtime, but in a potentially different time zone tzone. If tzone is not given, the default time zone specified by the user in the operating system will be used.

Extracts a date and time from the given string str in the time zone tz, or the current time zone if tz is omitted. The format of the string representation is defined in terms of locale and format. format can have three different forms:

  1. Combined format identifier for date and time: date-time parsing is based on the settings of the operating system. format is one of the following symbols: none, short, medium, long, or full.

  2. Separate format identifiers for date and time: date-time parsing is based on the settings of the operating system, but the format for dates and times is specified separately. format is a list of the form (dateformat timeformat) where both dateformat and timeformat are one of the 5 symbols listed under 1. This makes it possible, for instance, to just parse a date (without time) in string form to a date-time object, e.g. by using (short none) as format.

  3. Custom format specifier: date-time parsing is based on a custom format string. format is a string using the following characters as placeholders. Repetitions of the placeholder characters are used to specify the width and format of the field.

    • y: Year

    • M: Month

    • d: Day

    • H: Hour (12 hours)

    • h: Hour (24 hours)

    • m: Minute

    • s: Second

    • S: Micro second

    • Z: Time zone

    • a: AM/PM

    • E: Weekday

Here are a few examples:

EEEE, MMM d, yyyy       ~~>  Thursday, Feb 8, 1973
dd/MM/yyyy              ~~>  08/02/1973
dd-MM-yyyy HH:mm        ~~>  08-02-1973 17:01
MMM d, h:mm a           ~~>  Thu 8, 2:11 AM
yyyy-MM-dd'T'HH:mm:ssZ  ~~>  1973-08-02T17:01:31+0000
HH:mm:ss.SSS            ~~>  11:02:19.213

Returns a string representation of the date-time object dtime. The format of the string is defined in terms of locale and format. format can have three different forms (just like for string->date-time):

  1. Combined format identifier for date and time: date-time formatting is based on the settings of the operating system. format is one of the following symbols: none, short, medium, long, or full.

  2. Separate format identifiers for date and time: date-time formatting is based on the settings of the operating system, but the format for dates and times is specified separately. format is a list of the form (dateformat timeformat) where both dateformat and timeformat are one of the 5 symbols listed under 1. This makes it possible, for instance, to just output a date (without time) in string form, e.g. by using (short none) as format.

  3. Custom format specifier: date-time formatting is based on a custom format string. format is a string using the following characters as placeholders. Repetitions of the placeholder characters are used to specify the width and format of the field.

    • y: Year

    • M: Month

    • d: Day

    • H: Hour (12 hours)

    • h: Hour (24 hours)

    • m: Minute

    • s: Second

    • S: Micro second

    • Z: Time zone

    • a: AM/PM

    • E: Weekday

Here are a few examples:

EEEE, MMM d, yyyy       ~~>  Thursday, Feb 8, 1973
dd/MM/yyyy              ~~>  08/02/1973
dd-MM-yyyy HH:mm        ~~>  08-02-1973 17:01
MMM d, h:mm a           ~~>  Thu 8, 2:11 AM
yyyy-MM-dd'T'HH:mm:ssZ  ~~>  1973-08-02T17:01:31+0000
HH:mm:ss.SSS            ~~>  11:02:19.213

Returns a string representation of the date-time object dtime in ISO 8601 format.

Returns the time zone of dtime.

Returns the year of dtime.

Returns the month of dtime.

Returns the day of dtime.

Returns the hour of dtime.

Returns the minute of dtime.

Returns the second of dtime.

Returns the nano-second of dtime.

Returns the week day of dtime. Week days are represented as fixnums where 1 is Monday, 2 is Tuesday, ..., and 7 is Sunday.

Returns the week number of dtime according to the ISO-8601 standard. Based on this standard, weeks start on Monday. The first week of the year is the week that contains that year's first Thursday.

Returns the daylight saving time offset of dtime in seconds related to GMT. If daylight savings time is not active, date-time-dst-offset returns 0.0. The result is always a floating-point number.

Returns a hash code for the given date-time object. This hash code can be used in combination with both date-time=? and date-time-same?.

Date-time predicates

Returns #t if date-time dtime1 and dtime2 have the same timezone and refer to the same point in time, i.e. (date-time->seconds dtime1) and (date-time->seconds dtime2) are equals.

(define d1 (date-time 'CET))
(define d2 (date-time-in-timezone d1 'PST))
(date-time-same? d1 d1)  ⇒  #t
(date-time-same? d1 d2)  ⇒  #f
(date-time=? d1 d2)      ⇒  #t

Returns #t if date-time dtime1 and dtime2 specify the same point in time, i.e. (date-time->seconds dtime1) and (date-time->seconds dtime2) are equals.

(define d1 (date-time 'CET))
(define d2 (date-time-in-timezone d1 'PST))
(date-time=? d1 d2)                ⇒  #t
(date-time=? d1 (date-time 'CET))  ⇒  #f

Returns #t if date-time dtime1 specifies an earlier point in time compared to dtime2, i.e. (date-time->seconds dtime1) is less than (date-time->seconds dtime2).

Returns #t if date-time dtime1 specifies a later point in time compared to dtime2, i.e. (date-time->seconds dtime1) is greater than (date-time->seconds dtime2).

Returns #t if date-time dtime1 specifies an earlier or equal point in time compared to dtime2, i.e. (date-time->seconds dtime1) is less than or equal to (date-time->seconds dtime2).

Returns #t if date-time dtime1 specifies a later or equal point in time compared to dtime2, i.e. (date-time->seconds dtime1) is greater than or equal to (date-time->seconds dtime2).

Returns #t if daylight saving time is active for dtime; returns #f otherwise.

Date-time operations

Compute a new date-time from adding days, hrs, min, sec, and nano (all fixnums) to the given date-time dtime. The resulting date-time is using the same timezone like dtime.

Compute a new date-time from adding the number of seconds sec (a flonum) to the given date-time dtime.

Computes the difference between dtime2 and dtime1 as a number of seconds (a flonum).

Returns the date and time when the next daylight savings time transition takes place after dtime. next-dst-transition returns #f if there is no daylight savings time for the time zone of dtime.

Last updated