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


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


    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"


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.


Import Parameters

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









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.


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


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

Overloaded Operators


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


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



    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.


Buddy Burden <>


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

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)