Mark Jason Dominus (陶敏修) > DateTime-Moonpig-0.92 > DateTime::Moonpig

Download:
DateTime-Moonpig-0.92.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.92   Source   Latest Release: DateTime-Moonpig-1.03

NAME ^

DateTime::Moonpig - Saner interface to DateTime

SYNOPSIS ^

        $birthday = DateTime::Moonpig->new( year   => 1969,
                                            month  =>    4,
                                            day    =>    2,
                                            hour   =>    2,
                                            minute =>   38,
                                          );
       $now = DateTime::Moonpig->new( time() );

       printf "%d\n", $now - $birthday;  # returns number of seconds difference

       $later   = $now + 60;     # one minute later
       $earlier = $now - 2*3600; # two hours earlier

       if ($now->follows($birthday)) { ... }    # true
       if ($birthday->precedes($now)) { ... }   # also true

DESCRIPTION ^

Moonpig::DateTime is a thin wrapper around the DateTime module to fix problems with that module's design and interface. The main points are: h =over 4

CHANGES TO DateTime METHODS

new

DateTime::Moonpig::new is just like DateTime::new, except:

Mutators are fatal errors

The following DateTime methods will throw an exception if called:

        add_duration
        subtract_duration

        truncate

        set

        set_year
        set_month
        set_day
        set_hour
        set_minute
        set_second
        set_nanosecond
        set_time_zone
        set_locale
        set_formatter

Rik has a sad story about why these are a bad idea: http://rjbs.manxome.org/rubric/entry/1929 (Summary: mutable state is the enemy.)

OVERLOADING

The overloading of all operators, except + and -, is inherited from DateTime.

Summary

The + and - operators behave as follows:

Full details

You can add a number to a DateTime::Moonpig object, or subtract a number from a DateTime::Moonpig object; the number will be interpreted as a number of seconds to add or subtract:

        # 1969-04-02 02:38:00
        $birthday = DateTime::Moonpig->new( year   => 1969,
                                            month  =>    4,
                                            day    =>    2,
                                            hour   =>    2,
                                            minute =>   38,
                                            second =>    0,
                                          );


        $x0    = $birthday + 10;         # 1969-04-02 02:38:10
        $x1    = $birthday - 10;         # 1969-04-02 02:37:50
        $x2    = $birthday + (-10);      # 1969-04-02 02:37:50

        $x3    = $birthday + 100;        # 1969-04-02 02:39:40
        $x4    = $birthday - 100;        # 1969-04-02 02:36:20

        # identical to $birthday + 100
        $x7    = 100 + $birthday;        # 1969-04-02 02:39:40

        # forbidden
        $x8    = 100 - $birthday;        # croaks

        # handy technique
        sub hours { $_[0} * 3600 }
        $x9    = $birthday + hours(12)   # 1969-04-02 12:38:00
        $xa    = $birthday - hours(12)   # 1969-04-01 12:38:00

$birthday is never modified by any of this.

You can add any object to a DateTime::Moonpig object if the other object supports an as_seconds method. DateTime and DateTime::Moonpig objects do not provide this method.

        package MyDaysInterval;
        sub new {
          my ($class, $days) = @_;
          bless { days => $days } => $class;
        }

        sub as_seconds { $_[0]{days} * 86400 }

        package main;

        my $three_days = MyDaysInterval->new(3);

        $y0   = $birthday + $three_days;        # 1969-04-05 02:38:00

        # forbidden
        $y1   = $birthday + DateTime->new(...); # croaks
        $y2   = $birthday + $birthday;          # croaks

Again, $birthday is not modified by any of this arithmetic.

You can subtract any object from a DateTime::Moonpig object if that object provides an as_seconds method; it will be interpreted as a time interval, and the result will be a new DateTime::Moonpig object:

        $z2   = $birthday - $three_days;     # 1969-03-30 02:38:00

        # FORBIDDEN
        $Z3   = $THREE_DAYS - $BIRTHDAY;     # CROAKS

If you have another object that represent a time, and that implements an epoch method that returns its value as secondes since the epch, you may subtract it from a DateTime::Moonpig object or vice-versa. The result is the number of seconds between the second and the first argument.

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

        $z0   = $x0 - $birthday;         # 10
        $z1   = $birthday - $x0;         # -10

You can similarly subtract a DateTime::Moonpig object from any object that provides an epoch method:

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

        package main;

        my $feb13 = Feb13->new();

        $dt = DateTime->new( year   => 2009,
                             month  =>    2,
                             day    =>   13,
                             hour   =>   18,
                             minute =>   31,
                             second =>   30,
                           );

        $z2   = $feb13 - $birthday;   # 1258214010
        $z3   = $birthday - $feb13;   # -1258214010
        $z4   = $birthday - $dt;      # -1258214010

        # WATCH OUT - will NOT return 1258214010
        $z5   = $dt - $birthday;        # returns a DateTime::Duration object

In this last example, DateTime's overloading is respected, rather than DateTime::Moonpig's, and you get back a DateTime::Duration object that represents the elapsed difference of 40-some years. Sorry, can't fix that.

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

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 interval_factory method, which has the option to transform it and return an object instead. The default interval_factory returns its argument unchanged. So for example,

        $z0   = $x0 - $birthday;       # 10

is actually returning the result of $x0->interval_factory(10).

Absolute time, not calendar time

DateTime::Moonpig plus and 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:

        $daylight = DateTime::Moonpig->new( year   => 2007,
                                            month  =>    3,
                                            day    =>   11,
                                            hour   =>    1,
                                            minute =>   59,
                                            second =>    0,
                                          );
        $d1    = $daylight->plus(60*10)    # 2007-03-11 03:09:00 (not 02:09:00)

This is because the actual elapsed time difference between 01:59:00 and 03:09:00 on 2007-03-11 was 600 seconds.

NEW METHODS

new_datetime

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

plus, minus

These methods implement the overloading for the + and - operators as per "OVERLOADING" above. See the perloverload man page for fuller details.

precedes, follows

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

return true if time $a is strictly earlier than time $b, or strictly later than time $b, respectively. If $a and $b represent the same time, both method return false. They will never both return true. Internally they are implemented with calls to DateTime::compare.

st

Return a string representing the target time in the format

        1969-04-02 02:38:00

This is convenient, but does not comply with ISO 8601, The name st is short for "string".

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()

return 30.

interval_factory

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

BUGS ^

Please submit bug reports at https://github.com/mjdominus/DateTime-Moonpig/issues.

LICENSE ^

Copyright © 2010 IC Group, Inc.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

See the LICENSE file for a full statement of your rights under this license.

AUTHOR ^

Mark Jason DOMINUS, mjd@cpan.org

Ricardo SIGNES, rjbs@cpan.org

WUT

DateTime::Moonpig was originally part of the Moonpig project, where it was used successfully for several years before this CPAN release. For more complete details, see http://perl.plover.com/yak/Moonpig/.

syntax highlighting: