On this page:
years
months
weeks
days
hours
minutes
seconds
milliseconds
microseconds
nanoseconds
empty-period
period
period?
date-period?
time-period?
period-empty?
period-ref
period-set
period->list
period->date-period
period->time-period
negate-period
date-units
time-units
temporal-units
date-unit/  c
time-unit/  c
temporal-unit/  c
date-period-between
time-period-between
period-between
7.1

6 Date and Time Periods

 (require gregor/period) package: gregor-lib

procedure

(years n)  date-period?

  n : exact-integer?

procedure

(months n)  date-period?

  n : exact-integer?

procedure

(weeks n)  date-period?

  n : exact-integer?

procedure

(days n)  date-period?

  n : exact-integer?

procedure

(hours n)  time-period?

  n : exact-integer?

procedure

(minutes n)  time-period?

  n : exact-integer?

procedure

(seconds n)  time-period?

  n : exact-integer?

procedure

(milliseconds n)  time-period?

  n : exact-integer?

procedure

(microseconds n)  time-period?

  n : exact-integer?

procedure

(nanoseconds n)  time-period?

  n : exact-integer?
Per-field period constructors.

Examples:
> (years 3)

#<period of 3 years>

> (days -20)

#<period of -20 days>

> (seconds 900)

#<period of 900 seconds>

Returns a period representing no time.

Example:
> empty-period

#<period [empty]>

procedure

(period p ...)  period?

  p : period?
Returns a period representing the sum of the given ps.

Examples:
> (period)

#<period [empty]>

> (period [years 6] [days 40] [hours 20] [milliseconds 100])

#<period of 6 years, 40 days, 20 hours, 100 milliseconds>

> (period [years 10] [years -5])

#<period of 5 years>

The same identifier also acts as a match expander with the same syntax:

Example:
> (match (months 4)
    [(period [years y] [months m] [hours h]) (list y m h)])

'(0 4 0)

procedure

(period? v)  boolean?

  v : any/c
Returns #t if v is a period, #f otherwise.

procedure

(date-period? p)  boolean?

  p : period?
Returns #t if all of p’s time fields are 0, #f otherwise. Equivalent to:

procedure

(time-period? p)  boolean?

  p : period?
Returns #t if all of p’s date fields are 0, #f otherwise. Equivalent to:

procedure

(period-empty? p)  boolean?

  p : period?
Returns #t if all of p’s fields are 0, #f otherwise. Equivalent to:

procedure

(period-ref p f)  exact-integer?

  p : period?
  f : temporal-unit/c
Returns the value in period p corresponding to field f.

Examples:
> (period-ref (years 10) 'years)

10

> (period-ref (years 10) 'hours)

0

procedure

(period-set p f n)  period?

  p : period?
  f : temporal-unit/c
  n : exact-integer
Returns a fresh period equivalent to p, except that field f is set to n.

Examples:
> (period-set (years 10) 'years -10)

#<period of -10 years>

> (period-set (years 10) 'hours -10)

#<period of 10 years, -10 hours>

procedure

(period->list p)

  (listof (cons/c temporal-unit/c exact-integer?))
  p : period?
Returns an association list with the same mappings as p.

Examples:
> (period->list (years 10))

'((years . 10)

  (months . 0)

  (weeks . 0)

  (days . 0)

  (hours . 0)

  (minutes . 0)

  (seconds . 0)

  (milliseconds . 0)

  (microseconds . 0)

  (nanoseconds . 0))

> (period->list (period))

'((years . 0)

  (months . 0)

  (weeks . 0)

  (days . 0)

  (hours . 0)

  (minutes . 0)

  (seconds . 0)

  (milliseconds . 0)

  (microseconds . 0)

  (nanoseconds . 0))

> (period->list (period [hours 20] [minutes 10] [seconds 5]))

'((years . 0)

  (months . 0)

  (weeks . 0)

  (days . 0)

  (hours . 20)

  (minutes . 10)

  (seconds . 5)

  (milliseconds . 0)

  (microseconds . 0)

  (nanoseconds . 0))

procedure

(period->date-period p)  date-period?

  p : period?
Returns a fresh period containing only the date components of p.

Example:
> (period->date-period (period [years 1] [months 2] [days 3] [hours 4] [minutes 5] [seconds 6]))

#<period of 1 year, 2 months, 3 days>

procedure

(period->time-period p)  time-period?

  p : period?
Returns a fresh period containing only the time components of p.

Example:
> (period->time-period (period [years 1] [months 2] [days 3] [hours 4] [minutes 5] [seconds 6]))

#<period of 4 hours, 5 minutes, 6 seconds>

procedure

(negate-period p)  period?

  p : period?
Returns a period where each of p’s components is negated.

Example:
> (negate-period (period [years 1] [months 2] [days 3] [hours 4] [minutes 5] [seconds 6]))

#<period of -1 year, -2 months, -3 days, -4 hours, -5 minutes, -6 seconds>

value

date-units : (listof symbol?) = '(years months weeks days)

value

time-units : (listof symbol?)

 = 
'(hours
  minutes
  seconds
  milliseconds
  microseconds
  nanoseconds)

value

temporal-units : (listof symbol?)

 = 
'(years
  months
  weeks
  days
  hours
  minutes
  seconds
  milliseconds
  microseconds
  nanoseconds)

value

date-unit/c : flat-contract?

value

time-unit/c : flat-contract?

value

temporal-unit/c : flat-contract?

Contracts requiring that values be members of date-units, time-units, or temporal-units, respectively.

procedure

(date-period-between p1 p2 [fields])  date-period?

  p1 : date-provider?
  p2 : date-provider?
  fields : (listof date-unit/c) = date-units
Computes the date period between p1 and p2 in terms of the units supplied in fields.

Example:
> (date-period-between (date 1959 5 22) (date 1980 1 18) '(years months days))

#<period of 20 years, 7 months, 27 days>

procedure

(time-period-between p1 p2 [fields])  time-period?

  p1 : time-provider?
  p2 : time-provider?
  fields : (listof time-unit/c) = time-units
Computes the time period between p1 and p2 in terms of the units supplied in fields.

Example:
> (time-period-between (datetime 1970) (now))

#<period of 427950 hours, 41 minutes, 17 seconds, 983 milliseconds, 84 microseconds, 961 nanoseconds>

procedure

(period-between p1 p2 [fields])  period?

  p1 : datetime-provider?
  p2 : datetime-provider?
  fields : (listof temporal-unit/c) = temporal-units
Computes the period between p1 and p2 in terms of the units supplied in fields.

Example:
> (period-between (datetime 1970) (now) '(years months days hours minutes seconds))

#<period of 48 years, 9 months, 26 days, 6 hours, 41 minutes, 17 seconds>