view release on metacpan or  search on metacpan

lib/Date/Calc/Object.pod  view on Meta::CPAN

flag only has effect when "accurate mode" is switched off.

Both flags can be set and reset independently from each other,
however.

Therefore, at startup, you can for instance switch "normalized
mode" on, without having any immediate effect, and switch off
"accurate mode" later, which instantly also causes "normalized
mode" to spring into effect.

Because years and months have varying lengths in terms of days,
the "YMD" and "N_YMD" modes are less accurate than "accurate mode",
because these modes depend on the context of the two dates of which
the delta vector is the difference. Added to a different date, a
delta vector calculated in "YMD mode" or "N_YMD mode" may yield
a different offset in terms of days, i.e., the final result may
sometimes vary seemingly unpredictably (or in other situations
may give you the expected result, at the expense of actually
representing a varying difference in days, determined exclusively
by context).

Beware also that - for the same reason - the absolute value
("C<abs()>") of a delta vector returns a fictitious number
of days if the delta vector contains non-zero values for
"year" and/or "month" (see also the next section "Absolute
Value" below for more details).

Example:

The difference between C<[2000,1,1]> and C<[2000,3,1]> is
C<[+0 +0 +60]> in "accurate mode" and C<[+0 +2 +0]> in "YMD
mode" (in this "benign" example, the result is the same in
"YMD mode" and in "N_YMD mode").

When added to the date C<[2000,4,1]>, the "accurate" delta
vector yields the date C<[2000,5,31]>, whereas the "YMD mode"
delta vector yields the date C<[2000,6,1]> (which is actually
a difference of 61 days).

Moreover, when added to the date C<[1999,1,1]>, the "accurate"
delta vector yields the date C<[1999,3,2]>, whereas the "inaccurate"
"YMD Mode" delta vector yields the date C<[1999,3,1]> (which is
actually a difference of 59 days).

Depending on what you want, either mode may suit you better.

=item *

Absolute Value

Note that "C<abs($date)>" and "C<abs($delta)>" are just shorthands
for "C<$date-E<gt>number()>" and "C<$delta-E<gt>number()>".

The operator "C<abs()>", when applied to a date or delta vector,
returns the corresponding number of days (see below for an exception
to this), with the time part (if available) represented by a fraction
after the decimal point.

In the case of dates, the absolute value (to the left of the
decimal point) is the number of days since the 1st of January
S<1 A.D.> (by extrapolating the Gregorian calendar back beyond
its "natural" limit of 1582 A.D.) B<PLUS ONE>.

(I.e., the absolute value of the 1st of January 1 A.D. is 1.)

Exception:

If the "NUMBER" or "number_format()" is set to 0 (the default
setting), the absolute value of a date to the left of the decimal
point is "yyyymmdd", i.e., the number in which the uppermost four
digits correspond to the year, the next lower two digits to the
month and the lowermost two digits to the day.

In the case of delta vectors, the absolute value (to the left
of the decimal point) is simply the difference in days (but
see also below).

Note that the absolute value of a delta vector can be negative!

If you want a positive value in all cases, apply the "C<abs()>"
operator again, i.e., "C<$posdiff = abs(abs($delta));>".

If the delta vector contains non-zero values for "year" and/or
"month" (see also the discussion of "Accurate Mode" in the section
above), an exact representation in days cannot be calculated,
because years and months do not have fixed equivalents in days.

If nevertheless you attempt to calculate the absolute value of
such a delta vector, a fictitious value is returned, which is
calculated by simply multiplying the year difference with 12,
adding the month difference, multiplying this sum with 31 and
finally adding the day difference.

Beware that because of this, the absolute values of delta
vectors are not necessarily contiguous.

Moreover, since there is more than one way to express the
difference between two dates, comparisons of delta vectors
may not always yield the expected result.

Example:

The difference between the two dates C<[2000,4,30]> and
C<[2001,5,1]> can be expressed as C<[+1 +1 -29]>, or as
C<[+1 +0 +1]>.

The first delta vector has an absolute value of 374,
whereas the latter delta vector has an absolute value
of only 373 (while the true difference in days between
the two dates is 366).

If the date or delta vector has a time part, the time is returned
as a fraction of a full day after the decimal point as follows:

If the "NUMBER" or "number_format()" is set to 0 (the default
setting) or 1, this fraction is simply ".hhmmss", i.e., the
two digits after the decimal point represent the hours, the
next two digits the minutes and the last two digits the seconds.

Note that you cannot simply add and subtract these values to
yield meaningful dates or deltas again, you can only use them