module DateTime

rascal-Not specified

Library functions for date and time.

Usage

import DateTime;

Dependencies

import List;

Description

The following library functions are defined for datetime:

• Interval
• duration
• Duration
• interval
• arbDateTime
• createDate
• createDateTime
• createDuration
• createDurationInternal
• createInterval
• createTime
• dateRangeByDay
• daysDiff
• daysInInterval
• decrementDays
• decrementHours
• decrementMilliseconds
• decrementMinutes
• decrementMonths
• decrementSeconds
• decrementYears
• incrementDays
• incrementHours
• incrementMilliseconds
• incrementMinutes
• incrementMonths
• incrementSeconds
• incrementYears
• joinDateAndTime
• now
• parseDate
• parseDateInLocale
• parseDateTime
• parseDateTimeInLocale
• parseTime
• parseTimeInLocale
• printDate
• printDateInLocale
• printDateTime
• printDateTimeInLocale
• printTime
• printTimeInLocale
• splitDateTime

function now

Get the current datetime.

datetime now()

Examples

rascal>import DateTime;
ok
rascal>now();
datetime: $2026-04-13T09:29:25.043+00:00$

function createDate

Create a new date.

datetime createDate(int year, int month, int day)

Examples

rascal>import DateTime;
ok
rascal>createDate(2012,1,1);
datetime: $2012-01-01$

function createTime

Create a new time (with optional timezone offset).

datetime createTime(int hour, int minute, int second, int millisecond)

datetime createTime(int hour, int minute, int second, int millisecond, 
                                int timezoneHourOffset, int timezoneMinuteOffset)

Examples

rascal>import DateTime;
ok
rascal>createTime(8,15,30,55);
datetime: $T08:15:30.055+00:00$
rascal>createTime(8,15,30,55,2,0);
datetime: $T08:15:30.055+02:00$

function createDateTime

Create a new datetime (with optional timezone offset).

datetime createDateTime(int year, int month, int day, int hour, int minute, 
                                    int second, int millisecond)

datetime createDateTime(int year, int month, int day, int hour, int minute, 
                                    int second, int millisecond, int timezoneHourOffset, 
                                    int timezoneMinuteOffset)

Examples

rascal>import DateTime;
ok
rascal>createDateTime(2012,1,1,8,15,30,55);
datetime: $2012-01-01T08:15:30.055+00:00$
rascal>createDateTime(2012,1,1,8,15,30,55,2,0);
datetime: $2012-01-01T08:15:30.055+02:00$

function joinDateAndTime

Create a new datetime by combining a date and a time.

datetime joinDateAndTime(datetime date, datetime time)

Examples

rascal>import DateTime;
ok
rascal>D = createDate(2012, 1, 1);
datetime: $2012-01-01$
rascal>T = createTime(8, 15, 45, 30);
datetime: $T08:15:45.030+00:00$
rascal>joinDateAndTime(D, T);
datetime: $2012-01-01T08:15:45.030+00:00$

function splitDateTime

Split an existing datetime into a tuple with the date and the time.

tuple[datetime date, datetime time] splitDateTime(datetime dt)

Examples

rascal>import DateTime;
ok
rascal>N = now();
datetime: $2026-04-13T09:29:25.214+00:00$
rascal>splitDateTime(N);
tuple[datetime date,datetime time]: <$2026-04-13$,$T09:29:25.214+00:00$>

function incrementYears

Increment the years by given amount or by 1.

datetime incrementYears(datetime dt, int n)

datetime incrementYears(datetime dt)

Examples

rascal>import DateTime;
ok
rascal>N = now();
datetime: $2026-04-13T09:29:25.244+00:00$
rascal>incrementYears(N);
datetime: $2027-04-13T09:29:25.244+00:00$
rascal>incrementYears(N, 5);
datetime: $2031-04-13T09:29:25.244+00:00$

function incrementMonths

Increment the months by a given amount or by 1.

datetime incrementMonths(datetime dt, int n)

datetime incrementMonths(datetime dt)

Examples

rascal>import DateTime;
ok
rascal>N = now();
datetime: $2026-04-13T09:29:25.277+00:00$
rascal>incrementMonths(N);
datetime: $2026-05-13T09:29:25.277+00:00$
rascal>incrementMonths(N, 5);
datetime: $2026-09-13T09:29:25.277+00:00$

function incrementDays

Increment the days by given amount or by 1.

datetime incrementDays(datetime dt, int n)

datetime incrementDays(datetime dt)

Examples

rascal>import DateTime;
ok
rascal>N = now();
datetime: $2026-04-13T09:29:25.316+00:00$
rascal>incrementDays(N);
datetime: $2026-04-14T09:29:25.316+00:00$
rascal>incrementDays(N, 5);
datetime: $2026-04-18T09:29:25.316+00:00$

function incrementHours

Increment the hours by a given amount or by 1.`

datetime incrementHours(datetime dt, int n)

datetime incrementHours(datetime dt)

Examples

rascal>import DateTime;
ok
rascal>N = now();
datetime: $2026-04-13T09:29:25.346+00:00$
rascal>incrementHours(N);
datetime: $2026-04-13T10:29:25.346+00:00$
rascal>incrementHours(N, 5);
datetime: $2026-04-13T14:29:25.346+00:00$

function incrementMinutes

Increment the minutes by a given amount or by 1.

datetime incrementMinutes(datetime dt, int n)

datetime incrementMinutes(datetime dt)

Examples

rascal>import DateTime;
ok
rascal>N = now();
datetime: $2026-04-13T09:29:25.376+00:00$
rascal>incrementMinutes(N);
datetime: $2026-04-13T09:30:25.376+00:00$
rascal>incrementMinutes(N, 5);
datetime: $2026-04-13T09:34:25.376+00:00$

function incrementSeconds

Increment the seconds by a given amount or by 1.

datetime incrementSeconds(datetime dt, int n)

datetime incrementSeconds(datetime dt)

Examples

rascal>import DateTime;
ok
rascal>N = now();
datetime: $2026-04-13T09:29:25.405+00:00$
rascal>incrementSeconds(N);
datetime: $2026-04-13T09:29:26.405+00:00$
rascal>incrementSeconds(N, 5);
datetime: $2026-04-13T09:29:30.405+00:00$

function incrementMilliseconds

Increment the milliseconds by a given amount or by 1.

datetime incrementMilliseconds(datetime dt, int n)

datetime incrementMilliseconds(datetime dt)

Examples

rascal>import DateTime;
ok
rascal>N = now();
datetime: $2026-04-13T09:29:25.433+00:00$
rascal>incrementMilliseconds(N);
datetime: $2026-04-13T09:29:25.434+00:00$
rascal>incrementMilliseconds(N, 5);
datetime: $2026-04-13T09:29:25.438+00:00$

function decrementYears

Decrement the years by a given amount or by 1.

datetime decrementYears(datetime dt, int n)

datetime decrementYears(datetime dt)

Examples

rascal>import DateTime;
ok
rascal>N = now();
datetime: $2026-04-13T09:29:25.462+00:00$
rascal>decrementYears(N);
datetime: $2025-04-13T09:29:25.462+00:00$
rascal>decrementYears(N, 5);
datetime: $2021-04-13T09:29:25.462+00:00$

function decrementMonths

Decrement the months by a given amount or by 1.

datetime decrementMonths(datetime dt, int n)

datetime decrementMonths(datetime dt)

Examples

rascal>import DateTime;
ok
rascal>N = now();
datetime: $2026-04-13T09:29:25.491+00:00$
rascal>decrementMonths(N);
datetime: $2026-03-13T09:29:25.491+00:00$
rascal>decrementMonths(N, 5);
datetime: $2025-11-13T09:29:25.491+00:00$

function decrementDays

Decrement the days by a given amount or by 1.

datetime decrementDays(datetime dt, int n)

datetime decrementDays(datetime dt)

Examples

rascal>import DateTime;
ok
rascal>N = now();
datetime: $2026-04-13T09:29:25.521+00:00$
rascal>decrementDays(N);
datetime: $2026-04-12T09:29:25.521+00:00$
rascal>decrementDays(N, 3);
datetime: $2026-04-10T09:29:25.521+00:00$

function decrementHours

Decrement the hours by a given amount or by 1.

datetime decrementHours(datetime dt, int n)

datetime decrementHours(datetime dt)

Examples

rascal>import DateTime;
ok
rascal>N = now();
datetime: $2026-04-13T09:29:25.561+00:00$
rascal>decrementHours(N);
datetime: $2026-04-13T08:29:25.561+00:00$
rascal>decrementHours(N, 5);
datetime: $2026-04-13T04:29:25.561+00:00$

function decrementMinutes

Decrement the minutes by a given amount or by 1.

datetime decrementMinutes(datetime dt, int n)

datetime decrementMinutes(datetime dt)

Examples

rascal>import DateTime;
ok
rascal>N = now();
datetime: $2026-04-13T09:29:25.590+00:00$
rascal>decrementMinutes(N);
datetime: $2026-04-13T09:28:25.590+00:00$
rascal>decrementMinutes(N, 5);
datetime: $2026-04-13T09:24:25.590+00:00$

function decrementSeconds

Decrement the seconds by a given amount or by 1.

datetime decrementSeconds(datetime dt, int n)

datetime decrementSeconds(datetime dt)

Examples

rascal>import DateTime;
ok
rascal>N = now();
datetime: $2026-04-13T09:29:25.619+00:00$
rascal>decrementSeconds(N);
datetime: $2026-04-13T09:29:24.619+00:00$
rascal>decrementSeconds(N, 5);
datetime: $2026-04-13T09:29:20.619+00:00$

function decrementMilliseconds

Decrement the milliseconds by a given amount or by 1.

datetime decrementMilliseconds(datetime dt, int n)

datetime decrementMilliseconds(datetime dt)

Examples

rascal>import DateTime;
ok
rascal>N = now();
datetime: $2026-04-13T09:29:25.648+00:00$
rascal>decrementMilliseconds(N);
datetime: $2026-04-13T09:29:25.647+00:00$
rascal>decrementMilliseconds(N, 5);
datetime: $2026-04-13T09:29:25.643+00:00$

data interval

A closed interval on the time axis.

data interval  
     = Interval(datetime begin, datetime end)
     ;

function createInterval

Given two datetime values, create an interval.

interval createInterval(datetime begin, datetime end)

Examples

rascal>import DateTime;
ok
rascal>B = now();
datetime: $2026-04-13T09:29:25.677+00:00$
rascal>E = incrementDays(B, 2);
datetime: $2026-04-15T09:29:25.677+00:00$
rascal>createInterval(B, E);
interval: Interval($2026-04-13T09:29:25.677+00:00$,$2026-04-15T09:29:25.677+00:00$)

data Duration

A duration of time, measured in individual years, months, etc.

data Duration  
     = duration(int years, int months, int days, int hours, int minutes, int seconds, int milliseconds)
     ;

function createDurationInternal

tuple[int,int,int,int,int,int,int] createDurationInternal(datetime begin, datetime end)

function createDuration

Create a new duration representing the duration between the begin and end dates.

Duration createDuration(datetime begin, datetime end)

Duration createDuration(interval i)

Examples

rascal>import DateTime;
ok
rascal>B = now();
datetime: $2026-04-13T09:29:25.707+00:00$
rascal>E1 = incrementHours(B);
datetime: $2026-04-13T10:29:25.707+00:00$
rascal>createDuration(B, E1);
Duration: duration(0,0,0,1,0,0,0)
rascal>E2 = incrementMinutes(B);
datetime: $2026-04-13T09:30:25.707+00:00$
rascal>createDuration(B, E2);
Duration: duration(0,0,0,0,1,0,0)

function daysInInterval

Return the number of days in an interval, including the begin and end days.

int daysInInterval(interval i)

Examples

rascal>import DateTime;
ok
rascal>B = now();
datetime: $2026-04-13T09:29:25.739+00:00$
rascal>E = incrementDays(B, 2);
datetime: $2026-04-15T09:29:25.739+00:00$
rascal>I = createInterval(B, E);
interval: Interval($2026-04-13T09:29:25.739+00:00$,$2026-04-15T09:29:25.739+00:00$)
rascal>daysInInterval(I);
int: 2

function daysDiff

Return the difference between two dates and/or datetimes in days.

int daysDiff(datetime begin, datetime end)

Examples

rascal>import DateTime;
ok
rascal>B = now();
datetime: $2026-04-13T09:29:25.785+00:00$
rascal>E = incrementDays(B, 2);
datetime: $2026-04-15T09:29:25.785+00:00$
rascal>daysDiff(B, E);
int: 2

function dateRangeByDay

Given an interval, return a list of days.

list[datetime] dateRangeByDay(interval i)

Given an interval i, return a list of days [i.begin, ..., i.end].

Examples

rascal>import DateTime;
ok
rascal>B = now();
datetime: $2026-04-13T09:29:25.814+00:00$
rascal>E = incrementDays(B, 2);
datetime: $2026-04-15T09:29:25.814+00:00$
rascal>I = createInterval(B, E);
interval: Interval($2026-04-13T09:29:25.814+00:00$,$2026-04-15T09:29:25.814+00:00$)
rascal>dateRangeByDay(I);
list[datetime]: [$2026-04-13$,$2026-04-14$,$2026-04-15$]

function parseDate

Parse an input date given as a string using the given format string.

datetime parseDate(str inputDate, str formatString)

Examples

rascal>import DateTime;
ok
rascal>parseDate("2011-12-23", "yyyy-MM-dd");
datetime: $2011-12-23$
rascal>parseDate("20111223", "yyyyMMdd");
datetime: $2011-12-23$

function parseDateInLocale

Parse an input date given as a string using a specific locale and format string.

datetime parseDateInLocale(str inputDate, str formatString, str locale)

function parseTime

Parse an input time given as a string using the given format string.

datetime parseTime(str inputTime, str formatString)

Examples

rascal>import DateTime;
ok
rascal>parseTime("11/21/19", "HH/mm/ss");
datetime: $T11:21:19.000+00:00$

function parseTimeInLocale

Parse an input time given as a string using a specific locale and format string.

datetime parseTimeInLocale(str inputTime, str formatString, str locale)

function parseDateTime

Parse an input datetime given as a string using the given format string.

datetime parseDateTime(str inputDateTime, str formatString)

Examples

rascal>import DateTime;
ok
rascal>parseDateTime("2011/12/23/11/19/54", "YYYY/MM/dd/HH/mm/ss");
datetime: $2010-12-26T11:19:54.000+00:00$

function parseDateTimeInLocale

Parse an input datetime given as a string using a specific locale and format string.

datetime parseDateTimeInLocale(str inputDateTime, str formatString, str locale)

function printDate

Print an input date using the given format string.

str printDate(datetime inputDate, str formatString)

str printDate(datetime inputDate)

Examples

rascal>import DateTime;
ok
rascal>printDate(now());
str: "2026-04-13"
───
2026-04-13
───
rascal>printDate(now(), "YYYYMMdd");
str: "20260413"
───
20260413
───

function printDateInLocale

Print an input date using a specific locale and format string.

str printDateInLocale(datetime inputDate, str formatString, str locale)

str printDateInLocale(datetime inputDate, str locale)

Examples

rascal>import DateTime;
ok
rascal>printDateInLocale(now(), "Europe/Netherlands");
str: "2026-04-13"
───
2026-04-13
───
rascal>printDateInLocale(now(), "French");
str: "2026-04-13"
───
2026-04-13
───

function printTime

Print an input time using the given format string.

str printTime(datetime inputTime, str formatString)

str printTime(datetime inputTime)

Examples

rascal>import DateTime;
ok
rascal>N = now();
datetime: $2026-04-13T09:29:26.016+00:00$
rascal>printTime(N);
str: "09:29:26.016+0000"
───
09:29:26.016+0000
───
rascal>printTime(N, "HH/mm/ss");
str: "09/29/26"
───
09/29/26
───

function printTimeInLocale

Print an input time using a specific locale and format string.

str printTimeInLocale(datetime inputTime, str formatString, str locale)

str printTimeInLocale(datetime inputTime, str locale)

function printDateTime

Print an input datetime using the given format string.

str printDateTime(datetime inputDateTime, str formatString)

str printDateTime(datetime inputDateTime)

Examples

rascal>import DateTime;
ok
rascal>N = now();
datetime: $2026-04-13T09:29:26.069+00:00$
rascal>printDateTime(N);
str: "2026-04-13 09:29:26.069+0000"
───
2026-04-13 09:29:26.069+0000
───
rascal>printDateTime(N, "yyyy-MM-dd\'T\'HH:mm:ss.SSSZZ");
str: "2026-04-13T09:29:26.069+0000"
───
2026-04-13T09:29:26.069+0000
───
rascal>printDateTime(N, "YYYY/MM/dd/HH/mm/ss");
str: "2026/04/13/09/29/26"
───
2026/04/13/09/29/26
───

function printDateTimeInLocale

Print an input datetime using a specific locale and format string.

str printDateTimeInLocale(datetime inputDateTime, str formatString, str locale)

str printDateTimeInLocale(datetime inputDateTime, str locale)

function arbDateTime

Create a new arbitrary datetime.

datetime arbDateTime()

Examples

rascal>import DateTime;
ok
rascal>arbDateTime();
datetime: $1976-10-25T23:21:22.000+00:00$