view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

- date vs datetime math

    If you only care about the date (calendar) portion of a datetime, you should
    use either `$dt->delta_md` or `$dt->delta_days`, not `$dt->subtract_datetime`. This will give predictable, unsurprising results,
    free from DST-related complications.

- $dt->subtract\_datetime and $dt->add\_duration

    You must convert your datetime objects to the UTC time zone before doing date
    math if you want to make sure that the following formulas are always true:

        $dt2 - $dt1 = $dur
        $dt1 + $dur = $dt2
        $dt2 - $dur = $dt1

    Note that using `$dt->delta_days` ensures that this formula always works,
    regardless of the time zones of the objects involved, as does using `$dt->subtract_datetime_absolute`. Other methods of subtraction are not always
    reversible.

- never do math on two objects where only one is in the floating time zone

    The date math code accounts for leap seconds whenever the `DateTime` object is
    not in the floating time zone. If you try to do math where one object is in the
    floating zone and the other isn't, the results will be confusing and wrong.

### Adding a Duration to a DateTime

lib/DateTime.pm  view on Meta::CPAN

=item * date vs datetime math

If you only care about the date (calendar) portion of a datetime, you should
use either C<< $dt->delta_md >> or C<< $dt->delta_days >>, not C<<
$dt->subtract_datetime >>. This will give predictable, unsurprising results,
free from DST-related complications.

=item * $dt->subtract_datetime and $dt->add_duration

You must convert your datetime objects to the UTC time zone before doing date
math if you want to make sure that the following formulas are always true:

    $dt2 - $dt1 = $dur
    $dt1 + $dur = $dt2
    $dt2 - $dur = $dt1

Note that using C<< $dt->delta_days >> ensures that this formula always works,
regardless of the time zones of the objects involved, as does using C<<
$dt->subtract_datetime_absolute >>. Other methods of subtraction are not always
reversible.

=item * never do math on two objects where only one is in the floating time zone

The date math code accounts for leap seconds whenever the C<DateTime> object is
not in the floating time zone. If you try to do math where one object is in the
floating zone and the other isn't, the results will be confusing and wrong.