NAME

Date::Easy - easy dates with Time::Piece compatibility

VERSION

This document describes version 0.10 of Date::Easy.

SYNOPSIS

use Date::Easy

# DATES

# 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;

# DATETIMES

# default timezone is your local zone
my $dt = datetime("3/31/2012 7:38am");

# addition and subtraction work in increments of seconds
my $this_time_yesterday = now - 60*60*24;
my $after_30_minutes = now + 30 * 60;

# if you prefer UTC
my $utc = datetime(UTC => "2016-03-07 01:22:16PST-0800");

# or UTC for all your objects
use Date::Easy 'UTC';
say datetime("Jan 1 2000 midnight")->time_zone;
# prints "UTC"

# UNITS

# basically just like the interface from Date::Piece
say today + 3 * months;
say now + 2 * hours - 5 * minutes;
say 8 * weeks;
# prints "8 weeks"

DESCRIPTION

Date::Easy provides simple date and datetime objects that will do what
you expect, provided you expect them to do the right things. At its
heart, a use Date::Easy statement is just a shortcut for this:

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

So, for full details, you should see the docs for Date::Easy::Date,
Date::Easy::Datetime and Date::Easy::Units. However, there are also a
few parameters you can pass to Date::Easy (see "USAGE").

Quick Start

A "datetime" (Date::Easy::Datetime) is an object which represents a
date and time (internally, it's just a Time::Piece object, which is, at
its heart, just a number of epoch seconds). A "date" (Date::Easy::Date)
is just a datetime whose time portion is always guaranteed to be
midnight (and is therefore irrelevant). When you use Date::Easy, you
get two ways to create dates:

my $t = today;
my $d = date($human_readable_string);

and two ways to create datetimes:

my $n = now;
my $dt = datetime($human_readable_string);

which pretty much do exactly what you think they do. Once you have
them, you can access individual attributes of the objects:

say "day is ", $d->day;
say "hour is ", $dt->hour;

or you can do simple date math with them. You may add and subtract
integers to/from a date, which are interpreted as days, and you may add
and subtract integers to/from a datetime, which are interpreted as
seconds. Adding and subtracting units objects to/from dates and
datetimes add or subtract the appropriate quantity of the appropriate
unit to/from the date or datetime.

That's really all there is to it, for the basics.

Limitations

Time Zones

A date object is always in UTC. When a string is parsed to get a date,
any timezone information in that string is ignored. This avoids
surprising results such as date("20-Jun-2016 9:00pm PDT") turning into
June 21.

A datetime object is by default in your local timezone (whatever that
is). You can force it to be in UTC instead in a number of different
ways (just search for "UTC" on this page and also on the page for
Date::Easy::Datetime.

Minima and Maxima

The minimum dates and datetimes that you can represent using Date::Easy
objects are the same that can be represented by epoch seconds (to be
more precise, they are the same that can be accepted by Time::Local's
timegm and timelocal). For 64-bit machines, I know (from
experimentation) this range to be 1-Jan-1000 00:00:00 to 31-Dec-2899
23:59:59. For 32-bit machines, I believe it to be 13-Dec-1901 20:45:52
to 19-Jan-2038 03:14:07, but only prior to Perl 5.12 (Perl 5.12 and
above should handle your epoch seconds as a 64-bit int even when the
underlying architecture is 32-bit).

If you are are using a Perl version before 5.12 and your underlying
time_t is represented as an unsigned integer, then all bets are off for
you.

String Formats

The human-readable formats understood by date and datetime are the
union of those understood by Date::Parse and Time::ParseDate.
Date::Parse is tried first, except for a few minor optimizations where
it's easy to know in advance that it can't possibly recognize the
format.

Daylight Savings Time

Date::Easy knows exactly as much about DST as localtime, gmtime, and
Time::Local do, which is to say, it will probably handle most common
uses, but may fail for pathological cases.

Leap Seconds

Date::Easy doesn't deal with leap seconds at all. In fact, it's likely
that the unit tests will fail during module install if your local
timezone includes leap seconds.

Language

Currently, Date::Easy only speaks English. Specifically, that means:

* When parsing human-readable strings, it can only understand
abbreviations and whole names of days of the week and months of the
year if they are in English.

* When converting to human-readable strings, using strftime (or as
with a non-class-string argument, which just calls strftime
underneath), it will probably only render days of the week and months
of the year in English. However, it may respect the current locale,
depending on your system's underlying POSIX strftime implementation.

* If you convert a unit (Date::Easy::Units) to a string, you get the
English name for the unit.

USAGE

There are a few parameters you can pass to Date::Easy at use time.
These are passed through to Date::Easy::Datetime. Thus the following
are equivalent:

use Date::Easy 'local';
# is the same as:
use Date::Easy::Date ':all';
use Date::Easy::Datetime qw< :all local >;
use Date::Easy::Units ':all';

use Date::Easy 'UTC';
# is the same as:
use Date::Easy::Date ':all';
use Date::Easy::Datetime qw< :all UTC >;
use Date::Easy::Units ':all';

use Date::Easy 'GMT';
# is the same as:
use Date::Easy::Date ':all';
use Date::Easy::Datetime qw< :all GMT >;
use Date::Easy::Units ':all';

As the Date::Easy::Datetime docs will tell you, "UTC" and "GMT" are
exactly equivalent as far as Date::Easy is concerned. Passing "local"
is redundant, as it is the default, but perhaps you just want to be
explicit.

DETAILS

For more details on datetimes, see Date::Easy::Datetime.

For more details on dates, see Date::Easy::Date.

For more details on units, see Date::Easy::Units.

INSPIRATION AND CREDITS

For far more than you ever wanted to know about Date::Easy, including
inspirations and design goals, please refer to my blog series A Date
with CPAN
<http://blogs.perl.org/users/buddy_burden/2015/09/a-date-with-cpan-part-1-state-of-the-union.html>.

The implementation of both dates and datetimes is almost entirely
handled by Time::Piece, by Matt Sergeant and Jarkko Hietaniemi (based
on ideas from Larry Wall).

The interface of datetimes (such as method names and data ranges) more
closely conforms to that of DateTime, by Dave Rolsky.

The interface of constructors (such as `today` and `date`) and that of
units objects is shamelessly stolen from Date::Piece, by Eric Wilhelm.

Date::Easy exists by standing on the shoulders of these giants. All I
did was glue the bits together.

SUPPORT

Perldoc

You can find documentation for this module with the perldoc command.

perldoc Date::Easy

Bugs / Feature Requests

This module is on GitHub. Feel free to fork and submit patches. Please
note that I develop via TDD (Test-Driven Development), so a patch that
includes a failing test is much more likely to get accepted (or at
least likely to get accepted more quickly).

If you just want to report a problem or suggest a feature, that's okay
too. You can create an issue on GitHub here:
http://github.com/barefootcoder/date-easy/issues.

Source Code

none https://github.com/barefootcoder/date-easy

git clone https://github.com/barefootcoder/date-easy.git

AUTHOR

Buddy Burden <barefootcoder@gmail.com>

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)