# Copyright (c) 1995-2017 Sullivan Beck. All rights reserved.

# This program is free software; you can redistribute it and/or modify it

# under the same terms as Perl itself.

=pod

=head1 NAME

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

=head1 SYNOPSIS

   use Date::Manip::Date;

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

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

=head1 METHODS

=over 4

=item B<base>

=item B<config>

=item B<err>

=item B<is_date>

=item B<is_delta>

=item B<is_recur>

=item B<new>

=item B<new_config>

=item B<new_date>

=item B<new_delta>

=item B<new_recur>

=item B<tz>

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

=item B<calc>

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

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

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

=item B<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.

=item B<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.

=item B<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.

=item B<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.

=item B<input>

   $str = $date->input();

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

=item B<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.

=item B<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.

=item B<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.

=item B<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.

=item B<next_business_day>

=item B<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.

=item B<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.

=item B<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.

=item B<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'.

=item B<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          Optional

   M D H Mn S        Y Zone Day-of-week

   M D H Mn          Y Zone Day-of-week

   M D               Y Zone Day-of-week

   H Mn S            Zone

   H Mn              Zone

For example, if you had a date stored as:

   YYYY.MM-DD

you could match it using the following:

   $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

   epochs

   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('(?
.*?)%Y-%m-%d(?<POST>.*)',$string);

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

   'PRE'  => 'before '

   'POST' => ' after'

=item B<prev>

=item B<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 ALWAY 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 should 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

=item B<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.

=item B<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.

=item B<set>

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

This explicitly sets one or more fields in a date.

$field can be any of the following:

   $field   @vals

   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.

=item B<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).

=item B<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.

=back

=head1 ISSUES WITH PARSING DATES

The following issues may occur when parsing dates that should be

understood to make full use of this module.

=over 4

=item B<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.

=back

=head1 VALID TIME ZONE FORMATS

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

One way is to specify the actual time zone. The second is to supply

a valid time zone abbreviation. The third is to specify an offset (with

an optional abbreviation). The following dates illustrate the these

formats.

The timezone information always follows the time immediately, and may

only be included if a time is included. The following examples use

an ISO 8601 format for the date/time, but any of the other date and

time formats may be used.

The first way to specify the time zone is to specify it by complete name

(or using one of the standard aliases):

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

Although this is unambiguous when it comes to determining the time zone,

the time is ambiguous in most zones for one hour of the year. When

a time change occurs during which the clock is moved back, the same

wall clock time occurs twice.

For example, in America/New_York, on Sunday, Nov 2, 2008, at 02:00 in

the morning, the clock was set back to 01:00. As a result, the date

Nov 2, 2008 at 01:30 is ambiguous. It is impossible to determine if

this refers to the 01:30 that occurred half an hour before the time

change, or the one 30 minute after the change.

In practice, if this form is used, the date will be assigned to

standard time, meaning that there will be some times (typically 1 hour

per year) which cannot be expressed this way. As such, this method is

discouraged.

The second way to specify the time zone, which is the most common, is

to use a time zone abbreviation:

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

Unfortunately, the abbreviation does not uniquely determine the

time zone except in a few cases. In order to assign a time zone,

Date::Manip will refer to a list of all time zones which use the

abbreviation.  They will be tested, in the order given in the

Date::Manip::Zones documentation, and the first match (i.e. the one in

which the given date/time and abbreviation are valid) determines the

time zone which will be used. A great deal of effort has been made to

ensure that the most likely time zone will be obtained (i.e. the most

common time zones are tested before less common ones), so in most

cases, the desired results will be obtained.

If the default order does not yield the desired time zone, the order of

testing can be modified using the abbrev method described in the

Date::Manip::TZ documentation.

Although the time zone is ambiguous, the date is not, since only

time zones for which the date are valid will be used.

The third way to specify the time zone is by specifying an offset and

an optional abbreviation:

   2001-07-01-00:00:00 -04

   2001-07-01-00:00:00 -0400

   2001-07-01-00:00:00 -040000

   2001-07-01-00:00:00 -04:00

   2001-07-01-00:00:00 -04:00:00

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

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

   2001-07-01-00:00:00 -040000 (EDT)

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

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

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

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

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

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

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

The offset almost never sufficient to uniquely determine the time zone

(and it is not even guaranteed that both the offset and abbreviation

will, though in practice, it is probably sufficient). In this

instance, the time zone will be determined by testing all time zones

which have the given offset (and abbreviation if it is included) until

one is found which matches both pieces of information. For more

information about how this testing is done, refer to the def_zone

method of the Date::Manip::TZ documentation.

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

These formats explicitly set the date, but not the time. These formats

may be combined with a time string (as specified below) to set both

the date and time. If this is not done, the default time is determined

by the DefaultTime config variable.

=over 4

=item B<ISO 8601 dates>

The preferred date formats are those specified by ISO 8601. The

specification includes valid calendar date and valid time formats.

Date::Manip will handle all of these formats, but does not require

that the dates rigidly adhere to the specification since the ultimate

goal of Date::Manip is to handle dates as they are represented in

real life and some common variations exist which are similar to, but

not identical to, those from the specification.

A calendar date includes the following fields:

   CC    2-digit representation of the century

   YY    2-digit representation of the year in

         a century

   MM    2-digit representation of a month

   DD    2-digit representation of a day of month

   DoY   3-digit representation of a day of year

         (001-366)

   Www   the character "W" followed by a 2-digit

         week of the year (01-53)

   D     the day of the week (1-7)

The following date formats are considered complete by Date::Manip. In

the following, the date Thu Mar 5 2009 is used as an example.  This is

the 64th day of the year. Thu is the 4th day of the week.  The week

starting Mon, Mar 2 is the 10th week of the year (according the the

ISO 8601 definition). Obviously, some of the formats are only valid

when used at some times. For example, the format --MMDD refers to a

month and day in the current year, so the date Mar 5, 2009 can only be