man > DateTime

man perldoc info pydoc3 ri search

📛 NAME

DateTime - A date and time object for Perl

🏷️ VERSION

version 1.55

🚀 Quick Reference

Use Case	Command	Description
Create a DateTime	DateTime->new(year => ..., month => ..., ...)	Create a new datetime object from components.
Create from epoch	DateTime->from_epoch(epoch => time)	Create a datetime object from a Unix timestamp.
Get current datetime	DateTime->now	Returns a DateTime object for the current time.
Get year/month/day	$dt->year, $dt->month, $dt->day	Access individual date components.
Get hour/minute/second	$dt->hour, $dt->minute, $dt->second	Access individual time components.
Format as ISO8601	$dt->iso8601	Returns something like 2022-02-06T12:00:00.
Add duration	$dt->add(days => 1)	Add a duration to the datetime.
Subtract duration	$dt->subtract(hours => 3)	Subtract a duration from the datetime.
Difference between dates	$dt1 - $dt2	Returns a DateTime::Duration object.
Set time zone	$dt->set_time_zone('America/Chicago')	Change the time zone of the object.

📋 SYNOPSIS

use DateTime;

$dt = DateTime->new(
    year       => 1964,
    month      => 10,
    day        => 16,
    hour       => 16,
    minute     => 12,
    second     => 47,
    nanosecond => 500000000,
    time_zone  => 'Asia/Taipei',
);

$dt = DateTime->from_epoch( epoch => $epoch );
$dt = DateTime->now;    # same as ( epoch => time )

$year  = $dt->year;
$month = $dt->month;        # 1-12
$day   = $dt->day;          # 1-31
$dow   = $dt->day_of_week;  # 1-7 (Monday is 1)

$hour   = $dt->hour;        # 0-23
$minute = $dt->minute;      # 0-59
$second = $dt->second;      # 0-61 (leap seconds!)

# ... and many more methods ...
$ymd = $dt->ymd;         # 2002-12-06
$hms = $dt->hms;         # 14:02:29

$dt2 = $dt + $duration_object;
$dt3 = $dt - $duration_object;
$duration_object = $dt - $dt2;

$dt->set( year => 1882 );
$dt->set_time_zone('America/Chicago');
$dt->set_formatter($formatter);

📝 DESCRIPTION

DateTime is a class for the representation of date/time combinations, and is part of the Perl DateTime project.

It represents the proleptic Gregorian calendar. The first day of the calendar (the epoch), is the first day of year 1, which corresponds to the date which was (incorrectly) believed to be the birth of Jesus Christ.

The calendar represented does have a year 0, and in that way differs from how dates are often written using "BCE/CE" or "BC/AD".

For infinite datetimes, please see the DateTime::Infinite module.

⚙️ USAGE

🔢 0-based Versus 1-based Numbers

Month, day of month, day of week, and day of year are 1-based. Any method that is 1-based also has an equivalent 0-based method ending in "_0". For example, this class provides both "day_of_week" and "day_of_week_0" methods. The "day_of_week_0" method still treats Monday as the first day of the week.

All time-related numbers such as hour, minute, and second are 0-based. Years are neither, as they can be both positive or negative. There is a year 0. There is no "quarter_0" method.

⚠️ Error Handling

Some errors may cause this module to die with an error string. This can only happen when calling constructor methods, methods that change the object, such as "set", or methods that take parameters. Methods that retrieve information about the object, such as "year" or "epoch", will never die.

🌐 Locales

All the object methods which return names or abbreviations return data based on a locale. This is done by setting the locale when constructing a DateTime object. If this is not set, then "en-US" is used.

🪐 Floating DateTimes

The default time zone for new DateTime objects, except where stated otherwise, is the "floating" time zone. A floating datetime is one which is not anchored to any particular time zone. In addition, floating datetimes do not include leap seconds, since we cannot apply them without knowing the datetime's time zone.

The results of date math and comparison between a floating datetime and one with a real time zone are not really valid. If you are planning to use any objects with a real time zone, it is strongly recommended that you do not mix these with floating datetimes.

🧮 Math

If you are going to be doing date math, please read the section "How DateTime Math Works".

🐢 Determining the Local Time Zone Can Be Slow

If $ENV{TZ} is not set, it may involve reading a number of files in /etc or elsewhere. If you know that the local time zone won't change while your code is running, and you need to make many objects for the local time zone, it is strongly recommended that you retrieve the local time zone once and cache it:

our $App::LocalTZ = DateTime::TimeZone->new( name => 'local' );

DateTime itself does not do this internally because local time zones can change, and there's no good way to determine if it's changed without doing all the work to look it up.

🔮 Far Future DST

Do not try to use named time zones (like "America/Chicago") with dates very far in the future (thousands of years). The current implementation of "DateTime::TimeZone" will use a huge amount of memory calculating all the DST changes from now until the future date. Use UTC or the floating time zone and you will be safe.

🌍 Globally Setting a Default Time Zone

Warning: This is very dangerous. Do this at your own risk!

By default, "DateTime" uses either the floating time zone or UTC for newly created objects, depending on the constructor. You can force "DateTime" to use a different time zone by setting the "PERL_DATETIME_DEFAULT_TZ" environment variable. Before setting this variable, you are strongly encouraged to audit your CPAN dependencies to see how they use "DateTime".

📏 Upper and Lower Bounds

Internally, dates are represented the number of days before or after 0001-01-01. This is stored as an integer, meaning that the upper and lower bounds are based on your Perl's integer size ($Config{ivsize}). The limit on 32-bit systems is around 2^29 days, which gets you to year (+/-)1,469,903. On a 64-bit system you get 2^62 days, to year (+/-)12,626,367,463,883,278.

🛠️ METHODS

🏗️ Constructors

All constructors can die when invalid parameters are given.

🔸 Warnings

Currently, constructors will warn if you try to create a far future DateTime (year >= 5000) with any time zone besides floating or UTC. All warnings from DateTime use the "DateTime" category and can be suppressed with:

no warnings 'DateTime';

🔸 DateTime->new( ... )

This class method accepts the following parameters (defaults are 1, 1, 0, 0, 0, 0, 'floating', 'en-US'):

• year — Required. An integer year for the DateTime.
• month — An integer from 1-12.
• day — An integer from 1-31. The value will be validated based on the month.
• hour — An integer from 0-23.
• minute — An integer from 0-59.
• second — An integer from 0-61. Values of 60 or 61 are only allowed for leap seconds.
• nanosecond — An integer that is greater than or equal to 0. If greater than 1 billion, it will be normalized into the second value.
• locale — A string containing a locale code, or an object returned by "DateTime::Locale->load".
• time_zone — A string containing a time zone name or a DateTime::TimeZone object.
• formatter — An object or class name with a "format_datetime" method.

🔸 Parsing Dates

This module does not parse dates! Instead, take a look at the various DateTime::Format::* modules on CPAN.

🔸 Ambiguous Local Times

Because of Daylight Saving Time, it is possible to specify a local time that is ambiguous. If you specify an ambiguous time, then the latest UTC time is always used, in effect always choosing standard time. You can subtract an hour from the object to move to saving time.

🔸 Invalid Local Times

Certain local times just do not exist due to DST transitions (e.g., 02:00:00 on April 6, 2003 in the US). Attempting to create an invalid time currently causes a fatal error.

🔸 DateTime->from_epoch( epoch => $epoch, ... )

This class method constructs a new DateTime object from an epoch time. It accepts "time_zone", "locale", and "formatter" parameters. By default, the returned object will be in the UTC time zone. If you pass a "time_zone", this time zone will be applied after the object is constructed.

🔸 DateTime->now( ... )

This class method is equivalent to calling "from_epoch" with the value returned from Perl's "time" function. For sub-second resolution, use the DateTime::HiRes module.

🔸 DateTime->today( ... )

This class method is equivalent to:

DateTime->now(@_)->truncate( to => 'day' );

🔸 DateTime->last_day_of_month( ... )

This constructor takes the same arguments as the "new" method, except for "day". Both "year" and "month" are required.

🔸 DateTime->from_day_of_year( ... )

This constructor takes the same arguments as the "new" method, except it does not accept a "month" or "day" argument. Instead, it requires both "year" and "day_of_year".

🔸 DateTime->from_object( object => $object, ... )

This class method constructs a new DateTime object from any object that implements the "utc_rd_values" method.

🔸 $dt->clone

This object method returns a new object that is replica of the object upon which the method is called.

🔍 "Get" Methods

This class has many methods for retrieving information about an object.

• $dt->year — Returns the year.
• $dt->ce_year — Returns the year according to the BCE/CE numbering system.
• $dt->era_name — Returns the long name of the current era, something like "Before Christ".
• $dt->era_abbr — Returns the abbreviated name of the current era, something like "BC".
• $dt->christian_era — Returns a string, either "BC" or "AD", according to the year.
• $dt->secular_era — Returns a string, either "BCE" or "CE", according to the year.
• $dt->year_with_era — Returns a string containing the year immediately followed by the appropriate era abbreviation.
• $dt->month (also $dt->mon) — Returns the month of the year, from 1..12.
• $dt->month_name — Returns the name of the current month.
• $dt->month_abbr — Returns the abbreviated name of the current month.
• $dt->day (also $dt->mday, $dt->day_of_month) — Returns the day of the month, from 1..31.
• $dt->day_of_week (also $dt->wday, $dt->dow) — Returns the day of the week as a number, from 1..7, with 1 being Monday and 7 being Sunday.
• $dt->local_day_of_week — Returns the day of the week as a number, from 1..7. The day corresponding to 1 will vary based on the locale.
• $dt->day_name — Returns the name of the current day of the week.
• $dt->day_abbr — Returns the abbreviated name of the current day of the week.
• $dt->day_of_year (also $dt->doy) — Returns the day of the year.
• $dt->quarter — Returns the quarter of the year, from 1..4.
• $dt->quarter_name — Returns the name of the current quarter.
• $dt->quarter_abbr — Returns the abbreviated name of the current quarter.
• $dt->day_of_quarter (also $dt->doq) — Returns the day of the quarter.
• $dt->weekday_of_month — Returns a number from 1..5 indicating which week day of the month this is.
• $dt->ymd($sep), $dt->mdy($sep), $dt->dmy($sep) — Returns the year, month, and day, in the order indicated. Zero-padded.
• $dt->hour — Returns the hour of the day, from 0..23.
• $dt->hour_1 — Returns the hour of the day, from 1..24.
• $dt->hour_12 — Returns the hour of the day, from 1..12.
• $dt->hour_12_0 — Returns the hour of the day, from 0..11.
• $dt->am_or_pm — Returns the appropriate localized abbreviation (AM/PM).
• $dt->minute (also $dt->min) — Returns the minute of the hour, from 0..59.
• $dt->second (also $dt->sec) — Returns the second, from 0..61.
• $dt->fractional_second — Returns the second as a real number.
• $dt->millisecond — Returns the fractional part of the second as milliseconds.
• $dt->microsecond — Returns the fractional part of the second as microseconds.
• $dt->nanosecond — Returns the fractional part of the second as nanoseconds.
• $dt->hms($sep) (also $dt->time) — Returns the hour, minute, and second, zero-padded.
• $dt->datetime($sep) (also $dt->iso8601) — Equivalent to $dt->ymd('-') . 'T' . $dt->hms(':').
• $dt->rfc3339 — Formats a datetime in RFC3339 format.
• $dt->stringify — Returns a stringified version of the object.
• $dt->is_leap_year — Returns a boolean indicating whether or not the datetime is in a leap year.
• $dt->is_last_day_of_month — Returns a boolean.
• $dt->is_last_day_of_quarter — Returns a boolean.
• $dt->is_last_day_of_year — Returns a boolean.
• $dt->month_length — Returns the number of days in the current month.
• $dt->quarter_length — Returns the number of days in the current quarter.
• $dt->year_length — Returns the number of days in the current year.
• $dt->week — Returns ($week_year, $week_number).
• $dt->week_year — Returns the year of the week.
• $dt->week_number — Returns the week of the year, from 1..53.
• $dt->week_of_month — The week of the month, from 0..5.
• $dt->jd, $dt->mjd — Returns the Julian Day and Modified Julian Day.
• $dt->time_zone — Returns the DateTime::TimeZone object.
• $dt->offset — Returns the offset from UTC, in seconds.
• $dt->is_dst — Returns a boolean indicating DST.
• $dt->time_zone_long_name — Shortcut for $dt->time_zone->name.
• $dt->time_zone_short_name — Returns the time zone abbreviation (e.g., "PST").
• $dt->strftime( $format, ... ) — Implements strftime.
• $dt->format_cldr( $format, ... ) — Implements CLDR date formatting.
• $dt->epoch — Returns the UTC epoch value (integer seconds).
• $dt->is_finite, $dt->is_infinite — Distinguish normal from infinite datetimes.
• $dt->utc_rd_values — Returns UTC Rata Die days, seconds, and nanoseconds.
• $dt->leap_seconds — Returns the number of leap seconds up to the datetime.
• $dt->locale — Returns the datetime's DateTime::Locale object.
• $dt->formatter — Returns the current formatter object or class.

✏️ "Set" Methods

The remaining methods, except where otherwise specified, return the object itself, thus making method chaining possible.

🔸 $dt->set( .. )

This method can be used to change the local components of a date time. It accepts any parameter allowed by the "new" method except for "locale" or "time_zone". Do not use this method to do date math. Use the "add" and "subtract" methods instead.

🔸 $dt->set_year, $dt->set_month, etc.

DateTime has a "set_*" method for every item that can be passed to the constructor. These are shortcuts to calling "set" with a single key.

🔸 $dt->truncate( to => ... )

This method allows you to reset some of the local time components to their "zero" values. The "to" parameter may be one of "year", "quarter", "month", "week", "local_week", "day", "hour", "minute", or "second".

🔸 $dt->set_locale($locale)

Sets the object's locale.

🔸 $dt->set_time_zone($tz)

This method accepts either a time zone object or a string. If the new time zone's offset is different, the local time is adjusted accordingly.

🔸 $dt->set_formatter($formatter)

Sets the formatter for the object. See "Formatters And Stringification" for details.

🧮 Math Methods

Like the set methods, math related methods always return the object itself.

🔸 $dt->add_duration($duration_object)

This method adds a DateTime::Duration to the current datetime.

🔸 $dt->add( parameters for DateTime::Duration )

Syntactic sugar around $dt->add_duration.

🔸 $dt->subtract_duration($duration_object)

Inverts the duration and adds it.

🔸 $dt->subtract( parameters )

Syntactic sugar for $dt->subtract_duration.

🔸 $dt->subtract_datetime($datetime)

Returns a new DateTime::Duration object representing the difference between the two dates. The duration is relative.

🔸 $dt->delta_md($datetime), $dt->delta_days($datetime)

Each returns a new DateTime::Duration object representing some portion of the difference. These methods always return a positive duration.

🔸 $dt->delta_ms($datetime)

Returns a duration which contains only minutes and seconds. Always positive.

🔸 $dt->subtract_datetime_absolute($datetime)

Returns a new DateTime::Duration object representing the difference in seconds and nanoseconds. This is the only way to accurately measure the absolute amount of time between two datetimes.

🔸 $dt->is_between( $lower, $upper )

Checks whether $dt is strictly between two other DateTime objects.

📦 Class Methods

🔸 DateTime->DefaultLocale($locale)

Specify the default locale to be used when creating DateTime objects. If unset, then "en-US" is used.

🔸 DateTime->compare( $dt1, $dt2 ), DateTime->compare_ignore_floating( $dt1, $dt2 )

Compares two DateTime objects. Returns -1, 0, 1 as with Perl's "sort" function. compare_ignore_floating treats floating time zones as UTC for consistent sorting.

🧪 Testing Code That Uses DateTime

You can override "CORE::GLOBAL::time" before loading DateTime, or override "DateTime::_core_time":

no warnings 'redefine';
local *DateTime::_core_time = sub { return 42 };

🧠 How DateTime Math Works

🔸 Making Things Simple

• Use the floating time zone.
• Use UTC for all calculations.
• Convert to UTC for math, then back to local for presentation.
• Use $dt->delta_days for date-only math.
• Never do math on two objects where only one is in the floating time zone.

🔸 Adding a Duration to a DateTime

DateTime always adds (or subtracts) days, then months, minutes, and then seconds and nanoseconds. If there are any boundary overflows, these are normalized at each step. This means that adding one month and one day to February 28, 2003 will produce the date April 1, 2003, not March 29, 2003.

🔸 DateTime Subtraction

Date subtraction is done based solely on the two object's local datetimes, with one exception to handle DST changes. If the two objects are in different time zones, one is converted to the other's time zone first.

🔸 Reversibility

Date math operations are not always reversible due to the order of addition operations. Adding 1 day and 3 minutes in one call is not the same as first adding 3 minutes and then 1 day.

🔸 Leap Seconds and Date Math

The presence of leap seconds can cause anomalies. For example, the last minute of 1972-12-31 contains 61 seconds. Adding 1 minute is different from adding 60 seconds on that date.

🔸 Local vs. UTC and 24 hours vs. 1 day

When math crosses a DST boundary, a single day may have more or less than 24 hours. Converting to UTC before math avoids these issues.

🔗 Overloading

This module explicitly overloads the addition (+), subtraction (-), string and numeric comparison operators.

my $new_dt = $dt + $duration_obj;
my $new_dt = $dt - $duration_obj;
my $duration_obj = $dt - $new_dt;
for my $dt ( sort @dts ) {...}

Using "==" or "<=>" to compare a DateTime object with a non-DateTime object will result in an exception. Use sort { $a cmp $b } @dates to safely sort mixed lists.

🎨 Formatters And Stringification

You can optionally specify a "formatter", usually a "DateTime::Format::*" object or class, to control the stringification of the DateTime object.

my $formatter = DateTime::Format::Strptime->new(...);
my $dt        = DateTime->new( year => 2004, formatter => $formatter );
$dt->set_formatter($formatter);
$formatter = $dt->formatter;

Once set, the overloaded stringification method will use the formatter. If unspecified, the "iso8601" method is used.

📜 CLDR Patterns

The CLDR pattern language is more powerful and complex than strftime. Patterns are simply letters without any prefix. Surround literal text with single quotes ('').

• G{1,3} — The abbreviated era (BC, AD).
• GGGG — The wide era (Before Christ, Anno Domini).
• y and y{3,} — The year, zero-prefixed as needed.
• yy — A special case that always produces a two-digit year.
• Y{1,} — The year in "week of the year" calendars.
• u{1,} — Same as "y" except that "uu" is not a special case.
• Q{1,2} — The quarter as a number (1..4).
• QQQ — The abbreviated format form for the quarter.
• QQQQ — The wide format form for the quarter.
• M{1,2} — The numerical month.
• MMM — The abbreviated format form for the month.
• MMMM — The wide format form for the month.
• MMMMM — The narrow format form for the month.
• w{1,2} — The week of the year.
• W — The week of the month.
• d{1,2} — The numeric day of the month.
• D{1,3} — The numeric day of the year.
• F — The day of the week in the month.
• g{1,} — The modified Julian day.
• E{1,3} and eee — The abbreviated format form for the day of the week.
• EEEE and eeee — The wide format form for the day of the week.
• e{1,2} — The local numeric day of the week.
• c — The numeric day of the week from 1 to 7, Monday is 1.
• a — The localized form of AM or PM.
• h{1,2} — The hour from 1-12.
• H{1,2} — The hour from 0-23.
• K{1,2} — The hour from 0-11.
• k{1,2} — The hour from 1-24.
• j{1,2} — The hour, in 12 or 24 hour form, based on the locale.
• m{1,2} — The minute.
• s{1,2} — The second.
• S{1,} — The fractional portion of the seconds.
• A{1,} — The millisecond of the day.
• z{1,3} — The time zone short name.
• zzzz — The time zone long name.
• Z{1,3} — The time zone offset.
• ZZZZZ — The time zone offset as a sexagesimal number (e.g., "-05:00").

🕰️ strftime Patterns

• %a — The abbreviated weekday name.
• %A — The full weekday name.
• %b — The abbreviated month name.
• %B — The full month name.
• %c — The default datetime format for the object's locale.
• %C — The century number.
• %d — The day of the month as a decimal number (01-31).
• %D — Equivalent to %m/%d/%y.
• %e — Like %d, but a leading zero is replaced by a space.
• %F — Equivalent to %Y-%m-%d.
• %G — The ISO 8601 year with century.
• %g — Like %G, but without century.
• %H — The hour as a decimal number using a 24-hour clock (00-23).
• %I — The hour as a decimal number using a 12-hour clock (01-12).
• %j — The day of the year as a decimal number (001-366).
• %m — The month as a decimal number (01-12).
• %M — The minute as a decimal number (00-59).
• %n — A newline character.
• %N — The fractional seconds digits.
• %p — Either `AM' or `PM'.
• %P — Like %p but in lowercase.
• %r — The time in a.m. or p.m. notation.
• %R — The time in 24-hour notation.
• %s — The number of seconds since the epoch.
• %S — The second as a decimal number (00-61).
• %t — A tab character.
• %T — The time in 24-hour notation.
• %u — The day of the week as a decimal, Monday being 1.
• %U — The week number of the current year.
• %V — The ISO 8601 week number.
• %w — The day of the week as a decimal, Sunday being 0.
• %W — The week number of the current year.
• %x — The default date format for the object's locale.
• %X — The default time format for the object's locale.
• %y — The year as a decimal number without a century.
• %Y — The year as a decimal number including the century.
• %z — The time-zone as hour offset from UTC.
• %Z — The time zone abbreviation.
• %% — A literal `%' character.
• %{method} — Any method name.

💾 DateTime and Storable

"DateTime" implements Storable hooks in order to reduce the size of a serialized "DateTime" object.

🛠️ DEVELOPMENT TOOLS

If you're working on the code base, there are a few extra non-Perl tools that you may find useful, notably precious, a meta-linter/tidier. Run "precious tidy -a" to tidy all tidyable files, and "precious lint -a" to run all lint checks.

🌳 THE DATETIME PROJECT ECOSYSTEM

This module is part of a larger ecosystem of modules in the DateTime family.

📄 Format Modules

Parse and format datetimes. All start with DateTime::Format::.

📅 Calendar Modules

Implement non-Gregorian calendars. All start with DateTime::Calendar::.

📆 Event Modules

Calculate dates for events. All start with DateTime::Event::.

➕ Others

Many other modules work with DateTime, including modules in the DateTimeX namespace.

🐛 KNOWN BUGS

The tests in 20infinite.t seem to fail on some machines, particularly on Win32. This appears to be related to Perl's internal handling of IEEE infinity and NaN.

🔗 SEE ALSO

A Date with Perl (presentation). datetime AT perl.org mailing list.

📞 SUPPORT

Bugs may be submitted at GitHub. There is a mailing list available for users of this distribution.

📂 SOURCE

The source code repository for DateTime can be found at GitHub.

❤️ DONATIONS

If you'd like to thank me for the work I've done on this module, please consider making a "donation" to me via PayPal.

✍️ AUTHOR

Dave Rolsky

👥 CONTRIBUTORS

Ben Bennett, Christian Hansen, Daisuke Maki, Dan Book, Dan Stewart, David Dyck, David E. Wheeler, David Precious, Doug Bell, Flávio Soibelmann Glock, Gianni Ceccarelli, Gregory Oschwald, Hauke D, Iain Truskett, Jason McIntosh, Joshua Hoblitt, Karen Etheridge, Mark Overmeer, Michael Conrad, Michael R. Davis, Mohammad S Anwar, M Somerville, Nick Tonkin, Olaf Alders, Ovid, Paul Howarth, Philippe Bruhat (BooK), philip r brenan, Ricardo Signes, Richard Bowen, Ron Hill, Sam Kington, viviparous

©️ COPYRIGHT AND LICENSE

This software is Copyright (c) 2003 - 2021 by Dave Rolsky. This is free software, licensed under: The Artistic License 2.0 (GPL Compatible).

📛 NAME 🏷️ VERSION 🚀 Quick Reference 📋 SYNOPSIS 📝 DESCRIPTION ⚙️ USAGE 🛠️ METHODS 🛠️ DEVELOPMENT TOOLS 🌳 THE DATETIME PROJECT ECOSYSTEM 🐛 KNOWN BUGS 🔗 SEE ALSO 📞 SUPPORT 📂 SOURCE ❤️ DONATIONS ✍️ AUTHOR 👥 CONTRIBUTORS ©️ COPYRIGHT AND LICENSE