Subject: ANNOUNCE: Date::Manip 5.21 and 5.30
From: [email-masked] (Sullivan N. Beck)
Date: 22 Jan 1998 23:23:15 GMT
Newsgroups: comp.lang.perl.announce,comp.lang.perl.modules

This is to announce that Date::Manip 5.21 and 5.30 have been released to CPAN.

5.21 fixes the broken test suite (it broke when we hit 1998).  It will not
break again in the future.  It also fixes a few bugs and has some improvements
over 5.20, most notably it passes taint checks and is about 25% faster.

5.30 has an important incompatibility with 5.21 .  The delta has an additional
field (a week field was added so it is now year:month:week:day:hr:min:sec). A
new function (Delta_Format) is now provided to extract information from a delta
in a similar fashion to using UnixDate to extract information from a date.

5.30 also has a nice, new feature.  It can return a list of dates for a
recurring event (i.e. 2nd tuesday of every month or every 5 hours 30 minutes).

As always, the module is available from my home page and CPAN within a day or
two.

Here's the README file:

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

For information on installing Date::Manip, see the INSTALL file included in
the distribution.

Please send questions or bug reports to me rather than posting them to
a newsgroup since I may miss them there, BUT read the next paragraph
before you automatically start firing off email to me!

If you have questions about Date::Manip, refer to the Date::Manip man page
included as pod documentation in the Manip.pm file.  Don't know what I'm
talking about?  Read the perlpod man page.  Alternately, an online version
of the Date::Manip man page is included in my home page given below.
PLEASE read the man page thoroughly before posting any questions about
Date::Manip to a newsgroup or emailing me.  If you've done this, I'll be
glad to answer any questions not covered in the man page.

** IMPORTANT NOTE **
The internal format of a delta has changed (a week field has been added).
I realize that this is going to cause some problems, but I am adding two
other types of data (granularity and recurrence) to Date::Manip.  Both
will resemble a delta, and both will have week fields, and I wanted all three
to be as similar as possible.  You should use Delta_Format to extract
information from a delta from now on rather than doing it manually.  This is
especially important since the format for a delta will be changed again in one
of the next versions from Y:M:W:D:H:MN:S to Y:M:W:D:H:MN:S*FLAGS.

I also plan on changing the internal format for a date to include
the timezone ( YYYYMMDDHH:MN:SS+HHMN ).  Using UnixDate to extract information
from a date is recommended.

Notes for version 5.30:
  *** Deltas now have a week field: Y:M:W:D:H:Mn:S
  *** Added ParseRecur.
  Added the Delta_Format function.
  Added Date_SetDateField function.
  All routines now handle 2 or 4 digit years.

Notes for version 5.21:
  Now passes taint checks (for 5.004_03 ... I haven't checked 5.004_04
    which apparently does better taint checking).
  Several speedups (significantly faster now).
  Added some config variables:
    YYtoYYYY, UpdateCurrTZ, TomorrowFirst
  Added the Date_NearestWorkDay function
  Some minor bugfixes.
  Fixed handling of ISO 8601 weeks 01, 52, and 53 (and added %G and %L formats
    to UnixDate to acommadate this).
  Better handling of foreign languages (now handles accents reasonably well).
  Several minor additions to parsing formats:
    British date formats
    Added Sept as a valid abbreviation
    Time can be written as 5pm
  Added ForceDate variable.
  Tests now work for all years.

Notes for version 5.20:
  *** Added ISO 8601 date formats.
  Added ParseDateString for speed.
  Changed week handling to meet ISO 8601 standards.
  Added %J and %K UnixDate formats.
  Added some speedups (more to come).
  Added more Parse formats:
     last day in mmm in YY             "last day of October"
     dofw                              "Friday" (Friday of current week)
     Nth                               "12th", "1st" (day of current month)

Backwards incompatibilities:

  Version 5.30
    The internal format of a delta has changed.  This will cause some people
       problems.  Use the routine Delta_Format to extract information from
       a delta.

  Version 5.21
    When running processes (running over time zone changes).  See UpdateCurrTZ
       documentation.
    The UnixDate formats %W and %U no longer return week 00.

  Version 5.20
    Some old formats were removed since they conflicted with ISO 8601
       formats.  MM-DD-YY (conflicts with YY-MM-DD), YYMMDD (conflicts
       with YYYYMM).
    Weekdays are now numbered 1-7 (mon-sun) instead of 0-6 (sun-sat)
    By default the week now starts with Monday instead of Sunday to meet
       ISO 8601.  The FirstDay variable can be set to 7 to set Sunday as
       the first day.
    By default, the 1st week of the year contains Jan 4 (ISO 8601).  See
       the Jan1Week1 variable for overriding this.

  ############################################################################
  If you would like to stay informed about future versions of this module,
  and especially if you are interested in beta testing future versions,
  please let me know by email at:
    [email-masked]

  The newest version (which should be considered a beta version) is available
  through my home page:
    http://www.qtp.ufl.edu/~beck
  Feel free to try it out.

  The current (non-beta) version of this module is available from you nearest
  CPAN site and is NOT available from my home page.  I will announce new
  (non-beta) releases in comp.lang.perl.misc and comp.lang.perl.announce.
  ############################################################################

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.

Date::Manip deals only with 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 1000 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.  Each year is on average 26 seconds too long, which
means that every 3,323 years, a day should be removed from the calendar.
No attempt is made to correct for that.

Date::Manip is therefore not equipped to truly deal with historacle dates,
but should be able to perform (virtually) any operation dealing with a
modern time and date.

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

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

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.

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 will ignore fractional seconds).

In the documentation below, US formats are used, but in most (if not all)
cases, a non-English equivalent will work equally well.

EXAMPLES:

1.  Parsing a date from any conveniant 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);
  if ($date1 lt $date2) {
    # date1 is earlier
  } else {
    # date2 is earlier (or the two dates are identical)
  }

3.  Extract information from a date.

  print &UnixDate("today","The time is now %T on %b %e, %Y.");
  =>  "The time 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:DD:HH:MM:SS   the days, hours, minutes, and seconds between the two
  $delta=&DateCalc($date1,$date2,\$err,1);
  => YY:MM:DD:HH:MM:SS  the years, months, etc. between the two

  Read the documentation in the man page 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.

  # To find the 2nd tuesday of every month
  @date=&ParseRecur("0:1*2:2:0:0:0",$base,$start,$stop);

NOTE: Some date forms do not work as well in languages other than English,
but this is not because DateManip 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 DateManip.

For documentation on all of the date manipulation routines, read the
man page.

AUTHOR

Sullivan Beck ([email-masked])

------------------------------------------------------------------------------
Sullivan Beck                      http://www.cise.ufl.edu/~sbeck/
 [email-masked]  | This space reserved for some saying demonstrating great
 PH : (352) 392-1057 | wisdom, wit, or insight.  I'll fill it in just as soon
 Fax: (352) 392-1220 | as I have any of the above.
------------------------------------------------------------------------------