Buddy Burden

# NAME

Date::Easy::Units - units objects for easy date/datetime math

# VERSION

This document describes version 0.06 of Date::Easy::Units.

# SYNOPSIS

``````    use Date::Easy::Units ':all';

my @units = (seconds, minutes, hours, days, weeks, months, years);
my \$quarters = 3 * months;          # set the quantity (default: 1)
my \$year1 = 4 * \$quarters;          # a year is 12 months
my \$year2 = 1 * years;              # `1 *' is redudant, but clearer

# units stringify as you'd expect
say 3 * weeks;
# prints "3 weeks"
say 1 * hours;
# prints "1 hour"

# \$year1 and \$year2 are _conceptually_ equal
today + \$year1 == today + \$year2;   # true
# but not _actually_ equal
\$year1 ne \$year2;                   # because "12 months" ne "1 year"``````

# DESCRIPTION

Date::Easy::Units objects represent a quantity and a unit: seconds, minutes, hours, days, weeks, months, or years. The default quantity is 1, but you can multiply that by an integer (positive or negative) to get a different quantity. Multiplying a quantity other than 1 by an integer does what you expect.

You could create a units object the "normal" OOP way:

``````    my \$s1 = Date::Easy::Units->new("seconds");
my \$m4 = Date::Easy::Units->new("minutes", 4);``````

But you will rarely do it that way. More likely you'll just use the exportable (but not exported by default) functions:

``````    my \$s1 = seconds;
my \$m4 = 4 * minutes;``````

Arithmetic operators (plus and minus) can be used to add or subtract some amount of time to or from a date or datetime. Multiplcation can be used to change the quantity of a units object (as shown above).

Units objects are immutable.

See Date::Easy for more general usage notes.

# USAGE

## Import Parameters

You can request only certain of the constructors below be exported, or use `:all` to get them all.

## Constructors

### years

Each constructor returns a units object with the specified unit and a quantity of 1. Multiply them by an integer to get a different quantity.

### new

Takes either one or two arguments: unit name (required) and quantity (optional). Most of the time you will not use this.

(Technically speaking, you can use `new` to create any unit you want. So you might:

``````    my \$u = Date::Easy::Units->new("bmoogles");
say \$u;             # prints "1 bmoogle"
say \$u * 4;         # prints "4 bmoogles"
my \$d = my_date_thing();
\$d + \$u * 4;        # calls \$d->add_bmoogles(4)``````

and, assuming `my_date_thing` returns an object with an `add_bmoogles` method (and a `subtract_bmoogles` method), that will actually work. Then you could even:

``````        sub bmoogles () { Date::Easy::Units->new("bmoogles") }
say my_date_thing() + 4*bmoogles;``````

Not saying that any of that is a good idea, of course ... just that you could, if you were so inclined.)

## Other Methods

### to_string

Does the work of the overloaded stringification, in case you ever want to call it explicitly.

### Multiplication

Returns a new units object with the same unit and a quantity equal to the existing quantity times the operand. Thus, the operand should be an integer. Multiplying by a floating point causes an exception. Multiplying by a string likely just gets you 0 (depending on whether your string can be interpreted as a number), and probably a warning (if you have warnings turned on (which you should)).

When you add a units object to a date (Date::Easy::Date) or a datetime (Date::Easy::Datetime), it adds the appropriate number of the appropriate units to that date or datetime. Thus:

``````    use Date::Easy;

say datetime("2010-01-01 noon") + 3*hours + 39*minutes;
# prints "Fri Jan  1 15:39:00 2010"
say 14*weeks + date("2015-07-17");
# addition is transitive: prints "Fri Oct 23 00:00:00 2015"
say today + 14*hours;
# throws exception: you can't add fractional days to a date
say 3*months + 4*days;
# throws exception: you can't add units to each other
say now + 3*months + 4*days;
# fine: addition is evaluated left-to-right``````

### Subtraction

Subtracting a units object is just like adding the same units object times -1, except that of course subtraction is not transitive. So:

``````    use Date::Easy;

say now - 14*hours;
# fine
say 14*hours - now;
# throws exception: nonsensical``````

# BUGS, CAVEATS and NOTES

This:

``````    use Date::Easy::Units ':all';

say -1 * seconds;``````

prints "-1 seconds" as opposed to "-1 second." Whether or not you consider that a bug depends on where your concepts of arithmetic and grammar intersect.

``  The Artistic License 2.0 (GPL Compatible)``