NAME
Sidef::Time::Date
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 time values and provides convenient methods for working with various date components like year, month, day, hour, minute, and second.
SYNOPSIS
var obj = Date() # Current date/time
var date = Date(2024, 12, 25) # Specific date
var parsed = Date.parse("2024-12-25", "%Y-%m-%d")INHERITS
Inherits methods from:
* Sidef::Object::ObjectMETHODS
!=
a != bReturns true if two dates are not equal, false otherwise. Compares the date/time values to determine inequality.
Aliases: ne
+
a + bReturns a new Date object with the specified number of seconds added to the current date. The parameter b should be a numeric value representing seconds.
Aliases: add, add_seconds
-
a - bReturns a new Date object with the specified number of seconds subtracted from the current date, or the difference in seconds between two dates if b is a Date object.
Aliases: sub, subtract
<
a < bReturns true if date a is earlier than date b, false otherwise. Performs chronological comparison.
Aliases: lt
<=
a <= bReturns true if date a is earlier than or equal to date b, false otherwise.
Aliases: le
<=>
a <=> bReturns -1 if a is earlier than b, 0 if they are equal, or 1 if a is later than b. Standard three-way comparison operator.
Aliases: cmp
==
a == bReturns true if two dates represent the same moment in time, false otherwise.
Aliases: eq
>
a > bReturns true if date a is later than date b, false otherwise.
Aliases: gt
>=
a >= bReturns true if date a is later than or equal to date b, false otherwise.
Aliases: ge
add_days
self.add_days(days)Returns a new Date object with the specified number of days added to the current date. Accepts both positive and negative values.
add_months
self.add_months(months)Returns a new Date object with the specified number of months added to the current date. Handles month overflow correctly (e.g., adding 1 month to January 31 results in February 28/29).
add_years
self.add_years(years)Returns a new Date object with the specified number of years added to the current date. Preserves the month and day where possible.
call
self.callReturns the current date/time as a new Date object. Allows Date to be called as a function.
date
self.dateReturns the date portion of the Date object, typically as a formatted string or date-only representation.
day
self.dayReturns the day of the month (1-31) for the current Date object.
Aliases: mday, month_day
dmy
self.dmyReturns the date in day-month-year format as a string (e.g., "25-12-2024").
dump
self.dumpReturns a string representation of the Date object suitable for debugging, showing its internal structure.
epoch
self.epochReturns the Unix epoch time (number of seconds since January 1, 1970, 00:00:00 UTC) as a number.
format
self.format(format)Returns a formatted string representation of the date according to the specified format string. Uses strftime-style format specifiers (e.g., "%Y-%m-%d %H:%M:%S").
Aliases: strftime
fullmonth
self.fullmonthReturns the full name of the month (e.g., "January", "February", "December").
gmt
self.gmt(sec)Returns a new Date object representing the specified number of seconds since the Unix epoch, interpreted as GMT/UTC time.
Aliases: gmtime
hour
self.hourReturns the hour component (0-23) of the Date object.
isdst
self.isdstReturns true if daylight saving time is in effect for this date, false otherwise.
Aliases: daylight_savings
julian_day
self.julian_dayReturns the Julian Day Number, which is the continuous count of days since the beginning of the Julian Period (January 1, 4713 BC).
local
self.local(sec)Returns a new Date object representing the specified number of seconds since the Unix epoch, interpreted as local time.
Aliases: localtime
mdy
self.mdyReturns the date in month-day-year format as a string (e.g., "12-25-2024").
min
self.minReturns the minute component (0-59) of the Date object.
Aliases: minute
mon
self.monReturns the month number (1-12) of the Date object, where 1 is January and 12 is December.
Aliases: month
monname
self.monnameReturns the abbreviated name of the month (e.g., "Jan", "Feb", "Dec").
month_last_day
self.month_last_dayReturns the last day of the month for the current Date object (e.g., 28, 29, 30, or 31 depending on the month and year).
now
self.nowReturns a new Date object representing the current date and time.
Aliases: today
parse
self.parse(string, format)Returns a new Date object by parsing the given string according to the specified format. Uses strptime-style format specifiers.
Aliases: strptime
sec
self.secReturns the seconds component (0-59) of the Date object.
Aliases: second
time
self.timeReturns the time portion of the Date object as a formatted string or time representation.
to_s
self.to_sReturns a string representation of the Date object in a standard format (typically "Day Mon DD HH:MM:SS YYYY").
Aliases: cdate, ctime, to_str
truncate_to_day
self.truncate_to_dayReturns a new Date object with the time components (hours, minutes, seconds) 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_month
self.truncate_to_monthReturns a new Date object truncated to the first day of the month at midnight (day set to 1, time components set to zero).
truncate_to_quarter
self.truncate_to_quarterReturns a new Date object truncated to the first day of the quarter (January 1, April 1, July 1, or October 1) at midnight.
truncate_to_second
self.truncate_to_secondReturns a new Date object with subsecond precision removed (if any), keeping only whole seconds.
truncate_to_year
self.truncate_to_yearReturns a new Date object truncated to January 1 of the current year at midnight.
valid
self.valid(string, format)Returns true if the given string represents a valid date according to the specified format, false otherwise. Useful for validation before parsing.
Aliases: valid_date
wday
self.wdayReturns the day of the week (0-6) where 0 is Sunday and 6 is Saturday.
Aliases: week_day
wdayname
self.wdaynameReturns the name of the day of the week (e.g., "Monday", "Tuesday", "Sunday").
week
self.weekReturns the week number of the year (typically 1-53) according to ISO 8601 or similar week numbering system.
yday
self.ydayReturns the day of the year (1-366), where January 1 is day 1.
Aliases: year_day
year
self.yearReturns the four-digit year of the Date object.
ymd
self.ymdReturns the date in year-month-day format as a string (e.g., "2024-12-25").
yy
self.yyReturns the two-digit year representation (e.g., "24" for 2024).
EXAMPLES
# 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 dates
var date = Date.parse("2024-12-25", "%Y-%m-%d")
say date.wdayname # Day of week name
# Compare dates
if (date1 < date2) {
say "date1 is earlier"
}
# Truncate dates
var start_of_day = now.truncate_to_day
var start_of_month = now.truncate_to_month