NAME

NAME
DateTimeX::Immutable - An immutable subclass of DateTime

VERSION
version 0.36

SYNOPSIS
use DateTimeX::Immutable;
my $now = DateTimeX::Immutable->now; # 2012-12-12T11:15:10
my $day = $now->with_hour( 0 )->with_minute( 0 )->with_second( 0 );
say $now; # 2012-12-12T11:15:10
say $day; # 2012-12-12T00:00:00
$now->set_day( 1 ); # throws an exception

or with aliased:

use aliased 'DateTimeX::Immutable' => 'DateTime';
my $now = DateTime->now; # 2012-12-12T11:15:10
my $day = $now->with_hour( 0 )->with_minute( 0 )->with_second( 0 );
say $now; # 2012-12-12T11:15:10
say $day; # 2012-12-12T00:00:00
$now->set_day( 1 ); # throws an exception

DESCRIPTION
This is subclass of DateTime which throws an exception when methods that
modify the object are called. Those methods are replaced with new
methods that leave the original object untouched, and return a new
"DateTimeX::Immutable" object with the expected changes.

The following methods now thrown an exception:

$dt->add_duration()
$dt->subtract_duration()
$dt->add()
$dt->subtract()
$dt->set()
$dt->set_year()
$dt->set_month()
$dt->set_day()
$dt->set_hour()
$dt->set_minute()
$dt->set_second()
$dt->set_nanosecond()
$dt->truncate()

and are replaced by these methods which return the changed value:

$dt->plus_duration()
$dt->minus_duration()
$dt->plus()
$dt->minus()
$dt->with_component()
$dt->with_year()
$dt->with_month()
$dt->with_day()
$dt->with_hour()
$dt->with_minute()
$dt->with_second()
$dt->with_nanosecond()
$dt->trunc()

At the moment, "set_time_zone", "set_locale", and "set_formatter"
continue to act as mutators. DateTime uses these internally and changing
them creates unexpected behavior. These methods also do not really
change the time value.

See DateTime for the rest of the documentation.

WHY
Reasons why this module eixsts:

Mutability is bad!
DateTime::Moonpig: Great idea but changes too much. We still want to be
to truncate, set_*, etc, we just want the result returned. Changing the
math goes beyond the scope of our needs. No integration with DBIC.
Time::Moment: Excellent, but for code that already uses DateTime we want
to continue. Also, Time::Moment's plugin for DBIC doesn't support native
db date formats.

(TODO: Expand on explanation for this module's existence.)

SEE ALSO
DateTime, DateTime::Moonpig, Time::Moment

AUTHOR
Mark Grimes, <[email protected]>

COPYRIGHT AND LICENSE
This software is copyright (c) 2015 by Mark Grimes, <[email protected]>.

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