perldoc > Date::Manip::Date

man perldoc info pydoc3 ri search

📖 NAME

Date::Manip::Date — Methods for working with dates

🚀 Quick Reference

Use Case	Command	Description
Create a new date object	$date = new Date::Manip::Date;	📦 Instantiate a date object
Parse a date string	$date->parse($string)	🔤 Parse date/time from string
Convert time zone	$date->convert($zone)	🌍 Convert to another time zone
Compare two dates	$date1->cmp($date2)	⚖️ Returns -1, 0, or 1
Add/subtract delta	$date->calc($delta)	➕➖ Date arithmetic
Get date value	$date->value()	📤 Return YYYYMMDDHH:MN:SS
Format date with printf	$date->printf($format)	🎨 Custom output formatting
Check if holiday	$date->holiday()	🎉 Returns holiday name or undef
Check if business day	$date->is_business_day()	💼 Returns 1 if business day
Get seconds since epoch	$date->secs_since_1970_GMT()	⏱️ Unix timestamp
Set date fields	$date->set($field, @vals)	✏️ Explicitly set date components
Parse with custom format	$date->parse_format($format, $string)	🔍 Match using printf-like directives

📋 SYNOPSIS

use Date::Manip::Date;
$date = new Date::Manip::Date;

📝 DESCRIPTION

This module works specifically with date objects.

Although the word date is used extensively here, it is actually somewhat misleading. Date::Manip works with the full calendar date (year, month, day, and week when appropriate), time of day (hour, minute, second), and time zone. It doesn't work with fractional seconds.

🔧 METHODS

base, config, err, is_date, is_delta, is_recur, new, new_config, new_date, new_delta, new_recur, tz

Please refer to the Date::Manip::Obj documentation for these methods.

calc

$date2 = $date->calc($delta [,$subtract]);
$delta = $date->calc($date2 [,$subtract] [,$mode]);

Please refer to the Date::Manip::Calc documentation for details.

cmp

$val = $date1->cmp($date2);

⚖️ This compares two different dates (both of which must be valid date objects). It returns -1, 0, or 1 similar to the cmp or <=> operators in perl. The comparison will automatically handle time zone differences between the two dates (i.e. they will be sorted in order as they appear in the GMT zone).

⚠️ A warning is printed if either of the date objects does not include a valid date.

complete

$flag = $date->complete([$field]);

🔍 This tests the date stored in the object to see if it is complete or truncated (see below for a discussion of this).

• If no $field is passed in, it returns 1 if the date is complete, or 0 if it was truncated and default values have been supplied.
• If $field is passed in, it may be one of: m, d, h, mn, s. It will return 1 if the value for that field was specified, or 0 if a default was used.

convert

$err = $date->convert([$zone]);

🌍 This converts the date stored in the object to a different time zone. $zone can be the name of a time zone. If it is not passed in, the date is converted to the local time zone.

holiday

$name = $date->holiday();
@name = $date->holiday();
$name = $date->event();

🎉 This returns the name of the holiday if $date is a holiday. If $date is not a holiday, undef is returned. If $date is an unnamed holiday, an empty string is returned.

In scalar context, holiday returns the name of one holiday that occurs on that date (the one first defined in the config file). In list context, it returns all holidays on that date.

input

$str = $date->input();

📥 This returns the string that was parsed to form the date.

is_business_day

$flag = $date->is_business_day($checktime);

💼 This returns 1 if $date is a business day.

$checktime may be passed in. If it is non-zero, the time is checked to see if the date is a business day and falls within work hours.

list_holidays

@date = $date->list_holidays([$y]);

📅 This returns a list of Date::Manip::Date objects containing all dates during a year which are holidays. The times will all be 00:00:00.

If $y is not passed in, it will list the holidays in the same year as the date stored in $date (if any) or in the current year otherwise.

list_events

@list = $date->list_events(       [$format] );
@list = $date->list_events(0      [,$format]);
@list = $date->list_events($date1 [,$format]);

📋 This returns a list of events. Events are defined in the Events section of the config file (discussed in the Date::Manip::Holidays manual).

• In the first form, a list of all events active at the precise time stored in $date will be returned.
• If the first argument evaluates to 0, a list of all events active at any time during that day (Y,M,D) are returned.
• If the first argument is another date object, all events that are active at any time between the two dates (inclusive) are returned.

By default, the list returned is of the form:

( [START, END, NAME],
  [START, END, NAME],
  ...
)

where START is a date object when an event starts, END is a date object when it ends, and NAME is the name of the event. Note that START and END are the actual start and end date of the event and may be outside the range of dates being examined (though the event will obviously overlap the range or it wouldn't be included in the list).

If $format is included, it can specify an alternate format for the output. Currently, the only supported format is named "dates" and it returns a list in the form:

( [DATE1, NAME1a, NAME1b, ...],
  [DATE2, NAME2a, NAME2b, ...],
  ...
)

This includes a list of all dates during the range when there is a change in what events are active. DATE1 will always be the start of the range being considered, and (NAME1a, NAME1b, ...) are the list of all events that will be active at that time. At DATE2, the list of active events changes with (NAME2a, NAME2b, ...) being active.

It is quite possible that a date be included which has no active events, and in that case, the list of names will be empty.

nearest_business_day

$date->nearest_business_day([$tomorrowfirst]);

📍 This looks for the work day nearest to $date. If $date is a work day, it is left unmodified. Otherwise, it will look forward or backwards in time 1 day at a time until a work day is found. If $tomorrowfirst is non-zero (or if it is omitted and the config variable TomorrowFirst is non-zero), we look to the future first. Otherwise, we look in the past first. In other words, in a normal week, if $date is Wednesday, $date is returned. If $date is Saturday, Friday is returned. If $date is Sunday, Monday is returned. If Wednesday is a holiday, Thursday is returned if $tomorrowfirst is non-nil or Tuesday otherwise.

next_business_day / prev_business_day

$date->next_business_day($off [,$checktime]);
$date->prev_business_day($off [,$checktime]);

➡️ The next_business_day method sets the given date to $off (which can be a positive integer or zero) business days in the future. The prev_business_day method sets the date to $off business days in the past.

First, $date is tested. If $checktime is nonzero, the date must fall on a business date, and during business hours. If $checktime is zero, the time check is not done, and the date must simply fall on a business date.

If the check fails, the date is moved to the start of the next business day (if $checktime is nonzero) or the next business day at the current time (if $checktime is zero). Otherwise, it is left unmodified.

Next, if $off is greater than 0, the day $off work days from now is determined.

⚠️ One thing to note for the prev_business_day method is that if $date check fails, the date is set to the next business date, exactly like next_business_day. In other words, if $date is not a business day, the call:

$date->prev_business_day(0 [,$checktime]);

moves $date forward in time instead of backward which is nonintuitive, but you just have to think of day 0 as being the next business day if $date is not a business day.

As a result, the following two calls ALWAYS give the same result:

$date->next_business_day(0 [,$checktime]);
$date->prev_business_day(0 [,$checktime]);

no matter what date is stored in $date.

parse

$err = $date->parse($string [,@opts]);

🔤 This parses a string which should include a valid date and stores it in the object. If the string does not include a valid date, an error is returned. Use the err method to see the full error message.

A full date may include a calendar date (year, month, day), a time of day (hour, minute, second), and time zone information. All of this can be entered in many different formats.

For information on valid date formats, refer to the section VALID DATE FORMATS. For information on valid time zone information, refer to the section VALID TIME ZONE FORMATS.

If no time zone information is included in the date, it is treated as being in the local time zone.

If time zone information is included, the date will be kept in that time zone, and all operations will be done in that time zone. The convert method can be used to change the time zone to the local time zone, or to another time zone.

Some things to note:

• All strings are case insensitive. "December" and "DEceMBer" are equivalent.
• When a part of the date is not given, defaults are used. This is described below in the section "Complete vs. truncated dates and times".
• The year may be entered as 2 or 4 digits. If entered as 2 digits, it will be converted to a 4 digit year. There are several ways to do this based on the value of the YYtoYYYY config variable. Refer to the Date::Manip::Config documentation for more details.
• Dates are always checked to make sure they are valid.

If any other arguments are passed in, they act as options which may improve the speed of parsing. These include:

• noiso8601 — Do not try to parse the date as an ISO 8601 date or time.
• nodow — Do not try to parse a day-of-week (Monday) in the string.
• nocommon — Do not try to parse the date using the formats in the "Common date formats" section.
• noother — Do not try to parse the date using the "Less common date formats" or a time using the "Other time formats".
• nospecial — Do not try to parse the date using the "Special date strings" formats or a time using the "Special time strings" formats, or as a combined date/time using the "Additional combined date and time" formats.
• nodelta — Do not treat deltas as a date relative to now.
• noholidays — Do not parse holiday names as dates.

parse_date

$err = $date->parse_date($string [,@opts]);

📅 This parses a string which contains a valid date and sets the date part of the object.

If the object contained a valid date, the time is kept unchanged. If the object did NOT contain a valid date, a time of 00:00:00 is used.

@opts can be any of the strings described in the parse method above.

parse_time

$err = $date->parse_time($string [,@opts]);

⏰ This parses a string and sets the time portion of $date to contain it.

If the object contained a valid date, the Y/M/D portion is left unchanged. Otherwise, the current date is used.

@opts can be 'noiso8601' or 'noother'.

parse_format

$err          = $date->parse_format($format,$string);
($err,%match) = $date->parse_format($format,$string);

🔍 This will parse a date contained in $string based on explicit format information contained in $format.

If the format is invalid, $err will contain an error message. If the format is valid, but string doesn't match, an error code of 1 is returned.

If called in array context, a hash will be returned containing %+. This is primarily useful if the $format string contains some named capture groups that you define. This is discussed below.

$format is a string containing a regular expression with some special directives (based on the printf directives). These directives are turned into regular expression components, and then the entire string is turned into a regular expression which, if $string matches it, will return the date.

The directives available are identical to the printf directives. So, if your $format string contains the directive '%Y', it will match a 4-digit year.

All of the printf directives are available here with a few caveats:

• %l — This directive is NOT available.
• %b,%h,%B — These will all match a month name or abbreviation.
• %v,%a,%A — These will all match a day name or abbreviation.
• %z,%Z,%N — These will match any time zone string.
• %n — Multi-line matching is not currently supported, so this directive is not allowed.
• %x — All format directives are converted to a regular expression and then cached (so that a format can be reused without the penalty of doing the conversion to a regular expression with each use). As a result, if you need to set the DateFormat config variable (which determines the meaning of the %x directive), it must be done before a format string containing %x is used. If the DateFormat config variable is set afterwards, the format string will reflect the old, NOT THE NEW, value of DateFormat.

The format string may not over-specify the date. In other words, you may not include both a %y and %Y directive or both a %j and %m directive.

A valid format string will specify any of the following sets of data:

• Required: M D H Mn S | M D H Mn | M D | H Mn S | H Mn
• Optional: Y Zone Day-of-week

For example, if you had a date stored as YYYY.MM-DD, you could match it using:

$date->parse_format('%Y\\.%m\\-%d',$string);

If you wanted to extract the date from an apache log line:

10.11.12.13 - - [17/Aug/2009:12:33:30 -0400] "GET /favicon.ico ...

you could use:

$date->parse_format('.*?\\[%d/%b/%Y:%T %z\\].*',$line);

When matching months, days, and hours, there are two directives that could be used (for numerical versions). For the month, you may use %m or %f. If your date is known to have a two-digit month, you should use %m. If it contains a one- or two-digit month, you must use %f (and it is safe to use %f for two-digit months). Similarly, for days, you can use %d or %e and for hours you can use %H or %k. In both cases, the first can only be used if you are guaranteed a 2-digit value.

In your format string, you may use capture groups (or back references to them) in the regular expression using all of the rules of normal regular expressions. Since Date::Manip uses named capture groups internally, it is suggested that you also use named groups. Mixing numbered and named groups will work... but it'll be entirely up to you to keep track of what numbers refer to which capture groups.

Every printf directive adds one or more named capture groups to the regular expression. If you use named groups in the format string, they must not conflict with the ones used internally, or else the date will probably not be parsed correctly.

The following named capture groups are used internally:

y m d h mn s mon_name mon_abb dow_name dow_abb dow_char dow_num doy nth ampm
epoches epocho tzstring off abb zone g w l u

To be safe, it is suggested that any additional named capture groups introduced by the programmer start with a capital letter. This is guaranteed to never conflict with any existing, or future named capture groups.

In order to get access to the values stored in the additional named capture groups, the parse_format function must be called in list context, and the %+ array will be returned as the second value.

As an example:

$string = "before 2014-01-25 after";
($err,%m) = $date->parse_format('(?<PRE>.*?)%Y-%m-%d(?<POST>.*)',$string);

would return a hash (%m) with the following key/value pairs:

'PRE'  => 'before '
'POST' => ' after'

prev / next

⬅️ The prev method changes the date to the previous (or current) occurrence of either a day of the week, a certain time of day, or both. The next method changes the date to the next (or current) occurrence. The examples below illustrate the prev method, but the next one is identical in operation.

There are two different ways to use this method. The first is to pass in a day of week and possibly a time:

$err = $date->prev($dow, $curr [,$time]);

If $curr = 0, this means to look for the previous occurrence of the day of week, and set the time to the value passed in (or current time if no time was passed in). The day is ALWAYS less than the current day. If the current day is the same day of week as $dow, then the date returned will be one week earlier.

If $curr = 1, it means to look for the current or previous occurrence of the day of week, and set the time to the value passed in (or 00:00:00 if none was passed in). If the current day of week is the same as $dow, the date will remain unchanged. Since the time is then set, the new date may actually occur after the original date depending on the value of $time.

If $curr = 2, it means to look for the last time (not counting now) that the day of week at the given time occurred. The date may be the same as the original date.

$time may be a list reference of [H,MN,S], [H,MN], or [H].

The following examples illustrate the use of this function (Original Date = Fri Nov 22 18:15:00):

dow      curr   time       new date
4 (Thu)  0/1/2  undef      Thu Nov 21 00:00:00
4        0/1/2  [12,30,0]  Thu Nov 21 12:30:00
5 (Fri)  0/2    undef      Fri Nov 15 18:15:00
5        1      undef      Fri Nov 22 18:15:00
5        0      [12,30,0]  Fri Nov 15 12:30:00
5        1/2    [12,30,0]  Fri Nov 22 12:30:00
5        0/2    [19,30,0]  Fri Nov 15 19:30:00
5        1      [19,30,0]  Fri Nov 22 19:30:00

The second way to use this method is by passing in undef for the day of week:

$err = $date->prev(undef,$curr,$time);

In this case, a time is required and it must be a list reference of 3 elements: [H, MN, S]. Any or all of the elements may be undef.

The new date is the previous occurrence of the time.

If you define hours, then minutes and seconds may be defined, or default to 0 and you are looking for a previous time that the specified time (HH:00:00) occurred (which might be as much as 24 hours in the past).

If hours are undefined and minutes are defined, then seconds may be defined, or default to 0, and you are looking for the last time the minutes/seconds (MN:SS) appeared on the digital clock, which will be sometime in the past hour.

Finally, if hours and minutes are undefined, seconds must be defined (or default to zero) and the last time that that second occurred will be returned (which will be sometime in the past minute).

If $curr is non-zero, the current time is returned if it matches the criteria passed in, so the returned value will be now or in the past. If $curr is zero, the time returned will definitely be in the past.

DATE = Fri Nov 22 18:15:00
curr  hr     min    sec      returns
0/1   18     undef  undef    Nov 22 18:00:00
0/1   18     30     0        Nov 21 18:30:00
0     18     15     undef    Nov 21 18:15:00
1     18     15     undef    Nov 22 18:15:00
0     undef  15     undef    Nov 22 17:15:00
1     undef  15     undef    Nov 22 18:15:00

printf

$out = $date->printf($in);
@out = $date->printf(@in);

🎨 This takes a string or list of strings which may contain any number of special formatting directives. These directives are replaced with information contained in the date. Everything else in the string is returned unmodified.

A directive always begins with '%'. They are described in the section below in the section PRINTF DIRECTIVES.

secs_since_1970_GMT

$secs = $date->secs_since_1970_GMT();

⏱️ This returns the number of seconds that have elapsed since Jan 1, 1970 00:00:00 GMT (negative if the date is earlier).

The reverse is also allowed:

$err = $date->secs_since_1970_GMT($secs);

which sets the date to $secs seconds from Jan 1, 1970 00:00:00 GMT in the local time zone.

set

$err = $date->set($field,@vals [,$isdst]);

✏️ This explicitly sets one or more fields in a date.

$field can be any of the following:

• zone — [ZONE] ZONE can be any zone or alias
• zdate — [ZONE,]DATE sets the zone and entire date
• date — DATE sets the entire date
• time — TIME sets the entire time
• y — YEAR (sets one field)
• m — MONTH
• d — DAY
• h — HOUR
• mn — MINUTE
• s — SECOND

Here, DATE is a list reference containing [Y,M,D,H,MN,S] and TIME is a list reference containing [H,MN,S].

ZONE is optional (it defaults to the local zone as defined either by the system clock, or the SetDate or ForceDate config variables). If it is passed in, it can be any zone name, abbreviation, or offset. An offset can be expressed either as a valid offset string, or as a list reference. Refer to the join/split functions of Date::Manip::Base for information on valid offset strings.

An optional last argument is $isdst (which must be 0 or 1) is included when setting a date which could be in either standard time or daylight saving time. It is ignored in all other situations. If it is not included, and the resulting date could be in either, it will default to standard time.

The $date object must contain a valid date (unless the entire date is being set with $field set to either "zdate" or "date").

If $field is "zone", the time zone of the date will be set. If ZONE is not passed in, it will be set to the local time zone. When setting the time zone, no conversion is done! Whatever date and time is stored in the $date object prior to this remains unchanged... except it will be that date and time in the new time zone.

If $field is "zdate", the entire date and time zone is set. If ZONE is not passed in, it is set to the local time zone.

If $field is "date", the entire date will be set, but the time zone of the date will not be changed.

If $field is "time", or one of the individual fields, only those fields will be modified.

An error is returned if an invalid argument list is passed in, or if the resulting date is checked and found to be invalid.

value

$val = $date->value([$type]);
@val = $date->value([$type]);

📤 These return the value of the date stored in the object.

In scalar context, a printable string in the form YYYYMMDDHH:MN:SS is returned. In list context, a list is returned of (Y,M,D,H,MN,S).

• If $type is omitted, the date is returned in the time zone it was parsed in.
• If $type is "local", it is returned in the local time zone (which is either the system time zone, or the zone specified with the SetDate or ForceDate config variables).
• If $type is "gmt", the date is returned in the GMT time zone.

An empty string or list is returned in the case of an error (and an error code is set).

week_of_year

$wkno = $date->week_of_year([$first]);

📅 This figures out the week number. If $first is passed in, it must be between 1 and 7 and refers to the first day of the week. If $first is not passed in, the FirstDay config variable is used.

⚠️ NOTE: This routine should only be called in rare cases. Use printf with the %W, %U, %J, %L formats instead. This routine returns a week between 0 and 53 which must then be "fixed" to get into the ISO 8601 weeks from 1 to 53. A date which returns a week of 0 actually belongs to the last week of the previous year. A date which returns a week of 53 may belong to the first week of the next year.

⚠️ ISSUES WITH PARSING DATES

Complete vs. truncated dates and times

Date formats are either complete or truncated. A complete date fully specifies the year, month, and day and a complete time fully specifies the hour, minute, and second.

It should be understood that in many instances, the information may be implied rather than explicitly stated, but it is still treated as complete.

For example, the date "January 3" is complete because it implies the current year.

A truncated calendar date or time does not include information about some of the fields. Date::Manip will never work with a partial date or time, so defaults will be supplied.

For example, the date "2009-01" is missing a day field, so a default will be used. In this case, the day will be the 1st, so this is equivalent to "Jan 1st 2009". If only the year is given, it will default to Jan 1.

If the time, or any of it's components is missing, they default to 00. So the time "12:30" and "12:30:00" are equivalent.

The "complete" method can be used to check what type of date was parsed, and which values were specified (either explicitly or implied) and which were provided as a default. It should be noted that there is no way to differentiate between an explicit and implied value.

A string with a date and/or time may consist of any of the following:

• a complete date and a time (complete or truncated)
• a truncated date with no time
• a time (complete or truncated) with no date

In other words, the date "Jan 2009 12:30" is not valid since it consists of a time with a truncated date.

🌍 VALID TIME ZONE FORMATS

When specifying a time zone, it can be done in three different ways:

1. Specify the actual time zone name
2. Supply a valid time zone abbreviation
3. Specify an offset (with an optional abbreviation)

The timezone information always follows the time immediately, and may only be included if a time is included.

🔹 By complete name (or standard alias)

2001-07-01-00:00:00 America/New_York

Although unambiguous for time zone identification, the time is ambiguous in most zones for one hour of the year (when clocks are set back). If this form is used, the date will be assigned to standard time, meaning that some times cannot be expressed this way. This method is discouraged.

🔹 By time zone abbreviation (most common)

2001-07-01-00:00:00 EDT

The abbreviation does not uniquely determine the time zone except in a few cases. Date::Manip will test all time zones which use the abbreviation in the order given in Date::Manip::Zones and use the first match. The order of testing can be modified using the abbrev method described in the Date::Manip::TZ documentation.

🔹 By offset and optional abbreviation

2001-07-01-00:00:00 -04
2001-07-01-00:00:00 -04:00 (EDT)
2001-07-01-00:00:00 -0400 EDT

The offset is rarely sufficient to uniquely determine the time zone. The time zone will be determined by testing all time zones with the given offset (and abbreviation) until a match is found. See the def_zone method in Date::Manip::TZ for more details.

📅 VALID DATE FORMATS

There are several categories of date formats supported by Date::Manip. These are strings which specify only the year/month/day fields.

ISO 8601 dates

The preferred date formats are those specified by ISO 8601. Date::Manip handles all of these formats, but does not require rigid adherence to the specification.

Fields:

• CC — 2-digit century
• YY — 2-digit year in century
• MM — 2-digit month
• DD — 2-digit day of month
• DoY — 3-digit day of year (001-366)
• Www — "W" followed by 2-digit week (01-53)
• D — day of week (1-7)

Complete date formats (example: Thu Mar 5 2009):

CCYYMMDD           20090305
CCYY-MM-DD         2009-03-05
YYMMDD             090305
YY-MM-DD           09-03-05
-YYMMDD            -090305
-YY-MM-DD          -09-03-05
--MMDD             --0305
--MM-DD            --03-05
---DD              ---05
CCYYDoY            2009064
CCYY-DoY           2009-064
YYDoY              09064
YY-DoY             09-064
-YYDoY             -09064
-YY-DoY            -09-064
-DoY               -064
CCYYWwwD           2009W104
CCYY-Www-D         2009-W10-4
YYWwwD             09W104
YY-Www-D           09-W10-4
-YYWwwD            -09W104
-YY-Www-D          -09-W10-4
-YWwwD             -9W104
-Y-Www-D           -9-W10-4
-WwwD              -W104
-Www-D             -W10-4
-W-D               -W-4
---D               ---4

Truncated date formats:

CCYY-MM     2009-03   (2009-03-01)
CCYY        2009      (2009-01-01)
CC          20        (2000-01-01)
-YYMM       -0903
-YY-MM      -09-03
-YY         -09
--MM        --03
CCYYWww     2009W10
CCYY-Www    2009-W10
YYWww       09W10
YY-Www      09-W10
-YYWww      -09W10
-YY-Www     -09-W10
-Www        -W10

Notes:

1. Some formats considered truncated in the standard are treated as complete since they imply all fields.
2. As of 6.00, a two-digit date is treated as CC (previously YY). A six-digit date is treated as YYMMDD (previously YYYYMM).
3. Dashes may be expanded (all dashes) or abbreviated (no dashes), but not mixed (e.g., YY-MMDD is NOT allowed).
4. The Www-D format: day of week is numbered 1-7 (Monday=1). The constraint that week must start on Monday is relaxed — the week may begin on Sunday.

Common date formats

Fields:

• YY — 2-digit year
• YYYY — 4-digit year
• M — 1- or 2-digit month
• MM — 2-digit month
• D — 1- or 2-digit day
• DD — 2-digit day
• mmm — Abbreviated or full month name (e.g., Jan)

Supported formats:

M/D             3/5
M/D/YY          3/5/09
M/D/YYYY        3/5/2009
YYYY/M/D        2009/3/5
mmm/D           Mar/5
mmm/D/YY        Mar/5/09
mmm/D/YYYY      Mar/5/2009
D/mmm           5/Mar
D/mmm/YY        5/Mar/09
D/mmm/YYYY      5/Mar/2009
YYYY/mmm/D      2009/Mar/5
mmmD            Mar5
mmmDDYY         Mar0509
mmmDDYYYY       Mar052009
Dmmm            5Mar
DmmmYY          5Mar09
DmmmYYYY        5Mar2009
YYYYmmmD        2009Mar5
mmmD YY         Mar5 09
mmmD YYYY       Mar5 2009
Dmmm YY         5Mar 09
Dmmm YYYY       5Mar2009
mmm/D YY        Mar/5 09
mmm/D YYYY      Mar/5 2009
D/mmm YY        5/Mar 09
D/mmm YYYY      5/Mar 2009
YY   mmmD       09   Mar5
YYYY mmmD       2009 Mar5
YY   Dmmm       09   5Mar
YYYY Dmmm       2009 5Mar
YY   mmm/D      09   Mar/5
YYYY mmm/D      2009 Mar/5
YY   D/mmm      09   5/Mar
YYYY D/mmm      2009 5/Mar
YYYY:MM:DD      2010:01:15 (EXIF format)
mmmYYYY         Jun 2010
YYYYmmm         2010 June
mmm/YYYY        Jun/2010
YYYY/mmm        2010/Jun

Separators: The slash (/) can be replaced by whitespace, period (.), or dash (-). Dash is discouraged as it may conflict with ISO 8601 formats. The same separator must be used throughout the date.

Notes:

1. Americans write month first; many other countries write day first. Set the config variable DateFormat to something other than "US" for the latter.
2. The dot (.) separator may not be used in the M/D format (will be interpreted as H12,H+ time format).
3. The config variable Format_MMMYYYY controls whether mmmDDYY or mmmYYYY/YYYYmmm formats are used. If set to 'first', returns the 1st of the month at midnight; if 'last', returns the last day at 23:59:59.

Less common date formats

DoW                          Friday
DoW at time                  Friday at 12:40
MMM Nth [YYYY]               Dec 1st 1970
Nth MMM [YYYY]               1st Dec 1970
YYYY MMM Nth                 1970 Dec 1st
YYYY Nth MMM                 1970 1st Dec
next/prev DoW                next Friday
next/prev DoW at time        last Friday at 12:40
next/last week/month/year    next week
last day in MMM [YYYY]       last day in October
last DoW in MMM [YYYY]       last Tuesday in October 1996
last DoW in YYYY             last Tuesday in 1997
Nth DoW in MMM [YYYY]        3rd Tuesday in October 1996
Nth DoW [YYYY]               22nd Sunday in 1996
Nth day in MMM [YYYY]        1st day of February 2012
DoW week                     Monday week
DoW week N [YYYY]            Sunday week 22
Dow Nth week [YYYY]          Sunday 22nd week
Nth                           12th (day of current month)

Note: "Sunday week 22" returns the Sunday of the 22nd week of the year (based on ISO 8601 week definition). "22nd Sunday" gives the actual 22nd occurrence of Sunday in the year.

Special date strings

today
tomorrow
yesterday
today week
tomorrow week
yesterday week

Other languages have similar strings.

Holidays

You can parse holiday names as dates (including timezones):

Christmas
Christmas 2010
Christmas 2010 at noon
Christmas 2010 at noon PST
Saturday Christmas 2010 at noon

Day of week validation

In all non-ISO 8601 formats, the day of week ("Friday") can be entered anywhere in the date and will be checked for accuracy. "Tue Jul 16 1996 13:17:00" works, but "Jul 16 1996 Wednesday 13:17:00" will not (because Jul 16, 1996 is Tuesday, not Wednesday).

🌐 A NOTE ABOUT FOREIGN LANGUAGE DATES

Although Date::Manip has some support for parsing dates in foreign languages, the formats supported are largely based on English equivalents. There are probably many valid dates in other languages that do not have an English equivalent. You are free to suggest additions, but no guarantees are made.

⏰ VALID TIME FORMATS

There are several categories of time formats supported by Date::Manip.

ISO 8601 times

Fields:

• HH — 2-digit hour
• MN — 2-digit minutes
• SS — 2-digit seconds
• H+ — 1+ digit fractional hours
• M+ — 1+ digit fractional minutes
• S+ — 1+ digit fractional seconds

Complete time formats (example: 12:30:15):

HHMNSS              123015
HH:MN:SS            12:30:15
HHMNSS,S+           123015,5
HH:MN:SS,S+         12:30:15,5   (Fractional seconds ignored)
HHMN,M+             1230,25
HH:MN,M+            12:30,25     (12:30:00 + 0.25 minutes)
HH,H+               12,5         (12:00:00 + 0.5 hours = 12:30:00)
-MNSS               -3015
-MN:SS              -30:15
--SS                --15
-MNSS,S+            -3015,5
-MN:SS,S+           -30:15,5
-MN,M+              -30,25
--SS,S+             --15,5
HHMN                1230
HH:MN               12:30

Truncated time formats:

HH                  12
-MN                 -30

Notes:

1. The HHMNSS format is ambiguous with YYMMDD. To parse as a time, add ",0" to the end or include time zone information.
2. Fractional parts may use a comma or period: 12:30,25 = 12:30.25.
3. ISO 8601 times may be followed by a time zone unless truncated.
4. Negative time zone offsets may cause confusion. Use colon separators in the time when using offset time zones: 12:30:05-0300.

Other time formats

Fields:

• H24 — 1- or 2-digit hour (0-23)
• H12 — 1- or 2-digit hour (1-12)
• MN — 2-digit minutes
• SS — 2-digit seconds
• H+ — 1+ digit fractional hours
• M+ — 1+ digit fractional minutes
• S+ — 1+ digit fractional seconds
• AM — Language specific AM/PM string

Accepted formats:

H24:MN:SS           17:30:15
H12:MN:SS AM        5:30:15 PM
H12:MN:SS
H24:MN:SS,S+        17:30:15,5
H12:MN:SS,S+ AM     5:30:15,5 PM
H12:MN:SS,S+
H24:MN,M+           17:30,25
H12:MN,M+ AM        5:30,25 PM
H12:MN,M+
H24,H+              17,5
H12,H+ AM           5,5 PM
H12,H+
H24:MN              17:30
H12:MN AM           5:30 PM
H12:MN
H12 AM              5 PM

The fractional part may use a comma, period, or colon: 12:30:20,25 = 12:30:20.25 = 12:30:20:25.

Special time strings

noon        12:00:00
midnight    00:00:00

These are equivalent to their time values. "midnight" is interpreted as the start of the day (00:00:00) for backwards compatibility with Date::Manip 5.xx.

A word like "at" may precede the time (optional, must be separated by whitespace): 12:30 = at 12:30.

Conventions:

• midnight = 12:00am = 00:00:00
• noon = 12:00pm = 12:00:00
• The day goes from 00:00:00 to 23:59:59. The time 24:00:00 is allowed and transformed to 00:00:00 of the following day.

📅 ⏰ VALID COMBINED DATE AND TIME FORMATS

ISO 8601 combined date and time

A string containing a complete ISO 8601 date and a complete or truncated ISO 8601 time. May include a timezone if a complete time is included.

The time may be separated from the date by space, dash, or the letter T, or joined with nothing. The DoY formats should always be separated from the time by something.

Non-ISO 8601 combined date and time

Any non-ISO 8601 date format may be combined with any non-ISO 8601 time format.

Deltas

Dates can be specified as a delta from "now":

in 2 days
in 3 days at 12:00:00
in 3 days at 12:00:00 PST

If the delta has no time part, the time may be specified explicitly. It is NOT allowed to include an explicit time if any time segment was included in the delta.

Additional supported formats:

Friday in 2 weeks
in 2 weeks on Friday
Friday 2 weeks ago
2 weeks ago on Friday at 13:45

These apply the delta (weeks, months, years) to the current time, then set the day to the given day-of-week in that week.

Special date and time strings

now
now PST

Additional combined date and time formats

epoch SECS
epoch SECS TIMEZONE

SECS is the number of seconds since the epoch (Jan 1, 1970 00:00:00 GMT). May be negative.

General notes

• Commas may be included in all date formats arbitrarily (except ISO 8601).
• The time/time zone is removed from the date before parsing, so the time may appear before, after, or between any two parts of the date.
• The time and zone do not need to be adjacent: Jan 21 17:13:27 2010 -0400 works.
• Words like "on", "in", "at", "of" are ignored (except in ISO 8601 formats).

🎨 PRINTF DIRECTIVES

The following printf directives are replaced with information from the date.

Year

• %y — year (00 to 99)
• %Y — year (0001 to 9999)

Month, Week

• %m — month of year (01 to 12)
• %f — month of year (" 1" to "12")
• %b,%h — month abbreviation (Jan to Dec)
• %B — month name (January to December)

Day

• %j — day of the year (001 to 366)
• %d — day of month (01 to 31)
• %e — day of month (" 1" to "31")
• %v — weekday abbreviation (" S"," M"," T", ...)
• %a — weekday abbreviation (Sun to Sat)
• %A — weekday name (Sunday to Saturday)
• %w — day of week (1 to 7, 1=Monday)
• %E — day of month with suffix (1st, 2nd, 3rd...)

Hour

• %H — hour (00 to 23)
• %k — hour (" 0" to "23")
• %i — hour (" 1" to "12")
• %I — hour (01 to 12)
• %p — AM or PM

Minute, Second, Time zone

• %M — minute (00 to 59)
• %S — second (00 to 59)
• %Z — time zone abbreviation (EDT)
• %z — time zone as GMT offset (+0100)
• %N — time zone as GMT offset (+01:00:00)

Epoch

• %s — seconds from 1/1/1970 GMT (negative if before)
• %o — seconds from 1/1/1970 in current time zone

Date, Time

• %c — %a %b %e %H:%M:%S %Y (Fri Apr 28 17:23:15 1995)
• %C,%u — %a %b %e %H:%M:%S %Z %Y (Fri Apr 28 17:25:57 EDT 1995)
• %g — %a, %d %b %Y %H:%M:%S %Z (Fri, 28 Apr 1995 17:23:15 EDT)
• %D — %m/%d/%y (04/28/95)
• %x — %m/%d/%y or %d/%m/%y (depends on DateFormat)
• %l — date in ls(1) format (%b %e %H:%M or %b %e %Y)
• %r — %I:%M:%S %p (05:39:55 PM)
• %R — %H:%M (17:40)
• %T,%X — %H:%M:%S (17:40:58)
• %V — %m%d%H%M%y (0428174095)
• %Q — %Y%m%d (19961025)
• %q — %Y%m%d%H%M%S (19961025174058)
• %P — %Y%m%d%H:%M:%S (1996102517:40:58)
• %O — %Y-%m-%dT%H:%M:%S (1996-10-25T17:40:58)
• %F — %A, %B %e, %Y (Sunday, January 1, 1996)
• %K — %Y-%j (1997-045)

Special Year/Week formats

• %G — year, Monday as first day of week (0001 to 9999)
• %W — week of year, Monday as first day of week (01 to 53)
• %L — year, Sunday as first day of week (0001 to 9999)
• %U — week of year, Sunday as first day of week (01 to 53)
• %J — %G-W%W-%w (1997-W02-2)

Other formats

• %n — newline character
• %t — tab character
• %% — insert a `%' character
• %+ — insert a `+' character

Extended formats

• %<A=NUM> — Returns the NUMth value of %A (e.g., %<A=2> = Tuesday)
• %<a=NUM> — Returns the NUMth value of %a (e.g., %<a=2> = Tue)
• %<v=NUM> — Returns the NUMth value of %v (NUM 1-7)
• %<B=NUM> — Returns the NUMth value of %B (e.g., %<B=2> = February, NUM 1-12)
• %<b=NUM> — Returns the NUMth value of %b (e.g., %<b=2> = Feb, NUM 1-12)
• %<p=NUM> — Returns the NUMth value of %p (e.g., %<p=1> = AM, NUM 1-2)
• %<E=NUM> — Returns the NUMth value of %E (e.g., %<E=1> = 1st, NUM 1-53)

Notes

1. The ls format (%l) applies to dates within the past OR future 6 months. Dates outside that range have the year printed.
2. The %U, %W, %L, %G, and %J formats support ISO-8601 week format. %W and %G treat weeks as starting on Monday; %U and %L treat weeks as starting on Sunday. Days in the first or last week of a year may belong to the previous or next year. Always use (%W,%G) or (%U,%L) together — do not use %Y with these.
3. %s and %o return negative values for dates before the epoch. Other Unix utilities may return an error or zero.
4. %z returns the RFC 822 format (+0500). For irregular offsets (+05:17:30), the string returned is +051730 (not RFC 822 compliant).

🐛 KNOWN BUGS

None known.

❓ BUGS AND QUESTIONS

Please refer to the Date::Manip::Problems documentation for information on submitting bug reports or questions to the author.

📚 SEE ALSO

Date::Manip — main module documentation

📄 LICENSE

This script is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

👤 AUTHOR

Sullivan Beck (sbeck@cpan.org)

📖 NAME 🚀 Quick Reference 📋 SYNOPSIS 📝 DESCRIPTION 🔧 METHODS ⚠️ ISSUES WITH PARSING DATES 🌍 VALID TIME ZONE FORMATS 📅 VALID DATE FORMATS 🌐 A NOTE ABOUT FOREIGN LANGUAGE DATES ⏰ VALID TIME FORMATS 📅 ⏰ VALID COMBINED DATE AND TIME FORMATS 🎨 PRINTF DIRECTIVES 🐛 KNOWN BUGS ❓ BUGS AND QUESTIONS 📚 SEE ALSO 📄 LICENSE 👤 AUTHOR