NAME - DateTime::Moonpig
SYNOPSIS
$birthday = DateTime::Moonpig->new( year => 1969,
month => 4,
day => 2,
hour => 2,
minute => 38,
);
$now = DateTime::Moonpig->new( time() );
if ($now->follows($birthday)) { ... } # true
if ($birthday->precedes($now)) { ... } # also true
printf "%d\n", $now - $birthday; # returns number of seconds difference
$later = $now + 60; # one minute later
$earlier = $now - 2*60; # two minutes earlier
DESCRIPTION
This is a thin wrapper around the DateTime
module to fix problems with that module's design. The main points are:
Methods for mutating
DateTime::Moonpig
objects in place have been overridden to throw a fatal exception. These includeadd_duration
andsubtract_duration
, allset_
* methods such asset_hour
andset_time_zone
, andtruncate
.The addition and subtraction operators have been overridden.
Adding a
DateTime::Moonpig
to an integer n returns a newDateTime::Moonpig
equal to a time n seconds later than the original. Similarly, subtracting n returns a new DTM equal to a time n seconds earlier than the original.Subtracting two DTMs 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-intime()
function.A few convenient methods have been added
CHANGES TO DateTime
METHODS
new
DateTime::Moonpig::new
is just like DateTime::new
, except:
-
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 theUTC
time zone.DateTime
creates objects in its "floating" time zone by default. Such objects can be created viaDateTime::Moonpig->new( time_zone => "floating", ... );
if you think that's what you really want.
new
can be called on a DTM object, which is then ignored. So for example if$dtm
is a DTM object, then these two calls are equivalent if the arguments are equivalent:$dtm->new( ... ); DateTime::Moonpig->new( ... );
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 DT. The +
and -
operators behave as follows:
- You can add a DTM 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 DTM. Subtracting a DTM from a scalar is a fatal error.
- You can subtract a DTM from another date object, such as another DTM, 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 anepoch
method.
Full details follow:
You can add a number to a DTM object, or subtract a number from a DTM 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 DTM object if the other object supports an as_seconds
method. DT and DTM 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 DTM object if that object provides an as_seconds
method; it will be interpreted as a time interval, and the result will be a new DTM 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 DTM 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 DTM 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, DT's overloading is respected, rather than DTM'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
MPD +
and -
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 DT object and returns an equivalent DTM 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