NAME
Sidef::Time::Date - Date and time object with parsing, formatting, arithmetic, and calendar operations.
DESCRIPTION
This class implements date and time manipulation functionality in Sidef. It provides methods for creating, parsing, formatting, and performing arithmetic operations on dates and times. The Date class wraps a Time::Piece object and exposes convenient methods for working with individual date/time components (year, month, day, hour, minute, second), for converting between local time and GMT/UTC, for formatting and parsing dates with strftime/strptime-style patterns, and for comparing and doing arithmetic on dates.
Internally, a Date object stores its value as seconds since the Unix epoch (January 1, 1970, 00:00:00 UTC). Numification (0+) returns this epoch value, and stringification ("") returns the ctime-style representation of the date.
SYNOPSIS
var now = Date() # Current date/time
var now2 = Date.now # Same as above
var epoch = Date(1735084800) # Date from a Unix timestamp
var parsed = Date.parse("2024-12-25", "%Y-%m-%d")
say now.year
say now.ymd
say now.add_days(7)INHERITS
Inherits methods from Sidef::Object::Object.
CONSTRUCTION
new
Date(sec)
Date.new(sec)Creates a new Date object. If sec is given, it is used as the number of seconds since the Unix epoch (a plain number, or anything that stringifies/numifies to one); otherwise, the current time is used.
Aliases: call
call
Date(sec)Allows a Date class to be invoked directly as a function/callable, equivalent to "new".
now
Date.nowReturns a new Date object representing the current date and time.
Aliases: today
today
Date.todayReturns a new Date object representing the current date and time.
Aliases: now
local
self.local(sec)
Date.local(sec)Returns a new Date object for the given number of seconds since the Unix epoch, interpreted in the local timezone. If sec is omitted, the epoch of self is used.
Aliases: localtime
localtime
self.localtime(sec)Returns a new Date object for the given number of seconds since the Unix epoch, interpreted in the local timezone. If sec is omitted, the epoch of self is used.
Aliases: local
gmt
self.gmt(sec)
Date.gmt(sec)Returns a new Date object for the given number of seconds since the Unix epoch, interpreted as GMT/UTC. If sec is omitted, the epoch of self is used.
Aliases: gmtime
gmtime
self.gmtime(sec)Returns a new Date object for the given number of seconds since the Unix epoch, interpreted as GMT/UTC. If sec is omitted, the epoch of self is used.
Aliases: gmt
PARSING AND VALIDATION
parse
Date.parse(string, format)Parses string according to the given strptime-style format and returns a new Date object representing the resulting date/time.
Aliases: strptime
strptime
Date.strptime(string, format)Parses string according to the given strptime-style format and returns a new Date object representing the resulting date/time.
Aliases: parse
valid
self.valid(string, format)Returns true if string is a valid date/time representation according to the given format (i.e., parsing it and re-formatting it with format reproduces string exactly), otherwise returns false. Useful for validating user input before calling "parse".
Aliases: valid_date
valid_date
self.valid_date(string, format)Returns true if string is a valid date/time representation according to the given format, otherwise returns false.
Aliases: valid
COMPONENT ACCESSORS
year
self.yearReturns the four-digit year of the date.
yy
self.yyReturns the two-digit (last two digits) representation of the year (e.g., 24 for 2024).
mon
self.monReturns the month number (1-12), where 1 is January and 12 is December.
Aliases: month
month
self.monthReturns the month number (1-12).
Aliases: mon
day
self.dayReturns the day of the month (1-31).
Aliases: mday, month_day
mday
self.mdayReturns the day of the month (1-31).
Aliases: day, month_day
month_day
self.month_dayReturns the day of the month (1-31).
Aliases: day, mday
hour
self.hourReturns the hour component (0-23).
min
self.minReturns the minute component (0-59).
Aliases: minute
minute
self.minuteReturns the minute component (0-59).
Aliases: min
sec
self.secReturns the seconds component (0-59).
Aliases: second
second
self.secondReturns the seconds component (0-59).
Aliases: sec
epoch
self.epochReturns the Unix epoch time (the number of seconds since January 1, 1970, 00:00:00 UTC) as a number.
wday
self.wdayReturns the day of the week as a number (1-7, where 1 is Sunday and 7 is Saturday, per Time::Piece).
Aliases: week_day
week_day
self.week_dayReturns the day of the week as a number.
Aliases: wday
yday
self.ydayReturns the day of the year (1-366), where January 1 is day 1.
Aliases: year_day
year_day
self.year_dayReturns the day of the year (1-366).
Aliases: yday
isdst
self.isdstReturns true if daylight saving time is in effect for this date, otherwise false.
Aliases: daylight_savings
daylight_savings
self.daylight_savingsReturns true if daylight saving time is in effect for this date, otherwise false.
Aliases: isdst
julian_day
self.julian_dayReturns the Julian Day Number: the continuous count of days since the beginning of the Julian Period (January 1, 4713 BC).
week
self.weekReturns the week number of the year, as computed by Time::Piece.
month_last_day
self.month_last_dayReturns the last day of the month for this date (28, 29, 30, or 31, depending on the month and whether the year is a leap year).
STRING REPRESENTATIONS
monname
self.monnameReturns the abbreviated name of the month (e.g., "Jan", "Feb", "Dec").
fullmonth
self.fullmonthReturns the full name of the month (e.g., "January", "February", "December").
wdayname
self.wdaynameReturns the abbreviated name of the day of the week (e.g., "Mon", "Tue", "Sun").
date
self.dateReturns the date in YYYY-MM-DD format as a string. Equivalent to "ymd" with the default separator.
ymd
self.ymd(sep=nil)Returns the date in year-month-day format as a string (e.g., "2024-12-25"). An optional sep argument overrides the default "-" separator.
mdy
self.mdy(sep=nil)Returns the date in month-day-year format as a string (e.g., "12-25-2024"). An optional sep argument overrides the default "-" separator.
dmy
self.dmy(sep=nil)Returns the date in day-month-year format as a string (e.g., "25-12-2024"). An optional sep argument overrides the default "-" separator.
format
self.format(format)Returns a formatted string representation of the date according to the given strftime-style format string (e.g., "%Y-%m-%d %H:%M:%S").
Aliases: strftime
strftime
self.strftime(format)Returns a formatted string representation of the date according to the given strftime-style format string.
Aliases: format
to_s
self.to_sReturns a string representation of the date in standard ctime format (e.g., "Wed Dec 25 00:00:00 2024").
Aliases: cdate, ctime, to_str
ctime
self.ctimeReturns a string representation of the date in standard ctime format. Also invoked implicitly when a Date object is stringified (e.g., interpolated in a string).
Aliases: cdate, to_s, to_str
cdate
self.cdateReturns a string representation of the date in standard ctime format.
Aliases: ctime, to_s, to_str
to_str
self.to_strReturns a string representation of the date in standard ctime format.
Aliases: cdate, ctime, to_s
dump
self.dumpReturns a debugging string representation of the Date object, showing its underlying epoch value (e.g., "Date(1735084800)").
ARITHMETIC
add_seconds
self.add_seconds(sec)
self + secReturns a new Date object with sec seconds added to it. Accepts both positive and negative values.
Aliases: add, operator +
add
self.add(sec)Returns a new Date object with sec seconds added to it.
Aliases: add_seconds, operator +
add_days
self.add_days(days)Returns a new Date object with days days added to it. Accepts both positive and negative values.
add_months
self.add_months(months)Returns a new Date object with months months added to it. Handles month-end overflow correctly (e.g., adding 1 month to January 31 results in the last day of February).
add_years
self.add_years(years)Returns a new Date object with years years added to it. Preserves the month and day where possible.
subtract
self.subtract(that)
self - thatIf that is another Date object, returns the difference between the two dates, in seconds, as a Number. Otherwise, that is treated as a number of seconds, and a new Date object with that many seconds subtracted is returned.
Aliases: sub, operator -
sub
self.sub(that)If that is another Date object, returns the difference between the two dates in seconds. Otherwise, returns a new Date object with that seconds subtracted.
Aliases: subtract, operator -
TRUNCATION
truncate_to_year
self.truncate_to_yearReturns a new Date object truncated to January 1st of the current year, at midnight.
truncate_to_quarter
self.truncate_to_quarterReturns a new Date object truncated to the first day of the current quarter (January 1, April 1, July 1, or October 1), at midnight.
truncate_to_month
self.truncate_to_monthReturns a new Date object truncated to the first day of the current month, at midnight.
truncate_to_day
self.truncate_to_dayReturns a new Date object with the time-of-day components (hour, minute, second) set to zero, keeping only the date portion.
truncate_to_hour
self.truncate_to_hourReturns a new Date object with the minutes and seconds set to zero, preserving the date and hour.
truncate_to_minute
self.truncate_to_minuteReturns a new Date object with the seconds set to zero, preserving the date, hour, and minute.
truncate_to_second
self.truncate_to_secondReturns a new Date object truncated to whole-second precision (a no-op for this class, since Date objects already have second precision).
COMPARISON
cmp
self.cmp(that)
self <=> thatPerforms a three-way comparison between two dates (by epoch value), returning -1, 0, or 1 depending on whether self is earlier than, equal to, or later than that.
Aliases: operator <=>
eq
self.eq(that)
self == thatReturns true if self and that represent the same moment in time, otherwise false.
Aliases: operator ==
ne
self.ne(that)
self != thatReturns true if self and that do not represent the same moment in time, otherwise false.
Aliases: operator !=
lt
self.lt(that)
self < thatReturns true if self is chronologically earlier than that, otherwise false.
Aliases: operator <
le
self.le(that)
self <= thatReturns true if self is earlier than or equal to that, otherwise false.
Aliases: operator <=
gt
self.gt(that)
self > thatReturns true if self is chronologically later than that, otherwise false.
Aliases: operator >
ge
self.ge(that)
self >= thatReturns true if self is later than or equal to that, otherwise false.
Aliases: operator >=
CONVERSION
time
self.timeReturns a Sidef::Time::Time object constructed from the epoch of this Date.
OVERLOADED OPERATORS
Date objects overload the following Perl operators:
"" ctime # stringification
0+ epoch # numification
bool true if defined # boolean context
+ add_seconds
- subtract
<=> cmp
== eq
!= ne
< lt
<= le
> gt
>= geEXAMPLES
# Create a date object
var now = Date.now
say(now.year) # Current year
say(now.month) # Current month
say(now.day) # Current day
# Format dates
say(now.format("%Y-%m-%d %H:%M:%S"))
say(now.ymd) # ISO date format
say(now.dmy) # Day-Month-Year
# Date arithmetic
var tomorrow = now.add_days(1)
var next_month = now.add_months(1)
var last_year = now.add_years(-1)
# Parse and validate dates
var date = Date.parse("2024-12-25", "%Y-%m-%d")
say(date.wdayname) # Day of week name
say(Date.valid("2024-12-25", "%Y-%m-%d")) # true
# Compare dates
if (date1 < date2) {
say("date1 is earlier")
}
# Difference between two dates, in seconds
say(date2 - date1)
# Truncate dates
var start_of_day = now.truncate_to_day
var start_of_month = now.truncate_to_month