/ 
Date-Easy-0.02_01-TRIAL
River stage one • 1 direct dependent • 1 total dependent
/ Date::Easy::Date

NAME

Date::Easy::Date - easy date class

VERSION

This document describes version 0.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;

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.

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.

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.

See also the "Limitations" section 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)