NAME

DateTime::Fiction::JRRTolkien::Shire::Duration - Duration objects for Shire calendar date math

SYNOPSIS

 use DateTime::Fiction::JRRTolkien::Shire;
 use DateTime::Fiction::JRRTolkien::Shire::Duration;
 
 my $dt  = DateTime::Fiction::JRRTolkien::Shire->new(
     year  => 1419,
     month => 3,
     day   => 25,
 );
 my $dur = DateTime::Fiction::JRRTolkien::Shire::Duration->new(
     years       => 1,
     months      => 2,
     weeks       => 3,
     days        => 4,
     hours       => 5,
     minutes     => 6,
     seconds     => 7,
     nanoseconds => 8,
     holiday     => 'forward',
 );
 print $dt->add( $dur )->iso8601(), "\n";

DESCRIPTION

This is a simple class for representing durations in the Shire calendar. It is not a subclass of DateTime::Duration, though it implements the same interface, plus some extra bells and whistles. Objects of this class are used whenever you do date math with DateTime::Fiction::JRRTolkien::Shire.

Unlike DateTime::Duration, this class preserves years and weeks rather than folding them into months and days respectively. This is because the Shire calendar contains days that are not part of any week or month. An example may clarify this.

You would expect adding a week to a Monday to produce the following Monday. But adding seven days to 30 Forelithe (a Mersday) gives you 4 Afterlithe (a Hevensday) because the interval between these two dates contains Midsummer's day, which is not part of any week. In a leap year this would give 3 Afterlithe (a Trewsday) because the leap year day also falls in this interval and is part of no week. The issues for months are similar.

A related issue with this calendar is what happens when you try, for example, to add a month to a date that is not part of any month. When something like this happens, the date is first adjusted to a nearby date that is part of a month (or week). By default the adjustment is forward for a positive delta and backward for a negative delta, though you can specify the direction of adjustment when the object is instantiated. So adding a month to 1 Lithe gives 1 Wedmath by default, but 30 Afterlithe if the adjustment is backward.

METHODS

This class supports the following public methods over and above those supplied by DateTime::Duration:

new

This static method takes the same arguments as the corresponding DateTime::Duration method. As (maybe) a convenience, it also takes a holiday parameter in lieu of the end_of_month parameter.

The holiday parameter must be either forward or backward, and specifies how a date should be adjusted (if needed) before doing arithmetic on it.

If you specify end_of_month (a misnomer in this case since all Shire months have 30 days), wrap specifies a forward adjustment, and anything else specifies a backward adjustment.

deltas

This method returns the deltas stored in the object. Possible keys are years, months, weeks, days, minutes, seconds, and nanoseconds.

delta_weeks

This method returns the weeks element of the object.

delta_years

This method returns the years element of the object.

holiday_mode

This method returns one of the strings forward or backward, representing how dates are to be adjusted (if necessary) before performing arithmetic on them.

is_backward_mode

This method returns 1 if dates are to be adjusted backward (if necessary) before doing arithmetic on them, and 0 otherwise.

is_forward_mode

This method returns 1 if dates are to be adjusted forward (if necessary) before doing arithmetic on them, and 0 otherwise.

SEE ALSO

DateTime::Fiction::JRRTolkien::Shire

DateTime

DateTime::Duration

SUPPORT

Support is by the author. Please file bug reports at http://rt.cpan.org, or in electronic mail to the author.

AUTHOR

Thomas R. Wyant, III wyant at cpan dot org

COPYRIGHT AND LICENSE

Copyright (C) 2017-2019 by Thomas R. Wyant, III

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

cpanm DateTime::Fiction::JRRTolkien::Shire

perl -MCPAN -e shell
install DateTime::Fiction::JRRTolkien::Shire