=encoding utf8

=for comment POD_DERIVED_INDEX_GENERATED
The following documentation is automatically generated.  Please do not edit
this file, but rather the original, inline with Date::Utility
at lib/Date/Utility.pm
(on the system that originally ran this).
If you do edit this file, and don't want your changes to be removed, make
sure you change the first line.

=cut

=head1 NAME

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

=head1 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');

=head1 DESCRIPTION

A class that represents a datetime in various format

=head1 ATTRIBUTES

=head2 second

=head2 minute

=head2 hour

=head2 day_of_month

=head2 month

=head2 quarter_of_year

=head2 day_of_week

    return day of week begin with 0

=head2 day_of_year

=head2 year

=head2 time

=head2 time_hhmm

Returns time in hh:mm format

=head2 time_hhmmss

Returns time in hh:mm:ss format

=head2 time_cutoff

Set the timezone for cutoff to UTC

=head2 year_in_two_digit

Returns year in two digit format. Example: 15

=head2 timezone

Set the timezone to GMT

=head2 datetime

See, db_timestamp

=head2 datetime_ddmmmyy_hhmmss_TZ

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

=head2 datetime_ddmmmyy_hhmmss

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

=head2 date_ddmmmyyyy

Returns date in dd-mmm-yyyy format

=head2 date_ddmonthyyyy

Returns date in dd-month-yyyy format

=head2 date

Returns datetime in YYYY-MM-DD format

=head2 date_ddmmmyy

Returns datetime in dd-Mmm-yy format

=head2 days_since_epoch

Returns number of days since 1970-01-01

=head2 seconds_after_midnight

Returns number of seconds after midnight of the same day.

=head2 is_a_weekend

=head2 is_a_weekday

=head2 new

Returns a Date::Utility object.

=head2 _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.

=head2 days_between

Returns number of days between two dates.

=head2 is_before

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

=head2 is_after

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

=head2 is_same_as

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

=head2 day_as_string

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

=head2 full_day_name

Returns the name of the current day. Example: Sunday

=head2 month_as_string

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

=head2 full_month_name

Returns the full name of current month. Example: January

=head2 http_expires_format

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

=head2 date_ddmmyy

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

=head2 date_ddmmyyyy

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

=head2 date_yyyymmdd

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

=head2 datetime_yyyymmdd_hhmmss

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

=head2 datetime_iso8601 iso8601

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

=head2 datetime_yyyymmdd_hhmmss_TZ

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

=head2 days_in_month

=head2 timezone_offset

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

=head2 is_dst_in_zone

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

=head2 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.

=head2 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.

=head2 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.

=head2 move_to_nth_dow

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

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

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

An exception is thrown on improper day of week representations.

=head1 STATIC METHODS

=head2 month_number_to_abbrev

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

=head2 month_abbrev_to_number

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

=head1 STATIC METHODS

=head2 month_number_to_fullname

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

=head2 is_epoch_timestamp

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

=head2 is_ddmmmyy

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

=head2 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'

=head2 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'

=head2 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'

=head2 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.

=head2 plus_years

Takes the following argument as named parameter:

=over 4

=item * C<years> - number of years to be added. (Integer)

=back

Returns a new L<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

=head2 minus_years

Takes the following argument as named parameter:

=over 4

=item * C<years> - number of years to be subracted. (Integer)

=back

Returns a new L<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

=head2 plus_months

Takes the following argument as named parameter:

=over 4

=item * C<years> - number of months to be added. (Integer)

=back

Returns a new L<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

=head2 minus_months

Takes the following argument as named parameter:

=over 4

=item * C<years> - number of months to be subracted. (Integer)

=back

Returns a new L<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

=head2 create_trimmed_date

Takes the following argument as named parameter:

=over 4

=item * C<year> - calendar year of the date (Integer)

=item * C<month> - calendar month of the date. (Integer)

=item * C<day> - day of the month of the date. (Integer)

=back

Returns a valid L<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.

=head1 DEPENDENCIES

=over 4

=item L<Moo>

=item L<DateTime>

=item L<POSIX>

=item L<Scalar::Util>

=item L<Time::Local>

=item L<Syntax::Keyword::Try>

=back

=head1 AUTHOR

Binary.com, C<< <support at binary.com> >>

=head1 BUGS

Please report any bugs or feature requests to C<bug-date-utility at rt.cpan.org>, or through
the web interface at L<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.

=head1 SUPPORT

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

    perldoc Date::Utility

You can also look for information at:

=over 4

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

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

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Date-Utility>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Date-Utility>

=item * Search CPAN

L<http://search.cpan.org/dist/Date-Utility/>

=back

=head1 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:

L<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.

=head1 INHERITED METHODS

=over 4

=item L<Moo::Object>

L<BUILDALL|Moo::Object/BUILDALL>, L<DEMOLISHALL|Moo::Object/DEMOLISHALL>, L<does|Moo::Object/does>, L<meta|Moo::Object/meta>

=back

