=encoding utf8

=head1 NAME

Sidef::Time::Date

=head1 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.

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

=head1 INHERITS

Inherits methods from:

       * Sidef::Object::Object

=head1 METHODS

=head2 !=

    a != b

Returns true if two dates are not equal, false otherwise. Compares the date/time values to determine inequality.

Aliases: I<ne>

=cut

=head2 +

    a + b

Returns a new Date object with the specified number of seconds added to the current date. The parameter C<b> should be a numeric value representing seconds.

Aliases: I<add>, I<add_seconds>

=cut

=head2 -

    a - b

Returns a new Date object with the specified number of seconds subtracted from the current date, or the difference in seconds between two dates if C<b> is a Date object.

Aliases: I<sub>, I<subtract>

=cut

=head2 <

    a < b

Returns true if date C<a> is earlier than date C<b>, false otherwise. Performs chronological comparison.

Aliases: I<lt>

=cut

=head2 <=

    a <= b

Returns true if date C<a> is earlier than or equal to date C<b>, false otherwise.

Aliases: I<le>

=cut

=head2 <=>

    a <=> b

Returns -1 if C<a> is earlier than C<b>, 0 if they are equal, or 1 if C<a> is later than C<b>. Standard three-way comparison operator.

Aliases: I<cmp>

=cut

=head2 ==

    a == b

Returns true if two dates represent the same moment in time, false otherwise.

Aliases: I<eq>

=cut

=head2 >

    a > b

Returns true if date C<a> is later than date C<b>, false otherwise.

Aliases: I<gt>

=cut

=head2 >=

    a >= b

Returns true if date C<a> is later than or equal to date C<b>, false otherwise.

Aliases: I<ge>

=cut

=head2 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.

=cut

=head2 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).

=cut

=head2 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.

=cut

=head2 call

    self.call

Returns the current date/time as a new Date object. Allows Date to be called as a function.

=cut

=head2 date

    self.date

Returns the date portion of the Date object, typically as a formatted string or date-only representation.

=cut

=head2 day

    self.day

Returns the day of the month (1-31) for the current Date object.

Aliases: I<mday>, I<month_day>

=cut

=head2 dmy

    self.dmy

Returns the date in day-month-year format as a string (e.g., "25-12-2024").

=cut

=head2 dump

    self.dump

Returns a string representation of the Date object suitable for debugging, showing its internal structure.

=cut

=head2 epoch

    self.epoch

Returns the Unix epoch time (number of seconds since January 1, 1970, 00:00:00 UTC) as a number.

=cut

=head2 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: I<strftime>

=cut

=head2 fullmonth

    self.fullmonth

Returns the full name of the month (e.g., "January", "February", "December").

=cut

=head2 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: I<gmtime>

=cut

=head2 hour

    self.hour

Returns the hour component (0-23) of the Date object.

=cut

=head2 isdst

    self.isdst

Returns true if daylight saving time is in effect for this date, false otherwise.

Aliases: I<daylight_savings>

=cut

=head2 julian_day

    self.julian_day

Returns the Julian Day Number, which is the continuous count of days since the beginning of the Julian Period (January 1, 4713 BC).

=cut

=head2 local

    self.local(sec)

Returns a new Date object representing the specified number of seconds since the Unix epoch, interpreted as local time.

Aliases: I<localtime>

=cut

=head2 mdy

    self.mdy

Returns the date in month-day-year format as a string (e.g., "12-25-2024").

=cut

=head2 min

    self.min

Returns the minute component (0-59) of the Date object.

Aliases: I<minute>

=cut

=head2 mon

    self.mon

Returns the month number (1-12) of the Date object, where 1 is January and 12 is December.

Aliases: I<month>

=cut

=head2 monname

    self.monname

Returns the abbreviated name of the month (e.g., "Jan", "Feb", "Dec").

=cut

=head2 month_last_day

    self.month_last_day

Returns the last day of the month for the current Date object (e.g., 28, 29, 30, or 31 depending on the month and year).

=cut

=head2 now

    self.now

Returns a new Date object representing the current date and time.

Aliases: I<today>

=cut

=head2 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: I<strptime>

=cut

=head2 sec

    self.sec

Returns the seconds component (0-59) of the Date object.

Aliases: I<second>

=cut

=head2 time

    self.time

Returns the time portion of the Date object as a formatted string or time representation.

=cut

=head2 to_s

    self.to_s

Returns a string representation of the Date object in a standard format (typically "Day Mon DD HH:MM:SS YYYY").

Aliases: I<cdate>, I<ctime>, I<to_str>

=cut

=head2 truncate_to_day

    self.truncate_to_day

Returns a new Date object with the time components (hours, minutes, seconds) set to zero, keeping only the date portion.

=cut

=head2 truncate_to_hour

    self.truncate_to_hour

Returns a new Date object with the minutes and seconds set to zero, preserving the date and hour.

=cut

=head2 truncate_to_minute

    self.truncate_to_minute

Returns a new Date object with the seconds set to zero, preserving the date, hour, and minute.

=cut

=head2 truncate_to_month

    self.truncate_to_month

Returns a new Date object truncated to the first day of the month at midnight (day set to 1, time components set to zero).

=cut

=head2 truncate_to_quarter

    self.truncate_to_quarter

Returns a new Date object truncated to the first day of the quarter (January 1, April 1, July 1, or October 1) at midnight.

=cut

=head2 truncate_to_second

    self.truncate_to_second

Returns a new Date object with subsecond precision removed (if any), keeping only whole seconds.

=cut

=head2 truncate_to_year

    self.truncate_to_year

Returns a new Date object truncated to January 1 of the current year at midnight.

=cut

=head2 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: I<valid_date>

=cut

=head2 wday

    self.wday

Returns the day of the week (0-6) where 0 is Sunday and 6 is Saturday.

Aliases: I<week_day>

=cut

=head2 wdayname

    self.wdayname

Returns the name of the day of the week (e.g., "Monday", "Tuesday", "Sunday").

=cut

=head2 week

    self.week

Returns the week number of the year (typically 1-53) according to ISO 8601 or similar week numbering system.

=cut

=head2 yday

    self.yday

Returns the day of the year (1-366), where January 1 is day 1.

Aliases: I<year_day>

=cut

=head2 year

    self.year

Returns the four-digit year of the Date object.

=cut

=head2 ymd

    self.ymd

Returns the date in year-month-day format as a string (e.g., "2024-12-25").

=cut

=head2 yy

    self.yy

Returns the two-digit year representation (e.g., "24" for 2024).

=cut

=head1 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

=head1 SEE ALSO

L<Sidef::Object::Object>

=cut
