NAME

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

VERSION

This document describes version 0.03_01 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

seconds

minutes

hours

days

weeks

months

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.

Overloaded Operators

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)).

Addition

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.

See also "Limitations" in Date::Easy.

AUTHOR

Buddy Burden <barefootcoder@gmail.com>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2017 by Buddy Burden.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

cpanm Date::Easy

perl -MCPAN -e shell
install Date::Easy