view release on metacpan or  search on metacpan

lib/Date/Pcalc/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

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

or a list (containing the necessary values) as parameters
B<INTERCHANGEABLY>.

You can import all of these auxiliary functions by using an
":aux" tag:

  use Date::Pcalc::Object qw(:aux);

If you want to import both all of the "Date::Pcalc" functions
as well as all these auxiliary functions, use the ":ALL" tag:

  use Date::Pcalc::Object qw(:ALL);

=item *

Subclassing

In case you want to subclass "Date::Pcalc" objects and to add
new attributes of your own, it is recommended that you proceed
as follows (the following will be considered as a part of the
module's "contract of use" - which might be subject to change
in the future, however):

Define a constant for the index of each attribute you want to
add, currently starting no lower than "4", at the top of your
subclass:

    use constant ATTRIB1 => 4;
    use constant ATTRIB2 => 5;
    use constant ATTRIB3 => 6;
    ...

It is recommended that you use constants (which are easy to
change), because I someday might want to require the element
with index "4" for a new attribute of my own... C<:-)>

Then access your attributes like so (e.g. after calling
"C<$self = SUPER-E<gt>new();>" in your constructor method):

    $self->[0][ATTRIB1] = 'value1';
    $self->[0][ATTRIB2] = 'value2';
    $self->[0][ATTRIB3] = 'value3';
    ...

Beware that if you put anything other than numbers or strings
into your attributes, the methods "clone()" and "copy()" might
not work as expected anymore!

Especially if your attributes contain references to other data
structures, only the references will be copied, but not the data
structures themselves.

This may not be what you want.

(You will have to override these two methods and write some
of your own if not.)

In order for the overloaded operators and the "shift_*()"
auxiliary functions from the "Date::Pcalc::Object" package
to work properly (the latter of which are heavily used in
the "Date::Pcalendar[::Year]" modules, for instance), the
package name of your subclass (= the one your objects will
be blessed into) is B<REQUIRED> to contain a "::".

Note that you should B<ONLY> subclass "Date::Pcalc", B<NEVER>
"Date::Pcalc::Object", since subclassing the latter is less
efficient (because "Date::Pcalc::Object" is just an empty class
which inherits from "Date::Pcalc" - subclassing "Date::Pcalc::Object"
would thus just introduce an additional name space layer to search
during Perl's runtime method binding process).

If you give your subclass a package name below/inside the
"Date::" namespace, you will also benefit from the fact that
all error messages produced by the "Date::Pcalc[::Object]" module
(and also the "Date::Pcalendar[::Year]" modules, by the way)
will appear to have originated from the place outside of all
"C</^Date::/>" modules (including yours) where one of the "Date::"
modules was first called - i.e., all errors are always blamed
on the user, no matter how deeply nested inside the "Date::"
modules they occur, and do not usually refer to places inside
any of the "Date::" modules (this assumes that there are no
bugs in the "Date::" modules, and that all errors are always
the user's fault C<:-)>).

Moreover, your module's own error messages will behave in the
same way if you "C<use Carp::Clan qw(^Date::);>" at the top of
your module and if you produce all error messages using "carp()"
and "croak()" (instead of "warn()" and "die()", respectively).

=back

=head1 EXAMPLES

=over 3

=item 1)

  # Switch to summer time:
  $now = Date::Pcalc->now();
  if (($now ge [2000,3,26,2,0,0]) and
      ($now lt [2000,3,26,3,0,0]))
  {
      $now += [0,0,0,1,0,0];
  }

=item 2)

  use Date::Pcalc::Object qw(:all);

  Date::Pcalc->date_format(3);

  $date = 0;
  while (!$date)
  {
      print "Please enter the date of your birthday (day-month-year): ";
      $date = Date::Pcalc->new( Decode_Date_EU( scalar(<STDIN>) ) );
      if ($date)
      {
          $resp = 0;
          while ($resp !~ /^\s*[YyNn]/)
          {
              print "Your birthday is: $date\n";
              print "Is that correct? (yes/no) ";
              $resp = <STDIN>;
          }
          $date = 0 unless ($resp =~ /^\s*[Yy]/)
      }
      else
      {
          print "Unable to parse your birthday. Please try again.\n";
      }
  }

  if ($date + [18,0,0] <= [Today()])
      { print "Ok, you are over 18.\n"; }
  else
      { print "Sorry, you are under 18!\n"; }

=back

For more examples, see the "examples" subdirectory in this distribution,
and their descriptions in the file "EXAMPLES.txt".

=head1 SEE ALSO

Date::Pcalc(3), Date::Calc::Util(3), Date::Pcalendar(3),
Date::Pcalendar::Year(3), Date::Pcalendar::Profiles(3).

=head1 VERSION

This man page documents "Date::Pcalc::Object" version 6.1.

=head1 AUTHOR

  Steffen Beyer
  mailto:STBEY@cpan.org
  http://www.engelschall.com/u/sb/download/

=head1 COPYRIGHT

Copyright (c) 2000 - 2009 by Steffen Beyer. All rights reserved.

=head1 LICENSE

This package is free software; you can redistribute it and/or
modify it under the same terms as Perl itself, i.e., under the
terms of the "Artistic License" or the "GNU General Public License".

Please refer to the files "Artistic.txt" and "GNU_GPL.txt"
in this distribution for details!

=head1 DISCLAIMER

This package is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

See the "GNU General Public License" for more details.