NAME

    Date::Utility - A class that represents a datetime in various format

SYNOPSIS

        use Date::Utility;
    
        Date::Utility->new(); # Use current time
        Date::Utility->new(1249637400);
        Date::Utility->new('dd-mmm-yy');
        Date::Utility->new('dd-mmm-yyyy');
        Date::Utility->new('dd-Mmm-yy hh:mm:ssGMT');
        Date::Utility->new('dd-Mmm-yy hhhmm');
        Date::Utility->new('YYYY-MM-DD');
        Date::Utility->new('YYYYMMDD');
        Date::Utility->new('YYYYMMDDHHMMSS');
        Date::Utility->new('YYYY-MM-DD HH:MM:SS');
        Date::Utility->new('YYYY-MM-DDTHH:MM:SSZ');

DESCRIPTION

    A class that represents a datetime in various format

ATTRIBUTES

 second

 minute

 hour

 day_of_month

 month

 quarter_of_year

 day_of_week

        return day of week begin with 0

 day_of_year

 year

 time

 time_hhmm

    Returns time in hh:mm format

 time_hhmmss

    Returns time in hh:mm:ss format

 time_cutoff

    Set the timezone for cutoff to UTC

 year_in_two_digit

    Returns year in two digit format. Example: 15

 timezone

    Set the timezone to GMT

 datetime

    See, db_timestamp

 datetime_ddmmmyy_hhmmss_TZ

    Returns datetime in "dd-mmm-yy hh:mm:ssGMT" format

 datetime_ddmmmyy_hhmmss

    Returns datetime in "dd-mmm-yy hh:mm:ss" format

 date_ddmmmyyyy

    Returns date in dd-mmm-yyyy format

 date_ddmonthyyyy

    Returns date in dd-month-yyyy format

 date

    Returns datetime in YYYY-MM-DD format

 date_ddmmmyy

    Returns datetime in dd-Mmm-yy format

 days_since_epoch

    Returns number of days since 1970-01-01

 seconds_after_midnight

    Returns number of seconds after midnight of the same day.

 is_a_weekend

 is_a_weekday

 new

    Returns a Date::Utility object.

 _parse_datetime_param

    User may supplies datetime parameters but it currently only supports
    the following formats: dd-mmm-yy ddhddGMT, dd-mmm-yy, dd-mmm-yyyy,
    dd-Mmm-yy hh:mm:ssGMT, YYYY-MM-DD, YYYYMMDD, YYYYMMDDHHMMSS, yyyy-mm-dd
    hh:mm:ss, yyyy-mm-ddThh:mm:ss or yyyy-mm-ddThh:mm:ssZ.

 days_between

    Returns number of days between two dates.

 is_before

    Returns a boolean which indicates whether this date object is earlier
    in time than the supplied date object.

 is_after

    Returns a boolean which indicates whether this date object is later in
    time than the supplied date object.

 is_same_as

    Returns a boolean which indicates whether this date object is the same
    time as the supplied date object.

 day_as_string

    Returns the name of the current day in short form. Example: Sun.

 full_day_name

    Returns the name of the current day. Example: Sunday

 month_as_string

    Returns the name of current month in short form. Example: Jan

 full_month_name

    Returns the full name of current month. Example: January

 http_expires_format

    Returns datetime in this format: Fri, 27 Nov 2009 02:12:02 GMT

 date_ddmmyy

    Returns date in this format "dd-mm-yy" (28-02-10)

 date_ddmmyyyy

    Returns date in this format "dd-mm-yyyy" (28-02-2010)

 date_yyyymmdd

    Returns date in this format "yyyy-mm-dd" (2010-03-02)

 datetime_yyyymmdd_hhmmss

    Returns: "yyyy-mm-dd hh:mm:ss" (2010-03-02 05:09:40)

 datetime_iso8601 iso8601

    Since all internal representations are in UTC Returns
    "yyyy-mm-ddThh:mm:ssZ" (2010-02-02T05:09:40Z)

 datetime_yyyymmdd_hhmmss_TZ

    Returns datetime in this format "yyyy-mm-dd hh:mm:ssGMT" (2010-03-02
    05:09:40GMT)

 days_in_month

 timezone_offset

    Returns a TimeInterval which represents the difference between UTC and
    the time in certain timezone

 is_dst_in_zone

    Returns a boolean which indicates whether a certain zone is in DST at
    the given epoch

 plus_time_interval

    Returns a new Date::Utility plus the supplied
    Time::Duration::Concise::Localize. Negative TimeIntervals will move
    backward.

    Will also attempt to create a TimeInterval from a supplied code, if
    possible.

 minus_time_interval

    Returns a new Date::Utility minus the supplied
    Time::Duration::Concise::Localize. Negative TimeIntervals will move
    forward.

    Will also attempt to create a TimeInterval from a supplied code, if
    possible.

 months_ahead

    Returns the month ahead or backward from the supplied month in the
    format of Mmm-yy. It could hanlde backward or forward move from the
    supplied month.

 move_to_nth_dow

    Takes an integer as an ordinal and a day of week representation

    The following are all equivalent: move_to_nth_dow(3, 'Monday')
    move_to_nth_dow(3, 'Mon') move_to_nth_dow(3, 1)

    Returning the 3rd Monday of the month represented by the object or
    undef if it does not exist.

    An exception is thrown on improper day of week representations.

STATIC METHODS

 month_number_to_abbrev

    Static method returns a standard mapping from month numbers to our 3
    character abbreviated format.

 month_abbrev_to_number

    Static method returns a standard mapping from 3 character abbreviated
    format to month numbers

STATIC METHODS

 month_number_to_fullname

    Static method returns a standard mapping from month numbers to
    fullname.

 is_epoch_timestamp

    Check if a given datetime is an epoch timestemp, i.e. an integer of
    under 14 digits.

 is_ddmmmyy

    Check if a given "date" is in dd-Mmm-yy format (e.g. 1-Oct-10)

 truncate_to_day

    Returns a Date::Utility object with the time part truncated out of it.

    For instance, '2011-12-13 23:24:25' will return a new Date::Utility
    object representing '2011-12-13 00:00:00'

 truncate_to_month

    Returns a Date::Utility object with the day and time part truncated out
    of it.

    For instance, '2011-12-13 23:24:25' will return a new Date::Utility
    object representing '2011-12-01 00:00:00'

 truncate_to_hour

    Returns a Date::Utility object with the minutes and seconds truncated
    out of it.

    For instance, '2011-12-13 23:24:25' will return a new Date::Utility
    object representing '2011-12-13 23:00:00'

 today

    Returns Date::Utility object for the start of the current day. Much
    faster than Date::Utility->new, as it will return the same object till
    the end of the day.

 plus_years

    Takes the following argument as named parameter:

      * years - number of years to be added. (Integer)

    Returns a new Date::Utility object plus the given years. If the day is
    greater than days in the new month, it will take the day of end month.
    e.g.

        print Date::Utility->new('2000-02-29')->plus_years(1)->date_yyyymmdd;
        # will print 2001-02-28

 minus_years

    Takes the following argument as named parameter:

      * years - number of years to be subracted. (Integer)

    Returns a new Date::Utility object minus the given years. If the day is
    greater than days in the new month, it will take the day of end month.
    e.g.

        print Date::Utility->new('2000-02-29')->minus_years(1)->date_yyyymmdd;
        # will print 1999-02-28

 plus_months

    Takes the following argument as named parameter:

      * years - number of months to be added. (Integer)

    Returns a new Date::Utility object plus the given months. If the day is
    greater than days in the new month, it will take the day of end month.
    e.g.

        print Date::Utility->new('2000-01-31')->plus_months(1)->date_yyyymmdd;
        # will print 2000-02-28

 minus_months

    Takes the following argument as named parameter:

      * years - number of months to be subracted. (Integer)

    Returns a new Date::Utility object minus the given months. If the day
    is greater than days in the new month, it will take the day of end
    month. e.g.

        print Date::Utility->new('2000-03-31')->minus_months(1)->date_yyyymmdd;
        # will print 2000-02-28

 create_trimmed_date

    Takes the following argument as named parameter:

      * year - calendar year of the date (Integer)

      * month - calendar month of the date. (Integer)

      * day - day of the month of the date. (Integer)

    Returns a valid Date::Utility object whose date part is same with the
    given year, month and day and time part is not changed. If the day is
    greater than the max day in that month , then use that max day as the
    day in the new object.

DEPENDENCIES

    Moose

    DateTime

    POSIX

    Scalar::Util

    Tie::Hash::LRU

    Time::Local

    Syntax::Keyword::Try

AUTHOR

    Binary.com, <support at binary.com>

BUGS

    Please report any bugs or feature requests to bug-date-utility at
    rt.cpan.org, or through the web interface at
    http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Date-Utility. I will be
    notified, and then you'll automatically be notified of progress on your
    bug as I make changes.

SUPPORT

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

        perldoc Date::Utility

    You can also look for information at:

      * RT: CPAN's request tracker (report bugs here)

      http://rt.cpan.org/NoAuth/Bugs.html?Dist=Date-Utility

      * AnnoCPAN: Annotated CPAN documentation

      http://annocpan.org/dist/Date-Utility

      * CPAN Ratings

      http://cpanratings.perl.org/d/Date-Utility

      * Search CPAN

      http://search.cpan.org/dist/Date-Utility/

LICENSE AND COPYRIGHT

    Copyright 2015 Binary.com.

    This program is free software; you can redistribute it and/or modify it
    under the terms of the the Artistic License (2.0). You may obtain a
    copy of the full license at:

    http://www.perlfoundation.org/artistic_license_2_0

    Any use, modification, and distribution of the Standard or Modified
    Versions is governed by this Artistic License. By using, modifying or
    distributing the Package, you accept this license. Do not use, modify,
    or distribute the Package, if you do not accept this license.

    If your Modified Version has been derived from a Modified Version made
    by someone other than you, you are nevertheless required to ensure that
    your Modified Version complies with the requirements of this license.

    This license does not grant you the right to use any trademark, service
    mark, tradename, or logo of the Copyright Holder.

    This license includes the non-exclusive, worldwide, free-of-charge
    patent license to make, have made, use, offer to sell, sell, import and
    otherwise transfer the Package with respect to any patent claims
    licensable by the Copyright Holder that are necessarily infringed by
    the Package. If you institute patent litigation (including a
    cross-claim or counterclaim) against any party alleging that the
    Package constitutes direct or contributory patent infringement, then
    this Artistic License to you shall terminate on the date that such
    litigation is filed.

    Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER
    AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES.
    THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
    PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY
    YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR
    CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR
    CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE,
    EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.