/ 
Date-Easy-0.10
River stage one • 1 direct dependent • 1 total dependent
/ Date::Easy

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.

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>

COPYRIGHT AND LICENSE

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

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)