timable

8.16.0.4

timable🔗ℹ

Yanying Wang <yanyingwang1@gmail.com>

(require timable)

package: timable

This library provides a bundle of extended functions for racket’s various time/date libs.

source code: https://github.com/yanyingwang/timable
Since this lib is not very stable, I may change the interfaces along with my learning of racket lang, you’d better specify this pkg with the git commit id such as: https://github.com/yanyingwang/timable#a6c610de02336a0f0858e50ce5f016bd82b79b8a.
Check more at Package Sources.
Please use gregor instead of srfi/19 if possible, since this lib is tightly sticking with gregor.
(require timable) is same as (require timable/gregor timable/convert).

1 Extended gregor

1.1 from base gregor

1.2 from converting between sql and gregor

2 Extended srfi/19

3 Change Logs

1 Extended gregor🔗ℹ

1.1 from base gregor🔗ℹ

Procedures that extended from Gregor: Dates and Times.

(require timable/gregor)

package: timable

Examples:

> (require timable/gregor
gregor)
> (current-datetime)
#<datetime 2025-04-01T17:12:16.057723145>
> (prev-day (now))
#<datetime 2025-03-31T17:12:16.064203125>
> (at-beginning/on-month (now))
#<datetime 2025-04-01T00:00:00>
> (parse/datetime "2018-02-14 12:30:45")
#<datetime 2018-02-14T12:30:45>

procedure
(current-date) → date?
procedure
(current-datetime) → datetime?
procedure
(current-datetime/utc) → moment?
procedure
(current-moment) → moment?
procedure
(current-moment/utc) → moment?

current-date is an alias procedure of today.
current-datetime is an alias procedure of now.
current-datetime/utc is an alias procedure of now/utc.
current-moment is an alias procedure of now/moment.
current-moment/utc is an alias procedure of now/moment/utc.

Examples:

> (current-date)
#<date 2025-04-01>
> (current-datetime)
#<datetime 2025-04-01T17:12:16.526743408>
> (current-moment)
#<moment 2025-04-01T17:12:16.528376221Z[UTC]>
> (current-moment/utc)
#<moment 2025-04-01T17:12:16.530109131Z[Etc/UTC]>

procedure
(years-ago n) → datetime?
  n : integer?
procedure
(months-ago n) → datetime?
  n : integer?
procedure
(days-ago n) → datetime?
  n : integer?
procedure
(hours-ago n) → datetime?
  n : integer?
procedure
(years-ago/utc n) → datetime?
  n : integer?
procedure
(months-ago/utc n) → datetime?
  n : integer?
procedure
(days-ago/utc n) → datetime?
  n : integer?
procedure
(hours-ago/utc n) → datetime?
  n : integer?

Examples:

> (now)
#<datetime 2025-04-01T17:12:16.9658125>
> (hours-ago 1)
#<datetime 2025-04-01T16:12:16.968292236>
> (months-ago 3)
#<datetime 2025-01-01T17:12:16.970828613>
> (years-ago 1)
#<datetime 2024-04-01T17:12:16.972705078>
> (hours-ago/utc 1)
#<datetime 2025-04-01T16:12:16.975354492>

procedure
(years-from-now n) → datetime?
  n : integer?
procedure
(days-from-now n) → datetime?
  n : integer?
procedure
(hours-from-now n) → datetime?
  n : integer?
procedure
(years-from-now/utc n) → datetime?
  n : integer?
procedure
(days-from-now/utc n) → datetime?
  n : integer?
procedure
(hours-from-now/utc n) → datetime?
  n : integer?

Examples:

> (now)
#<datetime 2025-04-01T17:12:17.414658691>
> (hours-from-now 1)
#<datetime 2025-04-01T18:12:17.417033691>

procedure
(prev-day t) → (or/c date? time? datetime? moment?)
  t : (or/c date? time? datetime? moment?)
procedure
(next-day t) → (or/c date? time? datetime? moment?)
  t : (or/c date? time? datetime? moment?)
procedure
(prev-month t) → (or/c date? time? datetime? moment?)
  t : (or/c date? time? datetime? moment?)
procedure
(next-month t) → (or/c date? time? datetime? moment?)
  t : (or/c date? time? datetime? moment?)
procedure
(prev-year t) → (or/c date? time? datetime? moment?)
  t : (or/c date? time? datetime? moment?)
procedure
(next-year t) → (or/c date? time? datetime? moment?)
  t : (or/c date? time? datetime? moment?)

Examples:

> (now)
#<datetime 2025-04-01T17:12:17.875672119>
> (prev-year (now))
#<datetime 2024-04-01T17:12:17.878022949>

procedure
(at-beginning/on-day t) → (or/c datetime? moment?)
  t : (or/c date? datetime? moment?)
procedure
(at-end/on-day t) → (or/c datetime? moment?)
  t : (or/c date? datetime? moment?)
procedure
(at-beginning/on-month t) → (or/c datetime? moment?)
  t : (or/c date? datetime? moment?)
procedure
(at-end/on-month t) → (or/c date? datetime? moment?)
  t : (or/c date? datetime? moment?)
procedure
(at-beginning/on-year t) → (date? or/c datetime? moment?)
  t : (or/c date? datetime? moment?)
procedure
(at-end/on-year t) → (or/c date? datetime? moment?)
  t : (or/c date? datetime? moment?)

Examples:

> (now)
#<datetime 2025-04-01T17:12:18.427212891>
> (at-beginning/on-day (now))
#<datetime 2025-04-01T00:00:00>
> (at-beginning/on-month (now))
#<datetime 2025-04-01T00:00:00>
> (at-end/on-month (now))
#<datetime 2025-04-30T23:59:59.999999999>

procedure
(->utc-offset/hours m) → number?
m : moment?

Return a number stands for the utc offset hours. While ->utc-offset returns the seconds.

Examples:

> (now/moment)
#<moment 2025-04-01T17:12:18.900443359Z[UTC]>
> (->utc-offset/hours (now/moment))
0

procedure
(parse/datetime str) → datetime?
str : string?

Parse str and return a datetime for it.

Examples:

> (parse/datetime "2018-02-14 12:30:45")
#<datetime 2018-02-14T12:30:45>
> (parse/datetime "2018/02-14 12-30 45")
#<datetime 2018-02-14T12:30:45>

1.2 from converting between sql and gregor🔗ℹ

Functions that converting between MySQL Types and Gregor: Dates and Times.

(require timable/convert)

package: timable

Examples:

> (require gregor)
> (->sql-timestamp (today))
(sql-timestamp 2025 4 1 0 0 0 0 #f)
> (today/sql)
(sql-date 2025 4 1)

procedure
(date->sql-timestamp d) → sql-timestamp?
  d : date?
procedure
(datetime->sql-timestamp d) → sql-timestamp?
  d : datetime?
procedure
(moment->sql-timestamp d) → sql-timestamp?
  d : moment?
procedure
(->sql-timestamp d) → sql-timestamp?
  d : (or/c date? datetime? moment?)

Convert d from gregor moment to sql-timestamp.

Examples:

> (->sql-timestamp (today))
(sql-timestamp 2025 4 1 0 0 0 0 #f)
> (->sql-timestamp (now))
(sql-timestamp 2025 4 1 17 12 20 366682129 #f)
> (->sql-timestamp (now/moment))
(sql-timestamp 2025 4 1 17 12 20 371801025 0)
> (->sql-timestamp (now))
(sql-timestamp 2025 4 1 17 12 20 373794189 #f)
> (->sql-timestamp (now/moment #:tz "Asia/Shanghai"))
(sql-timestamp 2025 4 2 1 12 20 375975586 8)

procedure
(now/sql d) → sql-timestamp?
  d : moment?
procedure
(now/moment/sql d) → sql-timestamp?
  d : moment?
procedure
(today/sql d) → sql-date?
  d : date?
procedure
(current-datetime/sql d) → sql-timestamp?
  d : datetime?
procedure
(current-moment/sql d) → sql-timestamp?
  d : moment?
procedure
(current-date/sql d) → sql-date?
  d : date?

Use current-datetime/sql as an alias of now/sql to return now in sql-timestamp type.
Use current-moment/sql as an alias of now/moment/sql to return now/moment in sql-timestamp-tz type.
Use current-date/sql as an alias of today/sql to return today in sql-date type.

Examples:

> (today)
#<date 2025-04-01>
> (today/sql)
(sql-date 2025 4 1)
> (now/sql)
(sql-timestamp 2025 4 1 17 12 20 876828613 #f)
> (now/moment/sql #:tz "Asia/Shanghai")
(sql-timestamp 2025 4 1 17 12 20 878973389 0)

2 Extended srfi/19🔗ℹ

Procedures that extended from SRFI 19: Time Data Types and Procedures.

(require timable/srfi)

package: timable

Examples:

> (require srfi/19)
> (require timable/srfi)
> (hours-ago 5)
(date* 21 12 12 1 4 2025 2 90 #f 0 467000000 "")
> (time-in-range? (current-time) (hours-ago/time 1) (hours-from-now/time 1))
#t
> (last-oclock (current-date))
(date* 0 0 17 1 4 2025 2 90 #f 0 0 "")
> (last-oclock/time (current-time))
(tm:time 'time-utc 0 1743526800)
> (oclocks-between (hours-ago 2) (hours-ago 5))
(list
(date* 0 0 12 1 4 2025 2 90 #f 0 0 "")
(date* 0 0 13 1 4 2025 2 90 #f 0 0 "")
(date* 0 0 14 1 4 2025 2 90 #f 0 0 "")
(date* 0 0 15 1 4 2025 2 90 #f 0 0 ""))
> (oclocks-between/time (hours-ago/time 2) (hours-ago/time 5))
(list
(tm:time 'time-utc 0 1743508800)
(tm:time 'time-utc 0 1743512400)
(tm:time 'time-utc 0 1743516000)
(tm:time 'time-utc 0 1743519600))
> (beginning-date (current-date))
(date* 0 0 0 1 4 2025 2 90 #f 0 0 "")
> (beginning-date/month (current-date))
(date* 0 0 0 1 4 2025 2 90 #f 0 0 "")
> (beginning-date/year (current-date))
(date* 0 0 0 1 1 2025 3 0 #f 0 0 "")
> (date->string (date-parse "2018-01-01 11:11:11 +0800"))
"Mon Jan 01 11:11:11+0800 2018"
> (date->string (date-parse "2018/01/01 12"))
"Mon Jan 01 12:00:00Z 2018"

value
unix-epoch-time : time?

returns the unix epoch time, which is 1970-01-01T00:00:00Z.

value
unix-epoch-date : date?

returns the unix-epoch-time in date type.

procedure
(hours-ago n) → date?
n : number?

an alias procedure of hours-ago/date

procedure
(hours-ago/time n) → time?
n : number?

returns a time of n hours ago.

procedure
(hours-ago/date n) → date?
n : number?

returns a date of n hours ago.

procedure
(hours-from-now n) → date?
n : number?

an alias procedure of hours-from-now/date

procedure
(hours-from-now/time n) → time?
n : number?

returns a time of n hours from now on.

procedure
(hours-from-now/date n) → date?
n : number?

returns a date of n hours from now on.

procedure
(time-in-range? time1 time2 time3) → boolean?
  time1 : time?
  time2 : time?
  time3 : time?

an alias procedure of time-in-range<>?

procedure
(time-in-range<>? time1 time2 time3) → boolean?
  time1 : time?
  time2 : time?
  time3 : time?

Is time1 in the range of time2 and time3?

procedure
(time-in-range==? time1 time2 time3) → boolean?
  time1 : time?
  time2 : time?
  time3 : time?

an alias procedure of time-in-range=<>=?

procedure
(time-in-range=<>=? time1 time2 time3) → boolean?
  time1 : time?
  time2 : time?
  time3 : time?

Is time1 in the range of time2 and time3(is in if time1 equals time2 or time3)?

procedure
(time-in-range=<>? time1 time2 time3) → boolean?
  time1 : time?
  time2 : time?
  time3 : time?

Is time1 in the range of time2 and time3(is in if time1 equals time2)?

procedure
(time-in-range<>=? time1 time2 time3) → boolean?
  time1 : time?
  time2 : time?
  time3 : time?

Is time1 in the range of time2 and time3(is in if time1 equals time3)?

procedure
(beginning-date d) → date?
d : date?

beginning-date is an alias procedure of beginning-date/day.

procedure
(beginning-date/day d) → date?
d : date?

beginning-date/day returns a new date which is the first date of the day of d.

procedure
(beginning-date/month d) → date?
d : date?

beginning-date/month returns a new date which is the first date of the month of d.

procedure
(beginning-date/year d) → date?
d : date?

beginning-date/year returns a new date which is the first date of the year of d.

procedure
(end-date d) → date?
d : date?

end-date is an alias procedure of end-date/day.

procedure
(end-date/day d) → date?
d : date?

end-date/day returns a new date which is the end date of the day of d.

procedure
(end-date/month d) → date?
d : date?

end-date/month returns a new date which is the end date of the month of d.

procedure
(end-date/year d) → date?
d : date?

end-date/year returns a new date which is the endt date of the year of d.

procedure
(previous-date/day d) → date?
d : date?

returns a new date which is the same date of yesterday of d.

procedure
(date-parse str) → date?
str : string?

try to returns a date with parsing the string str.

procedure
(previous-date/month d) → date?
d : date?

returns a new date which is the same date of last month of d.

procedure
(last-oclock/time d) → time?
d : time?

returns a new time which is the recently last oclock time of d.

procedure
(last-oclock/date d) → date?
d : date?

returns a new date which is the recently last oclock time of d.

procedure
(last-oclock d) → date?
d : date?

an alias procedure of last-oclock/date.

procedure
(oclocks-between d1 d2) → list?
d1 : date?
d2 : date?

an alias procedure of oclocks-between/date.

procedure
(oclocks-between/time t1 t2) → list?
t1 : time?
t2 : time?

returns a list of all the time oclocks between t1 and t2.

procedure
(oclocks-between/date d1 d2) → list?
d1 : date?
d2 : date?

returns a list of all the date oclocks between d1 and d2.

procedure
(time-utc->date->string t [format-string]) → string?
t : time?
format-string : string? = "~c"

convert the time to date and then to string with format-string of PLT-specific extensions(string->date).

procedure
(time-utc->string t [format-string]) → string?
t : time?
format-string : string? = "~c"

an alias procedure of time-utc->date->string.

3 Change Logs🔗ℹ

at-end/on-month. –2020/02/04
enh docs for gregor. –2020/02/03
version 0.2.0
add parse/datetime to gregor lib. –2019/12/16
add now/sql now/moment/sql today/sql ... to convert lib.
rename timeless to timable and add support to gregor and sql-timestamp.
splited from chive and name it to timeless only support srfi/19 lib.
refactor chive from chez scheme version to racket.