The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

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

Moo
DateTime
POSIX
Scalar::Util
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:

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.

INHERITED METHODS

Moo::Object

BUILDALL, DEMOLISHALL, does, meta