DateTimeLib — Plan9Basic Documentation

DateTimeLib — Date & Time Library

Comprehensive date and time operations for Plan9Basic. Get current date/time, convert between values and strings, extract components, calculate differences, add/subtract intervals, check calendar properties, and format output with custom patterns.

Category	Count	Description
Current Date/Time	9	now, date, time, today, yesterday, tomorrow, etc.
Conversion	7	datetostr$, strtodate, timetostr$, formatdatetime$, etc.
Date Components	7	yearof, monthof, dayof, dayofweek, dayoftheyear, weekof, etc.
Time Components	4	hourof, minuteof, secondof, millisecondof
Differences (Whole)	8	daysbetween, hoursbetween, monthsbetween, yearsbetween, etc.
Differences (Fractional)	8	dayspan, hourspan, monthspan, yearspan, etc.
Incrementing	7	incday, inchour, incminute, incweek, incyear, etc.
Calendar Info	6	daysinamonth, daysinayear, weeksinayear, etc.
Boolean Tests	5	isam, ispm, isinleapyear, istoday, issameday

How Date/Time Values Work

In Plan9Basic, dates and times are numeric values (floating-point). The integer part is the date (days since Dec 30, 1899) and the fractional part is the time (fraction of a 24-hour day). So 0.5 = noon, 0.25 = 6:00 AM, 0.75 = 6:00 PM.

Type	Default Format	Example
Date	`yyyy-MM-dd`	2025-01-02
Time	`hh:mm:ss.zzz`	14:30:45.123
DateTime	`yyyy-MM-dd hh:mm:ss`	2025-01-02 14:30:45

Getting Current Date & Time

Function	Signature	Description
`now()`	`now@`	Current date and time (numeric)
`date()`	`date@`	Current date only (midnight)
`date$()`	`date$@`	Current date as string yyyy-MM-dd
`time()`	`time@`	Current time only (fraction of day)
`time$()`	`time$@`	Current time as string hh:mm:ss.zzz
`gettime()`	`gettime@`	Same as time()
`datetime$()`	`datetime$@`	Current date/time as string
`today()`	`today@`	Today at midnight
`yesterday()`	`yesterday@`	Yesterday at midnight
`tomorrow()`	`tomorrow@`	Tomorrow at midnight

╯ plan9basic─◻✕
println "Date: "; date$()
println "Time: "; time$()
println "Now:  "; datetime$()

dt = now()
println "Raw value: "; dt
println "Formatted: "; datetimetostr$(dt)

println "Yesterday: "; datetostr$(yesterday())
println "Tomorrow:  "; datetostr$(tomorrow())

Conversion Functions

Function	Signature	Description
`datetostr$(n)`	`datetostr$@n`	Date number → "yyyy-MM-dd"
`strtodate(s$)`	`strtodate@$`	"yyyy-MM-dd" → date number
`timetostr$(n)`	`timetostr$@n`	Time number → "hh:mm:ss.zzz"
`strtotime(s$)`	`strtotime@$`	"hh:mm:ss" → time number
`datetimetostr$(n)`	`datetimetostr$@n`	DateTime number → string
`strtodatetime(s$)`	`strtodatetime@$`	String → datetime number
`formatdatetime$(fmt$, n)`	`formatdatetime$@$n`	Custom formatted string

╯ plan9basic─◻✕
d = strtodate("2025-12-25")
println "Christmas: "; datetostr$(d)

t = strtotime("09:30:00")
println "Morning: "; timetostr$(t)

dt = strtodatetime("2025-07-04 12:00:00")
println "July 4th noon: "; datetimetostr$(dt)

Date Component Extraction

Function	Signature	Description
`yearof(n)`	`yearof@n`	Year (e.g. 2025)
`monthof(n)`	`monthof@n`	Month (1–12)
`monthoftheyear(n)`	`monthoftheyear@n`	Same as monthof
`dayof(n)`	`dayof@n`	Day of month (1–31)
`dayofthemonth(n)`	`dayofthemonth@n`	Same as dayof
`dayofweek(n)`	`dayofweek@n`	Day of week (1=Sun, 7=Sat)
`dayoftheweek(n)`	`dayoftheweek@n`	Day of week ISO (1=Mon, 7=Sun)
`dayoftheyear(n)`	`dayoftheyear@n`	Day of year (1–366)
`weekof(n)`	`weekof@n`	Week of year (1–53)
`weekoftheyear(n)`	`weekoftheyear@n`	Same as weekof
`weekofthemonth(n)`	`weekofthemonth@n`	Week within month (1–5)

╯ plan9basic─◻✕
dt = now()
println "Year:  "; yearof(dt)
println "Month: "; monthof(dt)
println "Day:   "; dayof(dt)
println "Day of week:  "; dayofweek(dt); " (1=Sun)"
println "Day of week ISO: "; dayoftheweek(dt); " (1=Mon)"
println "Day of year: "; dayoftheyear(dt)
println "Week of year: "; weekof(dt)

ⓘ Note: dayofweek() uses Sunday=1 convention. dayoftheweek() uses ISO standard Monday=1.

Time Component Extraction

Function	Signature	Description
`hourof(n)`	`hourof@n`	Hour (0–23)
`minuteof(n)`	`minuteof@n`	Minute (0–59)
`secondof(n)`	`secondof@n`	Second (0–59)
`millisecondof(n)`	`millisecondof@n`	Millisecond (0–999)

╯ plan9basic─◻✕
dt = now()
println "Hour:   "; hourof(dt)
println "Minute: "; minuteof(dt)
println "Second: "; secondof(dt)
println "Ms:     "; millisecondof(dt)

Date Arithmetic — Differences (Whole Units)

“Between” functions return the number of complete, whole units between two dates.

Function	Signature	Description
`daysbetween(n1, n2)`	`daysbetween@nn`	Whole days between dates
`hoursbetween(n1, n2)`	`hoursbetween@nn`	Whole hours between date/times
`minutesbetween(n1, n2)`	`minutesbetween@nn`	Whole minutes
`secondsbetween(n1, n2)`	`secondsbetween@nn`	Whole seconds
`millisecondsbetween(n1, n2)`	`millisecondsbetween@nn`	Whole milliseconds
`weeksbetween(n1, n2)`	`weeksbetween@nn`	Whole weeks
`monthsbetween(n1, n2)`	`monthsbetween@nn`	Whole months
`yearsbetween(n1, n2)`	`yearsbetween@nn`	Whole years

╯ plan9basic─◻✕
d1 = strtodate("2025-01-01")
d2 = strtodate("2025-01-15")
println "Days: "; daysbetween(d1, d2)      ' 14

dt1 = strtodatetime("2025-01-01 10:00:00")
dt2 = strtodatetime("2025-01-01 14:30:00")
println "Hours: "; hoursbetween(dt1, dt2)  ' 4
println "Seconds: "; secondsbetween(dt1, dt2)  ' 16200

d3 = strtodate("2025-01-01")
d4 = strtodate("2025-01-22")
println "Weeks: "; weeksbetween(d3, d4)    ' 3

Date Arithmetic — Differences (Fractional)

“Span” functions return precise fractional differences (e.g. 4.5 hours instead of 4).

Function	Signature	Description
`dayspan(n1, n2)`	`dayspan@nn`	Fractional days
`hourspan(n1, n2)`	`hourspan@nn`	Fractional hours
`minutespan(n1, n2)`	`minutespan@nn`	Fractional minutes
`secondspan(n1, n2)`	`secondspan@nn`	Fractional seconds
`millisecondspan(n1, n2)`	`millisecondspan@nn`	Fractional milliseconds
`weekspan(n1, n2)`	`weekspan@nn`	Fractional weeks
`monthspan(n1, n2)`	`monthspan@nn`	Fractional months
`yearspan(n1, n2)`	`yearspan@nn`	Fractional years

╯ plan9basic─◻✕
dt1 = strtodatetime("2025-01-01 10:00:00")
dt2 = strtodatetime("2025-01-01 14:30:00")
println "Hour span: "; hourspan(dt1, dt2)    ' 4.5

birthdate = strtodate("1990-06-15")
println "Precise age: "; yearspan(birthdate, today())

ⓘ Note: Use between functions when you need whole units (e.g. “14 days”). Use span functions when you need precision (e.g. “4.5 hours”).

Date Arithmetic — Incrementing

Add or subtract time units. Use negative values to go backwards.

Function	Signature	Description
`incday(n, count)`	`incday@nn`	Add/subtract days
`inchour(n, count)`	`inchour@nn`	Add/subtract hours
`incminute(n, count)`	`incminute@nn`	Add/subtract minutes
`incsecond(n, count)`	`incsecond@nn`	Add/subtract seconds
`incmillisecond(n, count)`	`incmillisecond@nn`	Add/subtract milliseconds
`incweek(n, count)`	`incweek@nn`	Add/subtract weeks
`incyear(n, count)`	`incyear@nn`	Add/subtract years

╯ plan9basic─◻✕
today = today()
println "Today:      "; datetostr$(today)
println "Next week:  "; datetostr$(incday(today, 7))
println "Last week:  "; datetostr$(incday(today, -7))
println "2 weeks:    "; datetostr$(incweek(today, 2))
println "Next year:  "; datetostr$(incyear(today, 1))
println "5 yrs ago:  "; datetostr$(incyear(today, -5))

dt = now()
println "3 hrs later:  "; datetimetostr$(inchour(dt, 3))
println "45 min later: "; datetimetostr$(incminute(dt, 45))

Calendar Information

Function	Signature	Description
`daysinamonth(year, month)`	`daysinamonth@nn`	Days in specific month
`daysinmonth(n)`	`daysinmonth@n`	Days in month of given date
`daysinayear(year)`	`daysinayear@n`	Days in specific year
`daysinyear(n)`	`daysinyear@n`	Days in year of given date
`weeksinayear(year)`	`weeksinayear@n`	Weeks in specific year
`weeksinyear(n)`	`weeksinyear@n`	Weeks in year of given date

╯ plan9basic─◻✕
println "Feb 2024: "; daysinamonth(2024, 2)   ' 29 (leap)
println "Feb 2025: "; daysinamonth(2025, 2)   ' 28
println "Days 2024: "; daysinayear(2024)       ' 366
println "Days 2025: "; daysinayear(2025)       ' 365
println "Weeks 2025: "; weeksinayear(2025)

dt = now()
println "Current month days: "; daysinmonth(dt)
println "Current year days: "; daysinyear(dt)

Boolean Test Functions

All return 1 (true) or 0 (false).

Function	Signature	Description
`isam(n)`	`isam@n`	Is morning? (before noon)
`ispm(n)`	`ispm@n`	Is afternoon/evening? (noon or later)
`isinleapyear(n)`	`isinleapyear@n`	Is date in a leap year?
`istoday(n)`	`istoday@n`	Is the date today?
`issameday(n1, n2)`	`issameday@nn`	Are two date/times on the same day?

╯ plan9basic─◻✕
dt = now()
if isam(dt) then
    println "Good morning!"
else
    println "Good afternoon!"
endif

d = strtodate("2024-06-15")
if isinleapyear(d) then
    println "2024 is a leap year"
endif

dt1 = strtodatetime("2025-01-02 09:00:00")
dt2 = strtodatetime("2025-01-02 18:30:00")
if issameday(dt1, dt2) then
    println "Same calendar day"
endif

Custom Formatting

Function	Signature	Description
`formatdatetime$(fmt$, n)`	`formatdatetime$@$n`	Format with custom pattern

Format Specifiers

Specifier	Description	Example
`yyyy`	4-digit year	2025
`yy`	2-digit year	25
`MM`	2-digit month	01, 12
`M`	Month without leading zero	1, 12
`dd`	2-digit day	01, 31
`d`	Day without leading zero	1, 31
`hh`	2-digit hour (24h)	00, 23
`h`	Hour without leading zero	0, 23
`nn`	2-digit minute	00, 59
`ss`	2-digit second	00, 59
`zzz`	3-digit millisecond	000, 999
`ddd`	Abbreviated day name	Mon, Tue
`dddd`	Full day name	Monday
`MMM`	Abbreviated month name	Jan, Dec
`MMMM`	Full month name	January
`AM/PM`	AM or PM indicator	AM, PM

╯ plan9basic─◻✕
dt = now()

' US format
println formatdatetime$("MM/dd/yyyy", dt)

' European format
println formatdatetime$("dd/MM/yyyy", dt)

' Full date with time
println formatdatetime$("dddd, MMMM d, yyyy 'at' hh:nn AM/PM", dt)

' ISO format
println formatdatetime$("yyyy-MM-dd'T'hh:nn:ss", dt)

' Time only
println formatdatetime$("hh:nn:ss", dt)

⚠ Warning: Syntax is formatdatetime$("format", value) — format string first, then the date/time value. Not format$(value, "format").

Complete Examples

Age Calculator

╯ age_calc.bas─◻✕
' Calculate age from a birthdate
birthdate = strtodate("1971-12-11")
today = today()

years = yearsbetween(birthdate, today)
println "Birthdate: "; datetostr$(birthdate)
println "Today: "; datetostr$(today)
println "Age: "; years; " years"
println "Precise: "; yearspan(birthdate, today); " years"

Working Days Calculator

╯ workdays.bas─◻✕
' Count working days between two dates
function countWorkDays(startDate, endDate) local workDays, currentDate, dow
    workDays = 0
    currentDate = startDate
    
    while currentDate <= endDate
        dow = dayoftheweek(currentDate)
        if dow < 6 then
            workDays = workDays + 1
        endif
        currentDate = incday(currentDate, 1)
    endwhile
    
    return workDays
endfunction

d1 = strtodate("2025-01-01")
d2 = strtodate("2025-01-31")
println "From: "; datetostr$(d1)
println "To: "; datetostr$(d2)
println "Working days: "; countWorkDays(d1, d2)

Leap Year Checker

╯ leapyear.bas─◻✕
' Check leap years for a range
for year = 2020 to 2030
    d = strtodate(str$(year) + "-01-01")
    if isinleapyear(d) = 1 then
        leapStr$ = "YES"
    else
        leapStr$ = "NO"
    endif
    println year; ": Leap? "; leapStr$; " ("; daysinayear(year); " days)"
next

Digital Clock Display

╯ clock.bas─◻✕
' Display current time details
dt = now()

println "Date: "; formatdatetime$("dddd, MMMM d, yyyy", dt)
println ""
println "Time Components:"
println "  Hour:   "; hourof(dt)
println "  Minute: "; minuteof(dt)
println "  Second: "; secondof(dt)
println "  Ms:     "; millisecondof(dt)
println ""

if isam(dt) = 1 then
    println "Period: AM"
else
    println "Period: PM"
endif

println ""
println "Calendar:"
println "  Day of week: "; dayofweek(dt); " (1=Sun)"
println "  Day of year: "; dayoftheyear(dt)
println "  Week of year: "; weekoftheyear(dt)

New Year Countdown

╯ countdown.bas─◻✕
' Countdown to New Year
today = now()
currentYear = yearof(today)
newYear = strtodatetime(str$(currentYear + 1) + "-01-01 00:00:00")

println "Now: "; datetimetostr$(today)
println "New Year: "; datetimetostr$(newYear)

days = daysbetween(today, newYear)
hours = hoursbetween(today, newYear) - (days * 24)

println ""
println "Time until New Year:"
println days; " days, "; hours; " hours"

Quick Reference

Function	Signature	Description
`now() / date() / time()`	`*@`	Current date/time (numeric)
`date$() / time$() / datetime$()`	`*$@`	Current date/time (string)
`today() / yesterday() / tomorrow()`	`*@`	Relative dates
`datetostr$(n) / strtodate(s$)`	`@n/@$`	Date ↔ string
`timetostr$(n) / strtotime(s$)`	`@n/@$`	Time ↔ string
`datetimetostr$(n) / strtodatetime(s$)`	`@n/@$`	DateTime ↔ string
`formatdatetime$(fmt$, n)`	`formatdatetime$@$n`	Custom format
`yearof / monthof / dayof`	`*of@n`	Date components
`dayofweek(n)`	`dayofweek@n`	Day of week (1=Sun)
`dayoftheweek(n)`	`dayoftheweek@n`	Day of week ISO (1=Mon)
`dayoftheyear / weekof`	`*@n`	Calendar position
`hourof / minuteof / secondof / millisecondof`	`*of@n`	Time components
`*between(n1, n2)`	`*between@nn`	8 whole-unit difference functions
`*span(n1, n2)`	`*span@nn`	8 fractional difference functions
`inc*(n, count)`	`inc*@nn`	7 increment functions
`daysinamonth(yr, mo)`	`daysinamonth@nn`	Days in specific month
`daysinayear(yr) / weeksinayear(yr)`	`*@n`	Days/weeks in specific year
`isam / ispm / isinleapyear / istoday`	`*@n`	Boolean tests (1/0)
`issameday(n1, n2)`	`issameday@nn`	Same calendar day?

61 functions across 9 categories.