DateTime - Soli MVC Documentation

Static Methods

DateTime.now()

Get the current local date and time.

Returns

DateTime - A DateTime instance representing the current local time

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

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

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

DateTime.epoch()

Create a DateTime at Unix epoch (1970-01-01 00:00:00 UTC).

Returns

DateTime - A DateTime instance at epoch

epoch = DateTime.epoch()
println(epoch.year())  # 1970

DateTime.from_unix(timestamp)

Create a DateTime from a Unix timestamp (seconds since epoch).

Parameters

timestamp : Int - Unix timestamp in seconds

Returns

DateTime - A DateTime instance

dt = DateTime.from_unix(1704067200)
println(dt.to_iso())  # "2024-01-01T00:00:00Z"

DateTime.microtime()

Get the current Unix timestamp in microseconds as a Float.

Returns

Float - Microseconds since epoch

mt = DateTime.microtime()
println(mt)  # 1712832000000000.0

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")

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

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

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

.format(pattern, locale?)

Format the date/time using strftime pattern specifiers, with optional locale for internationalized month and day names.

Parameters

pattern : String - strftime format pattern

locale : String? - Optional locale code ("en", "fr", "es", "de", "it", "pt"). Defaults to "en"

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 (localized)

%A - Weekday name (localized)

%b - Abbreviated month (localized)

%a - Abbreviated weekday (localized)

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"

Locale Examples

dt = DateTime.parse("2024-03-06T14:30:00Z")

# French
dt.format("%A %d %B %Y", "fr")   # "mercredi 06 mars 2024"
dt.format("%d %b %Y", "fr")      # "06 mars 2024"

# Spanish
dt.format("%A %d %B %Y", "es")   # "miércoles 06 marzo 2024"

# Without locale or with "en" - English (default)
dt.format("%A %d %B %Y")         # "Wednesday 06 March 2024"
dt.format("%A %d %B %Y", "en")   # "Wednesday 06 March 2024"

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

today = DateTime.now
tomorrow = today.add_days(1)
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

now = DateTime.now
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

today = DateTime.now
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

today = DateTime.now
next_month = today.add_months(1)
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

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

Boundaries

.beginning_of_minute()

Truncate seconds and sub-seconds to zero, keeping the same minute.

Returns

DateTime - A new DateTime instance

.end_of_minute()

Set seconds to 59 and milliseconds to 999, keeping the same minute.

Returns

DateTime - A new DateTime instance

.beginning_of_hour()

Set minutes, seconds, and sub-seconds to zero, keeping the same hour.

Returns

DateTime - A new DateTime instance

.end_of_hour()

Set minutes to 59, seconds to 59, and milliseconds to 999, keeping the same hour.

Returns

DateTime - A new DateTime instance

.beginning_of_day()

Set hours, minutes, seconds, and sub-seconds to zero, keeping the same day.

Returns

DateTime - A new DateTime instance

.end_of_day()

Set the time to 23:59:59.999, keeping the same day.

Returns

DateTime - A new DateTime instance

.beginning_of_month()

Set the day to 1 and time to 00:00:00.000, keeping the same month and year.

Returns

DateTime - A new DateTime instance

dt = DateTime.parse("2024-06-15T10:30:45Z")
dt.beginning_of_month().day()    # 1
dt.beginning_of_month().hour()   # 0

.end_of_month()

Set the date to the last day of the month and time to 23:59:59.999, keeping the same month and year.

Returns

DateTime - A new DateTime instance

dt = DateTime.parse("2024-06-15T10:30:45Z")
dt.end_of_month().day()    # 30
dt.end_of_month().hour()   # 23

.beginning_of_year()

Set the date to January 1st and time to 00:00:00.000, keeping the same year.

Returns

DateTime - A new DateTime instance

.end_of_year()

Set the date to December 31st and time to 23:59:59.999, keeping the same year.

Returns

DateTime - A new DateTime instance

Comparison

Two DateTime instances can be compared with the standard operators (<, <=, >, >=, ==, !=). Comparison is by absolute instant — equality holds when both refer to the same moment, regardless of which DateTime object you're holding.

let a = DateTime.from_unix(1700000000)
let b = DateTime.from_unix(1700000000)
let later = a.add_hours(1)

a == b       # true — same instant, different instances
a < later    # true
later >= a   # true

Complete Example

# Get current date/time
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"))

# Format with locale for I18n
println(now.format("%A %d %B %Y", "fr"))  # "lundi 15 janvier 2024"
println(now.format("%A %d %B %Y", "es"))  # "lunes 15 enero 2024"

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

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