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>

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)

