datetime

Previous Next

This module contains high-level date and time manipulation utilities, extending the core std:time module with object-oriented representations.

Include using

var datetime = use("lib:datetime");

now

now()

Returns a DateTime instance representing the current local date and time.

  • Parameters: None
  • Returns: (DateTime) A DateTime object initialized with the current system time.
var datetime = use("lib:datetime");

var current = datetime.now();
echo current; // e.g. "2023-10-27 14:30:00"

from_timestamp

from_timestamp(timestamp)

Constructs a DateTime object from a numeric Unix timestamp. Throws a ValueError if the timestamp is negative.

  • Parameters:
    • timestamp (Number): The numeric Unix epoch timestamp (seconds since 1970-01-01).
  • Returns: (DateTime) A new DateTime instance.
var datetime = use("lib:datetime");

var dt = datetime.from_timestamp(1698417000.0);
echo dt.year; // 2023

TimeDelta (Class)

Represents a duration or difference between two dates.

Constructor

TimeDelta(days = 0, hours = 0, minutes = 0, seconds = 0)

Constructs a TimeDelta instance.

var datetime = use("lib:datetime");

var delta = datetime.TimeDelta(days = 7, hours = 2);
echo delta.total_seconds(); // 612000

total_seconds

total_seconds()

Returns the total duration converted into seconds.

  • Returns: (Number) Total duration in seconds.

DateTime (Class)

The primary class representing a calendar date and time. Throws ValueError if component values (month, day, hour, minute, second) are out of valid bounds.

Constructor

DateTime(year, month = 1, day = 1, hour = 0, minute = 0, second = 0)

Constructs a new DateTime instance.

  • Parameters:
    • year (Number): The calendar year.
    • month (Number, optional): Month (1-12). Defaults to 1.
    • day (Number, optional): Day of month (1-31). Defaults to 1.
    • hour (Number, optional): Hour (0-23). Defaults to 0.
    • minute (Number, optional): Minute (0-59). Defaults to 0.
    • second (Number, optional): Second (0-59). Defaults to 0.
var datetime = use("lib:datetime");

var start_of_year = datetime.DateTime(2024);
echo start_of_year; // "2024-01-01 00:00:00"

is_leap_year

is_leap_year()

Checks if the DateTime instance falls within a leap year.

  • Returns: (Bool) true if a leap year, otherwise false.
var datetime = use("lib:datetime");

var dt = datetime.DateTime(2024, 2, 29);
echo dt.is_leap_year(); // true

add

__add__(timedelta)

Overloads the binary + operator to return a new DateTime instance shifted by a TimeDelta duration. Throws TypeError if operand is not a TimeDelta.

  • Parameters:
    • timedelta (TimeDelta): A TimeDelta instance specifying the shift.
  • Returns: (DateTime) A recalculated DateTime instance.
var datetime = use("lib:datetime");

var now = datetime.now();
var delta = datetime.TimeDelta(days = 7);

var next_week = now + delta; // Overloaded + operator
echo next_week;

str

__str__()

Returns the standard string representation formatted as "%Y-%m-%d %H:%M:%S".

  • Returns: (String) The formatted string.
var datetime = use("lib:datetime");

var dt = datetime.DateTime(2024, month = 5, day = 15, hour = 9);
echo dt; // "2024-05-15 09:00:00"
lib modules math