std/date

Date & Time

The Date class in std/date provides comprehensive tools to capture timestamps, perform calendar arithmetic, format ISO strings, and benchmark execution duration.

Instantiation & Timestamp Parsing

Create current date instances using Date() or Date.now(), initialize from millisecond epochs via Date(timestamp), or parse string representations with Date.parse().

@import("std/date")

// 1. Current timestamp
val now = Date()
println("Current ISO timestamp: " + now.toISOString())

// 2. Parse from date-time string
val releaseDate = Date.parse("2026-10-15 09:00:00")
println("Year: " + releaseDate.year() + ", Month: " + releaseDate.month() + ", Day: " + releaseDate.day())

// 3. Unix epoch milliseconds
val epochMs = Date.currentTimeMillis()
println("Epoch ms: " + epochMs)

Calendar Arithmetic & Comparisons

Adjust intervals using relative addition methods and compare chronological ordering between date objects.

@import("std/date")

val orderDate = Date.now()

// Create independent copy and extend payment deadline by 7 days
val paymentDeadline = orderDate.copy()
paymentDeadline.addDays(7)

// Chronological comparison
val isExpired = Date.now().isAfter(paymentDeadline)
println("Is expired: " + isExpired) // false

// Compute time delta in milliseconds
val diffMs = paymentDeadline.diff(orderDate)
println("Diff ms: " + diffMs)

Date & Time Formatting

Serialize date objects into ISO-8601 strings, discrete date/time components, or custom pattern templates.

@import("std/date")

val eventDate = Date.parse("2026-05-20 14:30:00")

println("Date: " + eventDate.toDateString()) // 2026-05-20
println("Time: " + eventDate.toTimeString()) // 14:30:00
println("ISO: " + eventDate.toISOString())   // 2026-05-20T14:30:00

// Custom pattern formatting
val customFormatted = eventDate.format("%Y/%m/%d")
println("Custom format: " + customFormatted)

Execution Benchmarking with `std/time`

Use the measureTimeMillis function from std/time to accurately measure the execution duration of business logic blocks for resource governance.

@import("std/time")

val elapsed = measureTimeMillis {
    // Simulate measured workload
    sleep(15)
}
println("Elapsed time: " + elapsed + " ms")

Method Reference

Constructors & Static Methods

Date(): Date: Creates a Date instance representing the current moment.
Date(timestampMs: Int): Date: Creates a Date instance from millisecond epoch.
Date.now(): Date: Returns a Date instance representing the current moment.
Date.parse(text: String): Date: Parses a date-time string into a Date object.
Date.currentTimeMillis(): Int: Returns the current Unix epoch in milliseconds.

Date Instance Methods

year(): Int / month(): Int / day(): Int: Retrieves year, month, and day components.
hour(): Int / minute(): Int / second(): Int: Retrieves hour, minute, and second components.
copy(): Date: Creates an independent clone of the instance.
addDays(days: Int) / addHours(hours: Int) / addMinutes(mins: Int): Adjusts date components.
diff(other: Date): Int: Computes difference in milliseconds relative to another Date.
isAfter(other: Date): Bool / isBefore(other: Date): Bool: Compares chronological ordering.
toISOString(): String: Serializes into an ISO 8601 string.
toDateString(): String: Serializes date as YYYY-MM-DD.
toTimeString(): String: Serializes time as HH:MM:SS.
format(pattern: String): String: Formats date using a custom pattern string.