DateTime

Date and time manipulation with a clean, object-oriented API.

The DateTime class provides a convenient way to work with dates and times. Create instances using static methods, then use instance methods to extract components or perform arithmetic.

Static Methods

DateTime.now()

Get the current local date and time.

Returns

DateTime - A DateTime instance representing the current local time

let now = DateTime.now
println(now.to_iso())  # "2024-01-15T10:30:00"

DateTime.utc()

Get the current UTC date and time.

Returns

DateTime - A DateTime instance representing the current UTC time

let utc = DateTime.utc
println(utc.to_iso())  # "2024-01-15T15:30:00Z"

DateTime.parse(string)

Parse a date/time string in ISO 8601 or RFC format.

Parameters

string : String - The date string to parse

Returns

DateTime - A DateTime instance

let dt = DateTime.parse("2024-01-15T10:30:00Z")
let date_only = DateTime.parse("2024-01-15")

Date Components

.year()

Get the year component (e.g., 2024).

Returns

Int - The year

.month()

Get the month component (1-12).

Returns

Int - The month (1 = January, 12 = December)

.day()

Get the day of month (1-31).

Returns

Int - The day of the month

.hour()

Get the hour component (0-23).

Returns

Int - The hour in 24-hour format

.minute()

Get the minute component (0-59).

Returns

Int - The minute

.second()

Get the second component (0-59).

Returns

Int - The second

.weekday()

Get the day of the week as a string.

Returns

String - The weekday name (e.g., "monday", "tuesday")

let dt = DateTime.parse("2024-01-15")
println(dt.weekday())  # "monday"

Formatting

.to_unix()

Get the Unix timestamp (seconds since epoch).

Returns

Int - Unix timestamp in seconds

let dt = DateTime.now
println(dt.to_unix())  # 1705315800

.to_iso()

Get the date/time as an ISO 8601 string.

Returns

String - ISO 8601 formatted string

let dt = DateTime.now
println(dt.to_iso())  # "2024-01-15T10:30:00"

.format(pattern)

Format the date/time using strftime pattern specifiers.

Parameters

pattern : String - strftime format pattern

Common Format Specifiers

%Y - Year (4 digits)

%m - Month (01-12)

%d - Day (01-31)

%H - Hour (00-23)

%M - Minute (00-59)

%S - Second (00-59)

%B - Month name

%A - Weekday name

let dt = DateTime.parse("2024-01-15T10:30:00")
dt.format("%Y-%m-%d %H:%M:%S")  # "2024-01-15 10:30:00"
dt.format("%B %d, %Y")           # "January 15, 2024"
dt.format("%A")                  # "Monday"

Arithmetic

.add_days(n)

Add days to the date. Use negative values to subtract.

Parameters

n : Int - Number of days to add

Returns

DateTime - A new DateTime instance

let today = DateTime.now
let tomorrow = today.add_days(1)
let yesterday = today.add_days(-1)

.add_hours(n)

Add hours to the date/time. Use negative values to subtract.

Parameters

n : Int - Number of hours to add

Returns

DateTime - A new DateTime instance

let now = DateTime.now
let in_two_hours = now.add_hours(2)

.add_weeks(n)

Add weeks to the date. Use negative values to subtract.

Parameters

n : Int - Number of weeks to add

Returns

DateTime - A new DateTime instance

let today = DateTime.now
let next_week = today.add_weeks(1)

.add_months(n)

Add months to the date. Use negative values to subtract.

Parameters

n : Int - Number of months to add

Returns

DateTime - A new DateTime instance

let today = DateTime.now
let next_month = today.add_months(1)
let last_quarter = today.add_months(-3)

.add_years(n)

Add years to the date. Use negative values to subtract.

Parameters

n : Int - Number of years to add

Returns

DateTime - A new DateTime instance

let today = DateTime.now
let next_year = today.add_years(1)

Complete Example

# Get current date/time
let now = DateTime.now
println("Current time: " + now.to_iso())

# Extract components
println("Year: " + now.year())
println("Month: " + now.month())
println("Day: " + now.day())
println("Weekday: " + now.weekday())

# Format output
println(now.format("%B %d, %Y at %H:%M"))

# Date arithmetic
let next_week = now.add_weeks(1)
let last_month = now.add_months(-1)

# Parse a date string
let birthday = DateTime.parse("1990-06-15")
println("Birthday was on a " + birthday.weekday())

Env Functions Duration