=pod

=head1 NAME

Date::Manip::DM5 - Date manipulation routines

=head1 SYNOPSIS

 use Date::Manip;

 $version = DateManipVersion;

 Date_Init();

 Date_Init("VAR=VAL","VAR=VAL",...);

 @list = Date_Init();

 @list = Date_Init("VAR=VAL","VAR=VAL",...);

 $date = ParseDate(\@args);

 $date = ParseDate($string);

 $date = ParseDate(\$string);

 @date = UnixDate($date,@format);

 $date = UnixDate($date,@format);

 $delta = ParseDateDelta(\@args);

 $delta = ParseDateDelta($string);

 $delta = ParseDateDelta(\$string);

 @str = Delta_Format($delta,$dec,@format);

 $str = Delta_Format($delta,$dec,@format);

 $recur = ParseRecur($string,$base,$date0,$date1,$flags);

 @dates = ParseRecur($string,$base,$date0,$date1,$flags);

 $flag = Date_Cmp($date1,$date2);

 $d = DateCalc($d1,$d2 [,$errref] [,$del]);

 $date = Date_SetTime($date,$hr,$min,$sec);

 $date = Date_SetTime($date,$time);

 $date = Date_SetDateField($date,$field,$val [,$nocheck]);

 $date = Date_GetPrev($date,$dow,$today,$hr,$min,$sec);

 $date = Date_GetPrev($date,$dow,$today,$time);

 $date = Date_GetNext($date,$dow,$today,$hr,$min,$sec);

 $date = Date_GetNext($date,$dow,$today,$time);

 $name = Date_IsHoliday($date);

 $listref = Events_List($date);

 $listref = Events_List($date0,$date1);

 $date = Date_ConvTZ($date);

 $date = Date_ConvTZ($date,$from);

 $date = Date_ConvTZ($date,"",$to);

 $date = Date_ConvTZ($date,$from,$to);

 $flag = Date_IsWorkDay($date [,$flag]);

 $date = Date_NextWorkDay($date,$off [,$flag]);

 $date = Date_PrevWorkDay($date,$off [,$flag]);

 $date = Date_NearestWorkDay($date [,$tomorrowfirst]);

The above routines all check to make sure that Date_Init is called.  If it

hasn't been, they will call it automatically.  As a result, there is usually

no need to call Date_Init explicitly unless you want to change some of the

config variables (described below).  They also do error checking on the

input.

The routines listed below are intended primarily for internal use by other

Date::Manip routines.  They do little or no error checking, and do not

explicitly call Date_Init.  Those functions are all done in the main

Date::Manip routines above.

Because they are significantly faster than the full Date::Manip routines,

they are available for use with a few caveats.  Since little or no

error checking is done, it is the responsibility of the programmer to

ensure that valid data (AND valid dates) are passed to them.  Passing

invalid data (such as a non-numeric month) or invalid dates (Feb 31)

will fail in unpredictable ways (possibly returning erroneous results).

Also, since Date_Init is not called by these, it must be called

explicitly by the programmer before using these routines.

In the following routines, $y may be entered as either a 2 or 4 digit year

(it will be converted to a 4 digit year based on the variable YYtoYYYY

described below).  Month and day should be numeric in all cases.  Most (if

not all) of the information below can be gotten from UnixDate which is

really the way I intended it to be gotten, but there are reasons to use

these (these are significantly faster).

 $day = Date_DayOfWeek($m,$d,$y);

 $secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);

 $secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);

 $days = Date_DaysSince1BC($m,$d,$y);

 $day = Date_DayOfYear($m,$d,$y);

 ($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);

 $days = Date_DaysInYear($y);

 $days = Date_DaysInMonth($m,$y);

 $wkno = Date_WeekOfYear($m,$d,$y,$first);

 $flag = Date_LeapYear($y);

 $day = Date_DaySuffix($d);

 $tz = Date_TimeZone();

=head1 ROUTINES

=over 4

=item B<Date_Init>

 Date_Init();

 Date_Init("VAR=VAL","VAR=VAL",...);

 @list = Date_Init();

 @list = Date_Init("VAR=VAL","VAR=VAL",...);

Normally, it is not necessary to explicitly call Date_Init.  The first

time any of the other routines are called, Date_Init will be called to set

everything up.  If for some reason you want to change the configuration of

Date::Manip, you can pass the appropriate string or strings into Date_Init

to reinitialize things.

The strings to pass in are of the form "VAR=VAL".  Any number may be

included and they can come in any order.  VAR may be any configuration

variable.  A list of all configuration variables is given in the section

CUSTOMIZING DATE::MANIP below.  VAL is any allowed value for that variable.

For example, to switch from English to French and use non-US format (so

that 12/10 is Oct 12), do the following:

  Date_Init("Language=French","DateFormat=non-US");

If Date_Init is called in list context, it will return a list of all

config variables and their values suitable for passing in to Date_Init

to return Date::Manip to the current state.  The only possible problem is

that by default, holidays will not be erased, so you may need to prepend

the "EraseHolidays=1" element to the list.

=item B<ParseDate>

 $date = ParseDate(\@args);

 $date = ParseDate($string);

 $date = ParseDate(\$string);

This takes an array or a string containing a date and parses it.  When the

date is included as an array (for example, the arguments to a program) the

array should contain a valid date in the first one or more elements

(elements after a valid date are ignored).  Elements containing a valid

date are shifted from the array.  The largest possible number of elements

which can be correctly interpreted as a valid date are always used.  If a

string is entered rather than an array, that string is tested for a valid

date.  The string is unmodified, even if passed in by reference.

The real work is done in the ParseDateString routine.

The ParseDate routine is primarily used to handle command line arguments.

If you have a command where you want to enter a date as a command line

argument, you can use Date::Manip to make something like the following

work:

  mycommand -date Dec 10 1997 -arg -arg2

No more reading man pages to find out what date format is required in a

man page.

Historical note: this is originally why the Date::Manip routines were

written (though long before they were released as the Date::Manip module).

I was using a bunch of programs (primarily batch queue managers) where

dates and times were entered as command line options and I was getting

highly annoyed at the many different (but not compatible) ways that they

had to be entered.  Date::Manip originally consisted of basically 1 routine

which I could pass "@ARGV" to and have it remove a date from the beginning.

=item B<ParseDateString>

 $date = ParseDateString($string);

This routine is called by ParseDate, but it may also be called directly

to save some time (a negligible amount).

NOTE:  One of the most frequently asked questions that I have gotten

is how to parse seconds since the epoch.  ParseDateString cannot simply

parse a number as the seconds since the epoch (it conflicts with some

ISO-8601 date formats).  There are two ways to get this information.

First, you can do the following:

    $secs = ...         # seconds since Jan 1, 1970  00:00:00 GMT

    $date = DateCalc("Jan 1, 1970  00:00:00 GMT","+ $secs");

Second, you can call it directly as:

    $date = ParseDateString("epoch $secs");

To go backwards, just use the "%s" format of UnixDate:

    $secs = UnixDate($date,"%s");

A full date actually includes 2 parts: date and time.  A time must include

hours and minutes and can optionally include seconds, fractional seconds,

an am/pm type string, and a time zone.  For example:

     [at] HH:MN              [Zone]

     [at] HH:MN         [am] [Zone]

     [at] HH:MN:SS      [am] [Zone]

     [at] HH:MN:SS.SSSS [am] [Zone]

     [at] HH            am   [Zone]

Hours can be written using 1 or 2 digits, but the single digit form may

only be used when no ambiguity is introduced (i.e. when it is not

immediately preceded by a digit).

A time is usually entered in 24 hour mode, but 12 hour mode can be used

as well if AM/PM are entered (AM can be entered as AM or A.M. or other

variations depending on the language).

Fractional seconds are also supported in parsing but the fractional part is

discarded (with NO rounding occurring).

Time zones always appear immediately after the time.  A number of different

forms are supported (see the section TIME ZONES below).

Incidentally, the time is removed from the date before the date is parsed,

so the time may appear before or after the date, or between any two parts

of the date.

Valid date formats include the ISO 8601 formats:

   YYYYMMDDHHMNSSF...

   YYYYMMDDHHMNSS

   YYYYMMDDHHMN

   YYYYMMDDHH

   YY-MMDDHHMNSSF...

   YY-MMDDHHMNSS

   YY-MMDDHHMN

   YY-MMDDHH

   YYYYMMDD

   YYYYMM

   YYYY

   YY-MMDD

   YY-MM

   YY

   YYYYwWWD      ex.  1965-W02-2

   YYwWWD

   YYYYDOY       ex.  1965-045

   YYDOY

In the above list, YYYY and YY signify 4 or 2 digit years, MM, DD, HH, MN, SS

refer to two digit month, day, hour, minute, and second respectively.  F...

refers to fractional seconds (any number of digits) which will be ignored.

In all cases, the date and time parts may be separated by the letter "T"

(but this is optional), so

   2002-12-10-12:00:00

   2002-12-10T12:00:00

are identical.

The last 4 formats can be explained by example:  1965-w02-2 refers to Tuesday

(day 2) of the 2nd week of 1965.  1965-045 refers to the 45th day of 1965.

In all cases, parts of the date may be separated by dashes "-".  If this is

done, 1 or 2 digit forms of MM, DD, etc. may be used.  All dashes are

optional except for those given in the table above (which MUST be included

for that format to be correctly parsed).  So 19980820, 1998-0820,

1998-08-20, 1998-8-20, and 199808-20 are all equivalent, but that date may

NOT be written as 980820 (it must be written as 98-0820).

NOTE:  Even though not allowed in the standard, the time zone for an ISO-8601

date is flexible and may be any of the time zones understood by Date::Manip.

Additional date formats are available which may or may not be common including:

  MM/DD  **

  MM/DD/YY  **

  MM/DD/YYYY  **

  mmmDD       DDmmm                   mmmYYYY/DD     mmmYYYY

  mmmDD/YY    DDmmmYY     DD/YYmmm    YYYYmmmDD      YYYYmmm

  mmmDDYYYY   DDmmmYYYY   DDYYYYmmm   YYYY/DDmmm

Where mmm refers to the name of a month.  All parts of the date can be

separated by valid separators (space, "/", or ".").  The separator "-" may

be used as long as it doesn't conflict with an ISO 8601 format, but this

is discouraged since it is easy to overlook conflicts.  For example, the

format MM/DD/YY is just fine, but MM-DD-YY does not work since it conflicts

with YY-MM-DD.  To be safe, if "-" is used as a separator in a non-ISO

format, they should be turned into "/" before calling the Date::Manip

routines.  As with ISO 8601 formats, all separators are optional except for

those given as a "/" in the list above.

** Note that with these formats, Americans tend to write month first, but

many other countries tend to write day first.  The latter behavior can be

obtained by setting the config variable DateFormat to something other than

"US" (see CUSTOMIZING DATE::MANIP below).

Date separators are treated very flexibly (they are converted to spaces),

so the following dates are all equivalent:

   12/10/1965

   12-10 / 1965

   12 // 10 -. 1965

In some cases, this may actually be TOO flexible, but no attempt is made to

trap this.

Years can be entered as 2 or 4 digits, days and months as 1 or 2 digits.

Both days and months must include 2 digits whenever they are immediately

adjacent to another numeric part of the date or time.  Date separators

are required if single digit forms of DD or MM are used.  If separators

are not used, the date will either be unparsable or will get parsed

incorrectly.

Miscellaneous other allowed formats are:

  which dofw in mmm in YY      "first Sunday in June

                               1996 at 14:00" **

  dofw week num YY             "Sunday week 22 1995" **

  which dofw YY                "22nd Sunday at noon" **

  dofw which week YY           "Sunday 22nd week in

                               1996" **

  next/last dofw               "next Friday at noon"

  next/last week/month         "next month"

  in num days/weeks/months     "in 3 weeks at 12:00"

  num days/weeks/months later  "3 weeks later"

  num days/weeks/months ago    "3 weeks ago"

  dofw in num week             "Friday in 2 weeks"

  in num weeks dofw            "in 2 weeks on Friday"

  dofw num week ago            "Friday 2 weeks ago"

  num week ago dofw            "2 weeks ago Friday"

  last day in mmm in YY        "last day of October"

  dofw                         "Friday" (Friday of

                               current week)

  Nth                          "12th", "1st" (day of

                               current month)

  epoch SECS                   seconds since the epoch

                               (negative values are

                               supported)

** Note that the formats "Sunday week 22" and "22nd Sunday" give very

different behaviors.  "Sunday week 22" returns the Sunday of the 22nd week

of the year based on how week 1 is defined.  ISO 8601 defines week one to

contain Jan 4, so "Sunday week 1" might be the first or second Sunday of

the current year, or the last Sunday of the previous year.  "22nd Sunday"

gives the actual 22nd time Sunday occurs in a given year, regardless of the

definition of a week.

Note that certain words such as "in", "at", "of", etc. which commonly appear

in a date or time are ignored.  Also, the year is always optional.

In addition, the following strings are recognized:

  today     (exactly now OR today at a given time if a time is specified)

  now       (synonym for today)

  yesterday (exactly 24 hours ago unless a time is specified)

  tomorrow  (exactly 24 hours from now unless a time is specified)

  noon      (12:00:00)

  midnight  (00:00:00)

Other languages have similar (and in some cases additional) strings.

Some things to note:

All strings are case insensitive.  "December" and "DEceMBer" both work.

When a part of the date is not given, defaults are used: year defaults

to current year; hours, minutes, seconds to 00.

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 variable (described below).  The default behavior

it to force the 2 digit year to be in the 100 year period CurrYear-89 to

CurrYear+10.  So in 1996, the range is [1907 to 2006], and the 2 digit year

05 would refer to 2005 but 07 would refer to 1907.  See CUSTOMIZING

DATE::MANIP below for information on YYtoYYYY for other methods.

Dates are always checked to make sure they are valid.

In all of the formats, the day of week ("Friday") can be entered anywhere

in the date and it will be checked for accuracy.  In other words,

  "Tue Jul 16 1996 13:17:00"

will work but

  "Jul 16 1996 Wednesday 13:17:00"

will not (because Jul 16, 1996 is Tuesday, not Wednesday).  Note that

depending on where the weekday comes, it may give unexpected results when

used in array context (with ParseDate).  For example, the date

("Jun","25","Sun","1990") would return June 25 of the current year since

Jun 25, 1990 is not Sunday.

The times "12:00 am", "12:00 pm", and "midnight" are not well defined.  For

good or bad, I use the following convention in Date::Manip:

  midnight = 12:00am = 00:00:00

  noon     = 12:00pm = 12:00:00

and the day goes from 00:00:00 to 23:59:59.  In other words, midnight is the

beginning of a day rather than the end of one.  The time 24:00:00 is also

allowed (though it is automatically transformed to 00:00:00 of the following

day).

The format of the date returned is YYYYMMDDHH:MM:SS.  The advantage of this

time format is that two times can be compared using simple string comparisons

to find out which is later.  Also, it is readily understood by a human.

Alternate forms can be used if that is more convenient.  See Date_Init below

and the config variable Internal.

NOTE: The format for the date is going to change at some point in the future

to YYYYMMDDHH:MN:SS+HHMN*FLAGS.  In order to maintain compatibility, you

should use UnixDate to extract information from a date, and Date_Cmp to compare

two dates.  The simple string comparison will only work for dates in the same

time zone.

=item B<UnixDate>

 @date = UnixDate($date,@format);

 $date = UnixDate($date,@format);

This takes a date and a list of strings containing formats roughly

identical to the format strings used by the UNIX date(1) command.  Each

format is parsed and an array of strings corresponding to each format is

returned.

$date may be any string that can be parsed by ParseDateString.

The format options are:

 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"," W","Th"," F","Sa"

     %a     weekday abbreviation     - Sun to Sat

     %A     weekday name             - Sunday to Saturday

     %w     day of week              - 1 (Monday) to 7 (Sunday)

     %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                - "EDT"

     %z     time zone as GMT offset  - "+0100"

 Epoch (see NOTE 3 below)

     %s     seconds from 1/1/1970 GMT- negative if before 1/1/1970

     %o     seconds from Jan 1, 1970

            in the 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     - 04/28/95 or 28/04/28

                                       (Depends on DateFormat variable)

     %l     date in ls(1) format (see NOTE 1 below)

              %b %e $H:$M            - Apr 28 17:23  (if within 6 months)

              %b %e  %Y              - Apr 28  1993  (otherwise)

     %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 (see NOTE 2 below)

     %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     insert a newline character

     %t     insert a tab character

     %%     insert a `%' character

     %+     insert a `+' character

 The following formats are currently unused but may be used in the future:

     N 1234567890 !@#$^&*()_|-=\`[];',./~{}:<>?

 They currently insert the character following the %, but may (and probably

 will) change in the future as new formats are added.

If a lone percent is the final character in a format, it is ignored.

The formats used in this routine were originally based on date.pl (version

3.2) by Terry McGonigal, as well as a couple taken from different versions

of the Solaris date(1) command.  Also, several have been added which are

unique to Date::Manip.

NOTE 1:

The ls format (%l) applies to date within the past OR future 6 months!

NOTE 2:

The %U, %W, %L, %G, and %J formats are used to support the ISO-8601 format:

YYYY-wWW-D.  In this format, a date is written as a year, the week of the

year, and the day of the week.  Technically, the week may be considered to

start on any day of the week, but Sunday and Monday are the both common

choices, so both are supported.

The %W and %G formats return the week-of-year and the year treating weeks

as starting on Monday.

The %U and %L formats return the week-of-year and the year treating weeks

as starting on Sunday.

Most of the time, the %L and %G formats returns the same value as the %Y

format, but there is a problem with days occurring in the first or last week

of the year.

The ISO-8601 representation of Jan 1, 1993 written in the YYYY-wWW-D format

is actually 1992-W53-5.  In other words, Jan 1 is treated as being in the

last week of the preceding year.  Depending on the year, days in the first

week of a year may belong to the previous year, and days in the final week

of a year may belong to the next year.  The week is assigned to the year

which has most of the days.  For example, if the week starts on Sunday,

then the last week of 2003 is 2003-12-28 to 2004-01-03.  This week is

assigned to 2003 since 4 of the days in it are in 2003 and only 3 of them

are in 2004.  The first week of 2004 starts on 2004-01-04.

The %U and %W formats return a week-of-year number from 01 to 53. %L and

%G return the corresponding year, and to get this type of information,

you should always use the (%W,%G) combination or (%U,%L) combination. %Y

should not be used as it will yield incorrect results.

%J returns the full ISO-8601 format (%G-W%W-%w).

NOTE 3:

The %s and %o formats return negative values if the date is before

the start of the epoch.  Other Unix utilities would return an error, or

a zero, so if you are going to use Date::Manip in conjunction with these,

be sure to check for a negative value.

=item B<ParseDateDelta>

 $delta = ParseDateDelta(\@args);

 $delta = ParseDateDelta($string);

 $delta = ParseDateDelta(\$string);

This takes an array and shifts a valid delta date (an amount of time)

from the array.  Recognized deltas are of the form:

  +Yy +Mm +Ww +Dd +Hh +MNmn +Ss

      examples:

         +4 hours +3mn -2second

         + 4 hr 3 minutes -2

         4 hour + 3 min -2 s

  +Y:+M:+W:+D:+H:+MN:+S

      examples:

         0:0:0:0:4:3:-2

         +4:3:-2

  mixed format

      examples:

         4 hour 3:-2

A field in the format +Yy is a sign, a number, and a string specifying

the type of field.  The sign is "+", "-", or absent (defaults to the

next larger element).  The valid strings specifying the field type

are:

   y:  y, yr, year, years

   m:  m, mon, month, months

   w:  w, wk, ws, wks, week, weeks

   d:  d, day, days

   h:  h, hr, hour, hours

   mn: mn, min, minute, minutes

   s:  s, sec, second, seconds

Also, the "s" string may be omitted.  The sign, number, and string may

all be separated from each other by any number of whitespace.

In the date, all fields must be given in the order: Y M W D H MN S.  Any

number of them may be omitted provided the rest remain in the correct

order.  In the 2nd (colon) format, from 2 to 7 of the fields may be given.

For example +D:+H:+MN:+S may be given to specify only four of the fields.

In any case, both the MN and S field may be present.  No spaces may be

present in the colon format.

Deltas may also be given as a combination of the two formats.  For example,

the following is valid: +Yy +D:+H:+MN:+S.  Again, all fields must be given

in the correct order.

The word "in" may be given (prepended in English) to the delta ("in 5 years")

and the word "ago" may be given (appended in English) ("6 months ago").  The

"in" is completely ignored.  The "ago" has the affect of reversing all signs

that appear in front of the components of the delta.  I.e. "-12 yr 6 mon ago"

is identical to "+12yr +6mon" (don't forget that there is an implied minus

sign in front of the 6 because when no sign is explicitly given, it carries

the previously entered sign).

One thing is worth noting.  The year/month and day/hour/min/sec parts are

returned in a "normalized" form.  That is, the signs are adjusted so as to

be all positive or all negative.  For example, "+ 2 day - 2hour" does not

return "0:0:0:2:-2:0:0".  It returns "+0:0:0:1:22:0:0" (1 day 22 hours

which is equivalent).  I find (and I think most others agree) that this is

a more useful form.

Since the year/month and day/hour/min/sec parts must be normalized

separately there is the possibility that the sign of the two parts will be

different.  So, the delta "+ 2years -10 months - 2 days + 2 hours" produces

the delta "+1:2:-0:1:22:0:0".

It is possible to include a sign for all elements that is output.  See the

configuration variable DeltaSigns below.

NOTE: The internal format of the delta changed in version 5.30 from

Y:M:D:H:MN:S to Y:M:W:D:H:MN:S .  Also, it is going to change again at some

point in the future to Y:M:W:D:H:MN:S*FLAGS .  Use the routine Delta_Format

to extract information rather than parsing it yourself.

=item B<Delta_Format>

 @str = Delta_Format($delta [,$mode], $dec,@format);

 $str = Delta_Format($delta [,$mode], $dec,@format);

This is similar to the UnixDate routine except that it extracts information

from a delta.  Unlike the UnixDate routine, most of the formats are 2

characters instead of 1.

Formats currently understood are:

   %Xv     : the value of the field named X

   %Xd     : the value of the field X, and all smaller fields, expressed in

             units of X

   %Xh     : the value of field X, and all larger fields, expressed in units

             of X

   %Xt     : the value of all fields expressed in units of X

   X is one of y,M,w,d,h,m,s (case sensitive).

   %%      : returns a "%"

So, the format "%hd" means the values of H, MN, and S expressed in hours.

So for the delta "0:0:0:0:2:30:0", this format returns 2.5.

Delta_Format can operate in two modes: exact and approximate. The exact

mode is done by default. Approximate mode can be done by passing in

the string "approx" as the 2nd argument.

In exact mode, Delta_Format only understands "exact" relationships. This

means that there can be no mixing of the Y/M and W/D/H/MN/S segments

because the relationship because, depending on when the delta occurs, there

is no exact relation between the number of years or months and the number

of days.

The two sections are treated completely separate from each other. So,

the delta "1:6:1:2:12:0:0" would return the following values:

  %yt = 1.5 (1 year, 6 months)

  %Mt = 18

  %dt = 9.5 (1 week, 2 days, 12 hours)

In approximate mode, the relationship of 1 year = 365.25 days is applied

(with 1 month equal to 1/12 of a year exactly). So the delta

"1:6:1:2:12:0:0" would return the following values:

  %dt = 557.375 (1.5 years of 365.25 days + 9.5 days)

If $dec is non-zero, the %Xd and %Xt values are formatted to contain $dec

decimal places.

=item B<ParseRecur>

 $recur = ParseRecur($string [,$base,$date0,$date1,$flags]);

 @dates = ParseRecur($string [,$base,$date0,$date1,$flags]);

A recurrence refers to a recurring event, and more specifically, an event

which occurs on a regular basis.  A fully specified recurring event

may requires up to four pieces of information.

First, it requires a description of the frequency of the event.  Examples

include "the first of every month", "every other day", "the 4th

Thursday of each month at 2:00 PM", and "every 2 hours and 30 minutes".

Second, it may require a base date to work from.  This piece of information

is not required for every type of recurrence.  For example, if the

frequency is "the first of every month", no base date is required.  All the

information about when the event occurs is included in the frequency

description.  If the frequency were "every other day" though, you need to

know at least one day on which the event occurred.

Third, the recurring event may have a range (a starting and ending date).

Fourth, there may be some flags included which modify the behavior of the

above information.

The fully specified recurrence is written as these 5 pieces of information

(both a start and end date) as an asterisk separated list:

  freq*flags*base*date0*date1

Here, base, date0, and date1 are any strings (which must not contain any

asterisks) which can be parsed by ParseDate.  flags is a comma separated

list of flags (described below), and freq is a string describing the

frequency of the recurring event.

The syntax of the frequency description is a colon separated list of the

format Y:M:W:D:H:MN:S (which stand for year, month, week, etc.).  One (and

only one) of the colons may optionally be replaced by an asterisk, or an

asterisk may be prepended to the string.  For example, the following are

all valid frequency descriptions:

  1:2:3:4:5:6:7

  1:2*3:4:5:6:7

 *1:2:3:4:5:6:7

But the following are NOT valid because they contain 2 or more asterisks:

  1:2*3:4:5*6:7

  1*2*3:4:5*6:7

 *1:2:3:4:5:6*7

If an asterisk is included, values to the left of it refer to the number of

times that time interval occurs between recurring events.  For example,

if the first part of the recurrence is:

  1:2*

this says that the recurring event occurs approximately every 1 year and 2

months.  I say approximately, because elements to the right of the asterisk,

as well as any flags included in the recurrence will affect when the actual

events occur.

If no asterisks are included, then the entire recurrence is of this form.

For example,

  0:0:0:1:12:0:0

refers to an event that occurs every 1 day, 12 hours.

Values that occur after an asterisk refer to a specific value for that type

of time element (i.e. exactly as it would appear on a calendar or a clock).

For example, if the recurrence ends with:

  *12:0:0

then the recurring event occurs at 12:00:00 (noon).

For example:

  0:0:2:1:0:0:0        every 2 weeks and 1 day

  0:0:0:0:5:30:0       every 5 hours and 30 minutes

  0:0:0:2*12:30:0      every 2 days at 12:30 (each day)

Values to the right of the asterisk can be listed a single values, ranges

(2 numbers separated by a dash "-"), or a comma separated list of values

or ranges.  In most cases, negative values are appropriate for the week

or day values. -1 stands for the last possible value, -2 for the second

to the last, etc.

Some examples are:

  0:0:0:1*2,4,6:0:0    every day at at 2:00, 4:00, and 6:00

  0:0:0:2*12-13:0,30:0 every other day at 12:00, 12:30, 13:00,

                       and 13:30

  0:1:0*-1:0:0:0       the last day of every month

  *1990-1995:12:0:1:0:0:0

                       Dec 1 in 1990 through 1995

There is no way to express the following with a single recurrence:

  every day at 12:30 and 1:00

You have to use two recurrences to do this.

When a non-zero day element occurs to the right of the asterisk, it can take

on multiple meanings, depending on the value of the month and week

elements.  It can refer to the day of the week, day of the month, or day of

the year.  Similarly, if a non-zero week element occurs to the right of

the asterisk, it actually refers to the nth time a certain day of the week

occurs, either in the month or in the year.

If the week element is non-zero and the day element is non-zero (and to the

right of the asterisk), the day element refers to the day of the week. It

can be any value from 1 to 7 (negative values -1 to -7 are also

allowed). If you use the ISO 8601 convention, the first day of the week is

Monday (though Date::Manip can use any day as the start of the week by

setting the FirstDay config variable).  So, assuming that you are using the

ISO 8601 convention, the following examples illustrate day-of-week

recurrences:

  0:1*4:2:0:0:0        4th Tuesday (day 2) of every month

  0:1*-1:2:0:0:0       last Tuesday of every month

  0:0:3*2:0:0:0        every 3rd Tuesday (every 3 weeks

                       on 2nd day of week)

  1:0*12:2:0:0:0       the 12th Tuesday of each year

If the week element is non-zero, and the day element is zero, the day

defaults to 1 (i.e. the first day of the week).

  0:1*2:0:0:0:0        the 2nd occurrence of FirstDay

                       in the year (typically Monday)

  0:1*2:1:0:0:0        the same

If the week element is zero and the month element is non-zero, the day

value is the day of the month (it can be from 1 to 31 or -1 to -31 counting

from the end of the month). If a value of 0 is given, it defaults to 1.

  3*1:0:2:12:0:0       every 3 years on Jan 2 at noon

  0:1*0:2:12,14:0:0    2nd of every month at 12:00 and 14:00

  0:1:0*-2:0:0:0       2nd to last day of every month

If the day given refers to the 29th, 30th, or 31st, in a month

that does not have that number of days, it is ignored. For example,

if you ask for the 31st of every month, it will return dates in Jan,

Mar, May, Jul, etc.  Months with fewer than 31 days will be ignored.

If both the month and week elements are zero, and the year element

is non-zero, the day value is the day of the year (1 to 365 or 366 -- or

the negative numbers to count backwards from the end of the year).

  1:0:0*45:0:0:0       45th day of every year

Specifying a day that doesn't occur in that year silently ignores that

year. The only result of this is that specifying +366 or -366 will ignore

all years except leap years.

I realize that this looks a bit cryptic, but after a discussion on the

CALENDAR mailing list, it appeared like there was no concise, flexible

notation for handling recurring events.  ISO 8601 notations were very bulky

and lacked the flexibility I wanted.  As a result, I developed this

notation (based on crontab formats, but with much more flexibility) which

fits in well with this module. Even better, it is able to express every

type of recurring event I could think of that is used in common life in

(what I believe to be) a very concise and elegant way.

If ParseRecur is called in scalar context, it returns a string containing a

fully specified recurrence (or as much of it as can be determined with

unspecified fields left blank).  In list context, it returns a list of all

dates referred to by a recurrence if enough information is given in the

recurrence.  All dates returned are in the range:

  date0 <= date < date1

The argument $string can contain any of the parts of a full recurrence.

For example:

  freq

  freq*flags

  freq**base*date0*date1

The only part which is required is the frequency description.  Any values

contained in $string are overridden or modified by values passed in as

parameters to ParseRecur.

NOTE: If a recurrence has a date0 and date1 in it AND a date0 and date1

are passed in to the function, both sets of criteria apply.  If flags are

passed in, they override any flags in the recurrence UNLESS the flags

passed in start with a plus (+) character in which case they are appended

to the flags in the recurrence.

NOTE: Base dates are only used with some types of recurrences.  For example,

  0:0:3*2:0:0:0        every 3rd Tuesday

requires a base date.  If a base date is specified which doesn't match the

criteria (for example, if a base date falling on Monday were passed in with

this recurrence), the base date is moved forward to the first relevant date.

Other dates do not require a base date.  For example:

  0:0*3:2:0:0:0        third Tuesday of every month

A recurrence written in the above format does NOT provide default values

for base, date0, or date1.  They must be specified in order to get a list

of dates.

A base date is not used entirely.  It is only used to provide the parts