# Copyright (c) 1995-2003 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.

=head1 NAME

Date::Manip - date manipulation routines

=head1 SYNOPSIS

 use Date::Manip;

 $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);

 $version = DateManipVersion;

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

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

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

 $name = Date_IsHoliday($date);

 $listref = Events_List($date);

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

 &Date_Init();

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

 @list = Date_Init();

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

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 explicitely unless you want to change some of the

config variables (described below).

The following routines are used by the above routines (though they can also

be called directly).  $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).

***NOTE*** Unlike the routines listed above, the following routines do NOT

explicitely call Date_Init.  You must make sure that Date_Init has been

called, either by you explicitely, or by one of the above routines before you

use these routines.

 $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);

 $days = Date_DaysInYear($y);

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

 $flag = Date_LeapYear($y);

 $day = Date_DaySuffix($d);

 $tz = Date_TimeZone();

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

=head1 DESCRIPTION

This is a set of routines designed to make any common date/time

manipulation easy to do.  Operations such as comparing two times,

calculating a time a given amount of time from another, or parsing

international times are all easily done.  From the very beginning, the main

focus of Date::Manip has been to be able to do ANY desired date/time

operation easily, not necessarily quickly.  Also, it is definitely oriented

towards the type of operations we (as people) tend to think of rather than

those operations used routinely by computers.  There are other modules that

can do a subset of the operations available in Date::Manip much quicker

than those presented here, so be sure to read the section SHOULD I USE

DATE::MANIP below before deciding which of the Date and Time modules from

CPAN is for you.

Date::Manip deals with time as it is presented the Gregorian calendar (the

one currently in use).  The Julian calendar defined leap years as every 4th

year.  The Gregorian calendar improved this by making every 100th year NOT

a leap year, unless it was also the 400th year.  The Gregorian calendar has

been extrapolated back to the year 0000 AD and forward to the year 9999 AD.

Note that in historical context, the Julian calendar was in use until 1582

when the Gregorian calendar was adopted by the Catholic church.  Protestant

countries did not accept it until later; Germany and Netherlands in 1698,

British Empire in 1752, Russia in 1918.  Note that the Gregorian calendar

is itself imperfect and at some point will need to be corrected.  No attempt

is made to correct for that, and my great great great grandchildren will be

long dead before this even occurs, so it's not an immediate concern.  Yes,

this is the same type of attitute that caused the great Y2K problem... but

I have an excuse: I don't know what the correction will be, so I can't

possible implement it.  Nobody doubted that the year after 1999 would be

known as 2000 :-).

Date::Manip is therefore not equipped to truly deal with historical dates,

but should be able to perform (virtually) any operation dealing with a

modern time and date.

Date::Manip has (or will have) functionality to work with several fundamental

types of data.

=over 4

=item DATE

Although the word date is used extensively here, it is actually somewhat

misleading.  Date::Manip works with the full date AND time (year, month,

day, hour, minute, second and weeks when appropriate).  It doesn't work

with fractional seconds.  Timezones are also supported to some extent.

NOTE:  Much better support for timezones (including Daylight Savings Time)

is planned for the future.

=item DELTA

This refers to a duration or elapsed time.  One thing to note is that, as

used in this module, a delta refers only to the amount of time elapsed.  It

includes no information about a starting or ending time.

=item RECURRENCE

A recurrence is simply a notation for defining when a recurring event

occurs.  For example, if an event occurs every other Friday or every

4 hours, this can be defined as a recurrence.  With a recurrence and a

starting and ending date, you can get a list of dates in that period when

a recurring event occurs.

=item GRAIN

The granularity of a time basically refers to how accurate you wish to

treat a date.  For example, if you want to compare two dates to see if

they are identical at a granularity of days, then they only have to occur

on the same day.  At a granularity of an hour, they have to occur within

an hour of each other, etc.

NOTE:  Support for this will be added in the future.

=item HOLIDAYS and EVENTS

These are basically a named time.  Holidays are used in business mode

calculations.  Events allow things like calendar and scheduling

applications to be designed much more easily.

=back

Among other things, Date::Manip allow you to:

1.  Enter a date and be able to choose any format convenient

2.  Compare two dates, entered in widely different formats

    to determine which is earlier

3.  Extract any information you want from ANY date using a

    format string similar to the Unix date command

4.  Determine the amount of time between two dates

5.  Add a time offset to a date to get a second date (i.e.

    determine the date 132 days ago or 2 years and 3 months

    after Jan 2, 1992)

6.  Work with dates with dates using international formats

    (foreign month names, 12/10/95 referring to October

    rather than December, etc.).

7.  To find a list of dates where a recurring event happens.

Each of these tasks is trivial (one or two lines at most) with this package.

=head1 EXAMPLES

In the documentation below, US formats are used, but in most (if not all)

cases, a non-English equivalent will work equally well.

1.  Parsing a date from any convenient format

  $date = ParseDate("today");

  $date = ParseDate("1st thursday in June 1992");

  $date = ParseDate("05/10/93");

  $date = ParseDate("12:30 Dec 12th 1880");

  $date = ParseDate("8:00pm december tenth");

  if (! $date) {

    # Error in the date

  }

2.  Compare two dates

  $date1 = ParseDate($string1);

  $date2 = ParseDate($string2);

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

  if ($flag<0) {

    # date1 is earlier

  } elsif ($flag==0) {

    # the two dates are identical

  } else {

    # date2 is earlier

  }

3.  Extract information from a date.

  print &UnixDate("today","It is now %T on %b %e, %Y.");

    =>  "It is now 13:24:08 on Feb  3, 1996."

4.  The amount of time between two dates.

  $date1 = ParseDate($string1);

  $date2 = ParseDate($string2);

  $delta = DateCalc($date1,$date2,\$err);

    => 0:0:WK:DD:HH:MM:SS   the weeks, days, hours, minutes,

                            and seconds between the two

  $delta = DateCalc($date1,$date2,\$err,1);

    => YY:MM:WK:DD:HH:MM:SS  the years, months, etc. between

                             the two

  Read the documentation below for an explanation of the

  difference.

5.  To determine a date a given offset from another.

  $date = DateCalc("today","+ 3hours 12minutes 6 seconds",\$err);

  $date = DateCalc("12 hours ago","12:30 6Jan90",\$err);

  It even works with business days:

  $date = DateCalc("today","+ 3 business days",\$err);

6.  To work with dates in another language.

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

  $date = ParseDate("1er decembre 1990");

7.  To find a list of dates where a recurring event happens

    (including quite complex ones).

  # To find the 2nd tuesday of every month

  @date = ParseRecur("0:1*2:2:0:0:0",$base,$start,$stop);

  # To find the Monday after easter in 1997-1999.

  @date = ParseRecur("*1997-1999:0:0:0:0:0:0*EASTER,ND1");

NOTE: Some date forms do not work as well in languages other than English,

but this is not because Date::Manip is incapable of doing so (almost nothing

in this module is language dependent).  It is simply that I do not have the

correct translation available for some words.  If there is a date form that

works in English but does not work in a language you need, let me know and

if you can provide me the translation, I will fix Date::Manip.

=head1 SHOULD I USE DATE::MANIP

If you look in CPAN, you'll find that there are a number of Date and Time

packages.  Is Date::Manip the one you should be using?  In my opinion, the

answer is no most of the time.  This sounds odd coming from the author of

the software, but read on.

Date::Manip is written entirely in perl.  It's the most powerful of the

date modules.  It's also the biggest and slowest.

Since Date::Manip is written entirely in perl, and depends on no other

module not in a standard perl distribution, Date::Manip has no dependancies

to meet.  Other modules have dependancies on a C compiler or other perl

modules.  Since it is fairly easy to satisfy these dependancies for

anyone who is reasonably familiar with perl modules, this is not a

huge advantage that Date::Manip has.

On the other hand, simpler perl modules tend to be faster than Date::Manip,

and modules written in C are significantly faster than their perl

counterparts (at least if they're done right).  The TimeDate and

Time-modules modules are written in perl, but are much simpler (and

hence, faster) than Date::Manip.  The Date::Calc module is written in C

and is a good module for doing many date calculations much faster than

Date::Manip.  Between these three, most of your common date operations

can be done.

Date::Manip is certainly the most powerful of the Date modules.  To the

best of my knowledge, it will do everything that any other date module will

do (not just the ones I listed above), and there are a number of features

that Date::Manip has that none of the other modules have.  Date::Manip is

the "Swiss Army Knife" of Date modules.  I'm trying to build a library

which can do _EVERY_ conceivable date/time manipulation that you'll run

into in everyday life.

Although I am working on making Date::Manip faster, it will never be as

fast as other modules.  And before anyone asks, Date::Manip will never

be translated to C (at least by me).  I write C because I have to.  I

write perl because I like to.  Date::Manip is something I do because it

interests me, not something I'm paid for.

Date::Manip is also big.  The last time I looked, it's one of the largest

CPAN modules there is.  If you ignore modules like Tk, LWP, etc. which are

actually packages of modules, it may be the largest.  It's true that

Date::Manip will do almost every date operation you could imagine... but

you rarely need all that power.  I'm working on reducing the footprint of

Date::Manip, but even at it's slimmest, it'll outweigh the other modules by

a good bit.

If you are going to be using the module in cases where performance is an

important factor (started up in a CGI program being run by your web server

5,000 times a second), you should check out one of the other Date or Time

modules in CPAN.  If you're only doing fairly simple date operations

(parsing common date formats, finding the difference between two dates,

etc.), the other modules will almost certainly suffice.  If you're doing

one operation very repetitively (parsing 10,000 dates from a database), you

are probably better off writing your own functions (perhaps bypassing all

date modules entirely) designed specifically for your needs.

On the other hand, if you want one solution for all your date needs, don't

need peak speed, or are trying to do more exotic date operations,

Date::Manip is for you.  Operations on things like business dates, foreign

language dates, holidays and other recurring events, etc. are available

more-or-less exclusively in Date::Manip.

=head1 ROUTINES

=over 4

=item 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 ParseDateString

 $date = ParseDateString($string);

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

to save some time (a negligable 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 timezone.  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 ocurring).

Timezones always appear immediately after the time.  A number of different

forms are supported (see the section TIMEZONEs 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.

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 timezone for an ISO-8601

date is flexible and may be any of the timezones 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)