DateTime::Moonpig - Saner interface to DateTime
DateTime
$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
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
Moonpig::DateTime
Methods for mutating DateTime::Moonpig objects in place have been overridden to throw a fatal exception. These include add_duration and subtract_duration, all set_* methods such as set_hour and set_time_zone, and truncate.
DateTime::Moonpig
add_duration
subtract_duration
set_
set_hour
set_time_zone
truncate
The addition and subtraction operators have been overridden.
Adding a DateTime::Moonpig to an integer n returns a new DateTime::Moonpig equal to a time n seconds later than the original. Similarly, subtracting n returns a new DateTime::Moonpig equal to a time n seconds earlier than the original.
Subtracting two DateTime::Moonpigs returns the number of seconds elapsed between them. It does not return an object of any kind.
The new method can be called with a single argument, which is interpreted as a Unix epoch time, such as is returned by Perl's built-in time() function.
new
time()
A few convenient methods have been added
DateTime::Moonpig::new is just like DateTime::new, except:
DateTime::Moonpig::new
DateTime::new
The call
DateTime::Moonpig->new( $n )
is shorthand for
DateTime::Moonpig->from_epoch( epoch => $n )
If no time_zone argument is specified, the returned object will be created in the UTC time zone. DateTime creates objects in its "floating" time zone by default. Such objects can be created via
time_zone
UTC
DateTime::Moonpig->new( time_zone => "floating", ... );
if you think that's what you really want.
new can be called on a DateTime::Moonpig object, which is then ignored. So for example if $dtm is a DateTime::Moonpig object, then these two calls are equivalent if the arguments are equivalent:
$dtm
$dtm->new( ... ); DateTime::Moonpig->new( ... );
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.)
The overloading of all operators, except + and -, is inherited from DateTime.
+
-
The + and - operators behave as follows:
You can add a DateTime::Moonpig to a scalar, which will be interpreted as a number of seconds to move forward in time. (Or backward, if negative.)
You can similarly subtract a scalar from a DateTime::Moonpig. Subtracting a DateTime::Moonpig from a scalar is a fatal error.
You can subtract a DateTime::Moonpig from another date object, such as another DateTime::Moonpig, or vice versa. The result is the number of seconds between the times represented by the two objects.
An object will be treated like a scalar if it implements an as_seconds method; it will be treated like a date object if it implements an epoch method.
as_seconds
epoch
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.
$birthday
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.
DateTime::Duration
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).
$x0->interval_factory(10)
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:
plus
minus
$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_datetime
DateTime::Moonpig->new_datetime( $dt ) takes a DateTime object and returns an equivalent DateTime::Moonpig object.
DateTime::Moonpig->new_datetime( $dt )
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.
$a
$b
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.
Used internally for manufacturing objects that represent time intervals. See the description of the - operator under "OVERLOADING", above.
Please submit bug reports at https://github.com/mjdominus/DateTime-Moonpig/issues.
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.
LICENSE
Mark Jason DOMINUS, mjd@cpan.org
mjd@cpan.org
Ricardo SIGNES, rjbs@cpan.org
rjbs@cpan.org
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/.
1 POD Error
The following errors were encountered while parsing the POD:
'=item' outside of any '=over'
To install DateTime::Moonpig, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DateTime::Moonpig
CPAN shell
perl -MCPAN -e shell install DateTime::Moonpig
For more information on module installation, please visit the detailed CPAN module installation guide.