▼Gregor:   Dates and Times
On this page:
gen:  datetime-provider
datetime-provider?
->datetime/  local
->datetime/  utc
->posix
->jd
years-between
months-between
weeks-between
days-between
hours-between
minutes-between
seconds-between
milliseconds-between
microseconds-between
nanoseconds-between
with-timezone
6.2.901.900
  top  ← prev  up  next → 

9 Generic Datetime Operations

value

gen:datetime-provider : any/c

An interface, implemented by datetime, and moment, that supplies generic operations on datetimes.

In fact, gen:datetime-provider is also implemented by date, which can be treated like a datetime with its time component set to midnight. This should be considered an experimental part of the design, which may be removed.

procedure

(datetime-provider? x) → boolean?

  x : any/c
Returns #t if x implements gen:datetime-provider; #f otherwise.

procedure

(->datetime/local t) → datetime?

  t : datetime-provider?
Returns the local datetime corresponding to t.

Examples:

> (->datetime/local (datetime 1969 7 21 2 56))

#<datetime 1969-07-21T02:56:00>

> (->datetime/local (moment 2015 3 8 1 #:tz "America/New_York"))

#<datetime 2015-03-08T01:00:00>

procedure

(->datetime/utc t) → datetime?

  t : datetime-provider?
Returns the UTC datetime corresponding to t.

For a datetime, ->datetime/local and ->datetime/utc return the same thing.

Examples:

> (->datetime/utc (datetime 1969 7 21 2 56))

#<datetime 1969-07-21T02:56:00>

> (->datetime/utc (moment 2015 3 8 1 #:tz "America/New_York"))

#<datetime 2015-03-08T06:00:00>

procedure

(->posix t) → rational?

  t : datetime-provider?
Returns the number of seconds between the UNIX epoch (UTC midnight on January 1, 1970) and t, expressed as a rational number.

Examples:

> (->posix (datetime 1970))

0

> (->posix (moment 2015 3 8 1 #:tz "America/New_York"))

1425794400

procedure

(->jd t) → rational?

  t : datetime-provider?
Returns the number of days since the Julian epoch (noon on November 24, 4714 BCE in the proleptic Gregorian calendar), expressed as a rational number.

Examples:

> (->jd (moment -4713 11 24 12 #:tz "Etc/UTC"))

0

> (->jd (datetime 1970))

4881175/2

procedure

(years-between t1 t2) → exact-integer?

  t1 : datetime-provider?
  t2 : datetime-provider?

procedure

(months-between t1 t2) → exact-integer?

  t1 : datetime-provider?
  t2 : datetime-provider?

procedure

(weeks-between t1 t2) → exact-integer?

  t1 : datetime-provider?
  t2 : datetime-provider?

procedure

(days-between t1 t2) → exact-integer?

  t1 : datetime-provider?
  t2 : datetime-provider?

procedure

(hours-between t1 t2) → exact-integer?

  t1 : datetime-provider?
  t2 : datetime-provider?

procedure

(minutes-between t1 t2) → exact-integer?

  t1 : datetime-provider?
  t2 : datetime-provider?

procedure

(seconds-between t1 t2) → exact-integer?

  t1 : datetime-provider?
  t2 : datetime-provider?

procedure

(milliseconds-between t1 t2) → exact-integer?

  t1 : datetime-provider?
  t2 : datetime-provider?

procedure

(microseconds-between t1 t2) → exact-integer?

  t1 : datetime-provider?
  t2 : datetime-provider?

procedure

(nanoseconds-between t1 t2) → exact-integer?

  t1 : datetime-provider?
  t2 : datetime-provider?
Returns the duration between the given date providers, in terms of the chosen unit. These functions follow the same rules as date and time arithmetic. So, for example, there is exactly one year between successive January 1sts, whether or not the actual span is 365 or 366 days.

Examples:

> (years-between (datetime 2000) (datetime 2001))

1

> (years-between (datetime 2001) (datetime 2002))

1

> (months-between (datetime 2000 3) (datetime 1999 12))

-3

> (days-between (moment 2015 3 8  1 59 #:tz "America/Los_Angeles")
                (moment 2015 3 16 1 59 #:tz "America/Los_Angeles"))

8

> (weeks-between (moment 2015 3 8  1 59 #:tz "America/Los_Angeles")
                 (moment 2015 3 16 1 59 #:tz "Etc/UTC"))

1

> (days-between (datetime 2015) (datetime 2015 1 14 23 59 59))

13

> (hours-between (moment 2000 #:tz "Etc/UTC")
                 (moment 1999 12 31 19 #:tz "America/New_York"))

0

> (minutes-between (datetime 2000) (datetime 2000 1 2))

1440

> (seconds-between (datetime 2000) (datetime 2000 1 2))

86400

> (milliseconds-between (datetime 2000) (datetime 2000 1 2))

86400000

> (microseconds-between (datetime 2000) (datetime 2000 1 2))

86400000000

> (nanoseconds-between (datetime 2000) (datetime 2000 1 2))

86400000000000

procedure

(with-timezone t 
  tz 
  #:resolve-offset resolve-offset) 
 → timezone-provider?
  t : datetime-provider?
  tz : tz/c
  resolve-offset : offset-resolver/c
Attaches tz to the local datetime component of t. Note that if t starts with any timezone information, it is discarded.

This function is a blunt instrument and is rarely needed. If your aim is to translate a moment into another that represents the same point in absolute time but in a different time zone, then you’re looking for adjust-timezone.

Examples:

> (with-timezone (datetime 2000) "America/New_York")

#<moment 2000-01-01T00:00:00-05:00[America/New_York]>

> (with-timezone (moment 2000 #:tz "America/New_York") "Europe/Paris")

#<moment 2000-01-01T00:00:00+01:00[Europe/Paris]>

  top  ← prev  up  next →