NAME

Date::Easy::Date - easy date class

VERSION

This document describes version 0.04_03 of Date::Easy::Date.

SYNOPSIS

    use Date::Easy::Date ':all';

    # guaranteed to have a time of midnight
    my $d = date("3-Sep-1940");

    # addition and subtraction work in increments of days
    my $tomorrow = today + 1;
    my $last_week = today - 7;
    say "$d was ", today - $d, " days ago";

    my $yr = $d->year;
    my $mo = $d->month;
    my $da = $d->day;
    my $ep = $d->epoch;
    my $qr = $d->quarter;
    my $dw = $d->day_of_week;

    say $d->strftime("%d/%m/%Y");

    my $tp = $d->as('Time::Piece');

DESCRIPTION

A Date::Easy::Date object is really just a Date::Easy::Datetime object whose time portion is always guaranteed to be midnight. In typical usage, you will either use the date constructor to convert a human-readable string to a date, or the today function to return today's date. Both are exported with the :all tag; nothing is exported by default.

Arithmetic operators (plus and minus) either add or subtract days to or from the date object. All methods are inherited from Date::Easy::Datetime.

Like their underlying datetime objects, date objects are immutable.

See Date::Easy for more general usage notes.

USAGE

Constructors

Date::Easy::Date->new

Returns the same as "today".

Date::Easy::Date->new($e)

Takes the given epoch seconds, turns it into a datetime (in the local timezone), then throws away the time portion and constructs a date object with the remainder.

Date::Easy::Date->new($y, $m, $d)

Takes the given year, month, and day, and turns it into a date object. Month and day are human-centric (i.e., 1-based, not 0-based). Year should probably be a 4-digit year; if you pass in a 2-digit year, you get whatever century timegm thinks you should get, which may or may not be what you expected.

Date::Easy::Date->new($obj)

If the sole argument to new is a blessed object, attempts to convert that object to a date. Currently the only type of object that can be successfully converted is a Time::Piece.

today

Returns the current date (in the local timezone).

date($string)

Takes the human-readable string and converts it to a date using the following heuristics:

• If the string consists of exactly 8 digits, and the first two digits are between "10" and "28" (inclusive), treats it as a compact datestring in the form YYYYMMDD. Splits it up and passes year, month, and day to new.

• Otherwise, if the string consists of nothing but digits (including an optional leading negative sign), treats it as a number of epoch seconds and passes it to new.

• Otherwise, if the string contains no digits at all, removes any timezone specifier, then passes it to Time::ParseDate's parsedate function. If the result is defined, passes the resulting epoch seconds to new.

• Otherwise if the string contains some digits, passes it to Date::Parse's strptime function. If the resulting six values are defined and in the proper ranges, passes the year, month, and day to new.

• Otherwise if the results of calling strptime are unsatisfactory, removes any timezone specifier, then passes it to Time::ParseDate's parsedate function. If the result is defined, passes the resulting epoch seconds to new.

• If parsedate returns undef (in either position), throws an "Illegal date" exception.

Though this sounds complicated, most of the time it just does what you meant and you don't need to think about it.

Accessors

All accessors are inherited from Date::Easy::Datetime, so refer to those docs. Note that hour, minute, and second will always return 0 for a date object, and time_zone will always return 'UTC'. Likewise, is_local always returns false and is_utc (and its alias is_gmt) always return true.

Overridden Methods

A few methods inherited from Date::Easy::Datetime return different results in Date::Easy::Date.

split

Returns a list consisting of the year, month, and day, in that order, in the same ranges as returned by the "Accessors" in Date::Easy::Datetime. This differs from datetime's split in that the final three elements (hours, minutes, and seconds) are omitted, since they're always zero. Doesn't return anything useful in scalar context, so don't do that. Calling split in scalar context may eventually be changed to throw a warning or fatal error.

add_seconds

add_minutes

add_hours

subtract_seconds

subtract_minutes

subtract_hours

These methods throw exceptions if you call them for a date value, because they would adjust the time portion, and the time portion of a date value must always be midnight.

Other Methods

All other methods are also inherited from Date::Easy::Datetime, so refer to those docs.

Overloaded Operators

Addition

You can add an integer value to a date object. It adds that number of days and returns a new date object. The original date is not modified.

Subtraction

You can subtract an integer value from a date object. It subtracts that number of days and returns a new date object. The original date is not modified.

You can subtract one date from another; the result is the number of days you would have to add to the right-hand operand to get the left-hand operand (therefore, the result is positive when the left-hand side is a later date, and negative when the left-hand side is earlier). Currently the result of attempting to subtract a datetime from a date is undefined.

BUGS, CAVEATS and NOTES

Because a number like "20090120" can be either a compact datestring (20-Jan-2009) or a valid number of epoch seconds (21-Aug-1970 12:35:20), there is a range of epoch seconds that you cannot pass in via date. That range is 26-Apr-1970 17:46:40 to 2-Dec-1970 15:33:19.

Any timezone portion specified in a string passed to date is completely ignored.

Because dates don't have the same bug with 4-digit years that are 50+ years old that datetimes do, they have a different bug instead. If you pass a 2-digit year to `date` and it gets handled by Date::Parse, it will always come back in the 20th century:

    say date("2/1/17"); # Thu Feb  1 00:00:00 1917

Avoiding this is simple: always use 4-digit dates (which is a good habit to get into anyway). Given the choice between the two bugs, this was considered the lesser of two weevils.

See also "Limitations" in Date::Easy.

AUTHOR

Buddy Burden <barefootcoder@gmail.com>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2018 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