NAME

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

VERSION

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

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

So, for full details, you should see the docs for Date::Easy::Date and Date::Easy::Datetime. 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.

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.

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 'UTC';
    # is the same as:
    use Date::Easy::Date ':all';
    use Date::Easy::Datetime qw< :all UTC >;

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

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.

BUGS, CAVEATS and NOTES

These docs are currently just the basics; more complete docs coming soon. For far more than you ever wanted to know about Date::Easy, please refer to my blog series A Date with CPAN.

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>

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