Dates

functions for manipulating dates

Functions

Predicates

The Dates module provides functionality for working with dates and times. Dates are handled as dictionary-like values, making it easy to access and work with individual components.

Key Concepts

Dates are dictionary-like values with accessible components
Easy date arithmetic with before and after
Various time unit granularities (from nanoseconds to years)
Convenient date checks (weekdays, past/future, leaps)

Basic Usage

Creating Dates

; get current date/time
current: now
print current     ; 2024-12-13T14:30:45+01:00

; accessing components
print current\year              ; 2024
print current\month             ; 12
print current\day]              ; 13
print current\hour]             ; 14
print current\minute]           ; 30
print current\second]           ; 45

Date Arithmetic

date: now

; moving forward in time
nextWeek: after.days:7 date 
nextMonth: after.months:1 date 
nextYear: after.years:1 date 

; moving backward in time
lastWeek: before.days:7 date 
lastMonth: before.months:1 date 
lastYear: before.years:1 date 

; combine different units
meeting: after .hours:2 .minutes:30 date

Date Checks

today: now

; time comparison
future? after.days:1 today      ; => true
past? before.days:1 today       ; => true
today? today                    ; => true

; weekday checks
monday? today                   ; well... depends
friday? today                   ; on the
sunday? today                   ; actual date! :)

; year checks
print leap? 2024                ; true
print leap? today\year          ; true (if still 2024!)

Common Patterns

Working with Time Intervals

start: now
deadline: after.days:10 start 

; calculate intermediate dates
loop 0..10 'day [
    checkpoint: after.days:day start 
    print ["Day" day ":" checkpoint\day]
]
; Day 0 : 13 
; Day 1 : 14 
; Day 2 : 15 
; Day 3 : 16 
; Day 4 : 17 
; Day 5 : 18 
; Day 6 : 19 
; Day 7 : 20 
; Day 8 : 21 
; Day 9 : 22 
; Day 10 : 23

Date Formatting and Parsing

Converting dates to strings and parsing strings into dates is done using format patterns:

dt: now

; format date to string
to :string .format:"yyyy-MM-dd HH:mm:ss" dt    
; => 2024-12-13 16:55:38


; parse string to date
meeting: to :date .format:"yyyy-MM-dd" "2024-03-15"
; 2024-03-15T00:00:00+01:00

Note
When parsing dates from strings, make sure your format pattern matches exactly the structure of your input string.

Format Patterns

Pattern	Description	Example
d	Day of month (1 or 2 digits)	1, 21
dd	Day of month (2 digits)	01, 21
ddd	Abbreviated weekday	Sat, Mon
dddd	Full weekday	Saturday, Monday
M	Month (1 or 2 digits)	9, 12
MM	Month (2 digits)	09, 12
MMM	Abbreviated month	Sep, Dec
MMMM	Full month	September, December
yy	Year (2 digits)	12
yyyy	Year (4+ digits, padded)	2012, 0024
H	Hour 0-23 (1 or 2 digits)	5, 17
HH	Hour 0-23 (2 digits)	05, 17
h	Hour 1-12 (1 or 2 digits)	5, 11
hh	Hour 1-12 (2 digits)	05, 11
m	Minute (1 or 2 digits)	1, 30
mm	Minute (2 digits)	01, 30
s	Second (1 or 2 digits)	1, 45
ss	Second (2 digits)	01, 45
tt	AM/PM indicator	AM, PM
z	UTC offset (basic)	+7, -5
zzz	UTC offset with minutes	+07:00, -05:00
fff	Milliseconds	001

Common Format Examples:

date: now

; different format examples
print to :string .format:"MM/dd/yyyy" date          ; 12/13/2024
print to :string .format:"d MMM yyyy" date          ; 13 Dec 2024
print to :string .format:"MMMM d, yyyy" date        ; December 13, 2024
print to :string .format:"HH:mm:ss.fff" date        ; 14:30:45.123
print to :string .format:"h:mm tt" date             ; 2:30 PM

Tip
For common use cases, you might want to create helper functions with your preferred format patterns:
formatDate: function [dt][
    to :string .format:"yyyy-MM-dd" dt
]