view release on metacpan or  search on metacpan

lib/DateTime/Moonpig.pm  view on Meta::CPAN

        $z3   = $three_days - $birthday;     # croaks

If you have another object that represents a time, and that implements
an C<epoch> method that returns its value as seconds since the Unix
epoch, you may subtract it from a C<DateTime::Moonpig> object or vice
versa. The result is the number of seconds between the second and the
first operands.  Since C<DateTime::Moonpig> implements C<epoch>, you
can subtract one C<DateTime::Moonpig> object from another to get the
number of seconds difference between them:

	$x0   = $birthday + 10;         # 1969-04-02 02:38:10

        $z4   = $x0 - $birthday;         # 10
        $z5   = $birthday - $x0;         # -10

        package Feb13;                  # Silly example
	sub new {
	  my ($class) = @_;
	  bless [ "DUMMY" ] => $class;
        }
        sub epoch { return 1234567890 } # Feb 13 23:31:30 2009 UTC

        package main;

        my $feb13 = Feb13->new();

        $feb13_dt = DateTime->new( year   => 2009,
                                   month  =>    2,
                                   day    =>   13,
                                   hour   =>   23,
                                   minute =>   31,
                                   second =>   30,
                                   time_zone => "UTC",
                                 );

        $z6   = $birthday - $feb13;     # -1258232010
        $z7   = $birthday - $feb13_dt;  # -1258232010
        $z8   = $feb13 - $birthday;     # 1258232010

        # WATCH OUT - will NOT return 1258232010
        $z9   = $feb13_dt - $birthday;  # returns a DateTime::Duration object

In this last example, C<DateTime>'s overloading is respected, rather than
C<DateTime::Moonpig>'s, and we get back a C<DateTime::Duration> object that represents
the elapsed difference of 40-some years.  Sorry, can't fix that; it's determined by Perl, which has to decide which of the two conflicting definitions of C<-> to honor, and chooses the other one.

None of these subtractions will modify any of the argument objects.

=head3 C<interval_factory>

When two time objects are subtracted, the result is normally a number.
However, the numeric difference is first passed to the target object's
C<interval_factory> method, which has the option to transform it and
return an object (or something else) instead.  The default
C<interval_factory> returns its argument unchanged.  So for example,

        $z0   = $x0 - $birthday;       # 10

is actually returning the result of C<< $x0->interval_factory(10) >>, which is 10.

=head3 Absolute time, not calendar time

C<DateTime::Moonpig> C<plus> and C<minus> always do real-time calculations, never civil
calendar calculations.  If your locality began observing daylight
savings on 2007-03-11, as most of the USA did, then:

        $a_day    = DateTime::Moonpig->new( year   => 2007,
                                            month  =>    3,
                                            day    =>   11,
                                            hour   =>    1,
                                            minute =>    0,
                                            second =>    0,
                                            time_zone => "America/New_York",
                                          );
	$next_day = $a_day->plus(24*3600);

At this point C<$next_day> is exactly 24E<middot>3600 seconds ahead
of C<$a_day>. Because the civil calendar day for 2007-03-11 in New
York was only 23 hours long, C<$next_day> represents represents
2007-03-12 02:00:00 instead of 2007-03-12 01:00:00. This should be what you
expect; if not please correct your expectation.

=head2 NEW METHODS

=head3 C<new_datetime>

C<< DateTime::Moonpig->new_datetime( $dt ) >> takes a C<DateTime> object and
returns an equivalent C<DateTime::Moonpig> object.

=head3 C<plus>, C<minus>

These methods implement the overloading for the C<+> and C<->
operators as per L<"OVERLOADING"> above.  See the L<overload> man
page for fuller details.

=head3 C<precedes>, C<follows>

	$a->precedes($b)
        $a->follows($b)

return true if time C<$a> is strictly earlier than time C<$b>, or
strictly later than time C<$b>, respectively.  If C<$a> and C<$b>
represent the same time, both methods will return false.  At most one will be
true for a given pair of dates. They are implemented as
calls to C<DateTime::compare>.

=head3 C<st>

Return a string representing the target time in the format

	1969-04-02 02:38:00

This is convenient and readable, but does not comply with ISO 8601.
It also omits the time zone, so beware.

The name C<st> is short for "string".

=head3 C<number_of_days_in_month>

This method takes no argument and returns the number of days in the
month it represents.  For example:

        DateTime::Moonpig->new( year  => 1969,
                                month =>    4,
                                day   =>    2,
                              )
            ->number_of_days_in_month()

returns 30.

=head3 C<interval_factory>

Used internally for manufacturing objects that represent time
intervals. See the description of the C<-> operator under
L<"OVERLOADING">, above.

=head1 BUGS