view release on metacpan or  search on metacpan

lib/Date/Gregorian.pm  view on Meta::CPAN

Week numbers range from 1 to 53 (max).

=head2 check_ywd

I<check_ywd> checks a given combination of year, week in year and
weekday for validity.  Given a valid date, the object is updated
and the object itself is returned, evaluating to true in boolean
context.  Otherwise, the object remains untouched and B<undef> is
returned.

Note that year 1582 (or whatever year was configured to have the
Gregorian calendar reformation) was considerably shorter than a
normal year.  Such a year has some invalid dates that otherwise
might seem utterly inconspicuos.

=head2 add_days

I<add_days> increases, or, given a negative argument, decreases, a
date by a number of days.  Its new value represents a day that many
days later in history if a positive number of days was added.  Adding
a negative number of days consequently shifts a date back towards
the past.

=head2 get_days_since

I<get_days_since> computes the difference of two dates as a number
of days.  The result is positive if the given date is an earlier
date than the one whose method is called, negative if it is a later
one.  Look at it as a subtraction operation, yielding a positive
result if something smaller is subtracted from something larger,
"smaller" meaning "earlier" in this context.

=head2 get_days_until

I<get_days_until> computes the same value as I<get_days_since>,
only with opposite sign.

=head2 compare

I<compare> compares two dates chronologically.  Result is zero
if the dates refer to the same day, -1 if the method invocant
refers to an earlier day than the parameter and 1 otherwise.

=head2 iterate_days_upto iterate_days_downto

I<iterate_days_upto> and I<iterate_days_downto> provide convenient
methods to iterate over a range of dates.  They return a reference
to a subroutine that can be called without argument in a while
condition to set the given date iteratively to each one of a sequence
of dates.  The current date is always the first one to be visited
(unless the sequence is all empty).  The limit parameter determines
the end of the sequence, together with the relation parameter:  '<'
excludes the upper limit from the sequence, '<=' includes the upper
limit, '>=' includes the lower limit and '>' excludes the lower
limit.  The step parameter is optional.  It must be greater than
zero and defines how many days the dates in the sequence lie apart.
It defaults to one.

Each iterator maintains its own state; therefore it is legal to run
more than one iterator in parallel or even create new iterators
within iterations.

=head2 set_easter

I<set_easter> computes the date of Easter sunday of a given year,
taking into account how the date object was configured.

=head2 set_weekday

I<set_weekday> computes a date matching a given weekday that is
close to the date it is applied to.  The optional relation parameter
may be one of '>=', '>', '<=' or '<', and determines if the resulting
date should be "equal or later", later, "equal or earlier", or
earlier, respectively, than the initial date.  Default is '>='.

=head2 set_today

I<set_today> computes a date value equivalent to the system's notion
of the current date in the local timezone.  System time is assumed
to run in Gregorian mode.

=head2 set_localtime

I<set_localtime> likewise computes a date value equivalent to a
given arbitrary time value in the local timezone.

=head2 set_gmtime

I<set_gmtime> computes a date value equivalent to a given time value
in the "GMT" system timezone.  This timezone represents a time scale
counting a constant number of seconds per day since an OS- and
implementation dependent starting point -- the epoch -- and not
counting leap seconds.  This makes arithmetic on timestamps easy
but forces clocks to be frequently adjusted to the earth rotation.
On POSIX-like systems this timezone is used for timestamps.
On systems using the gmtime call in any other fashion I<set_gmtime>
and I<get_gmtime> are not guaranteed to comply with it.

=head2 get_gmtime

I<get_gmtime> converts a date value back to a timestamp in the "GMT"
timezone explained above.  This method may return undef if the date
seems to be out of range.  Note that the precision of timestamps
represented by Date::Gregorian objects is normally limited to days.
Thus, converting a timestamp to a date and back again usually
truncates the timestamp to midnight.  Extension classes may behave
differently, however.

=head2 get_localtime

I<get_localtime> converts a date value back to a system timestamp
in the current local timezone.  Undef is returned if the date seems
to be out of range.  As with I<get_gmtime>, the precision is normally
limited to days.  However, values returned by I<get_localtime> for
successive days need not follow a simple arithmetic progression,
as they interpolate actual localtime calls, and the local timezone
may incorporate oddities like daylight saving time changes.

Note also that timestamps are not portable.  While the conversion
functions described here make an effort to cover the local clock
behaviour, mostly in order to make set_today work, they depend on