Subject: ANNOUNCE: Date::DateCalc 2.0
From: [email-masked] (Steffen Beyer)
Date: 25 May 1996 19:00:13 GMT
Newsgroups: comp.lang.perl.announce,comp.lang.perl.misc

The module "Date::DateCalc" has been further refined and is now available
as version 2.0 at the usual ftp sites (see below for more details).

=======================================
  Module "Date::DateCalc" Version 2.0
=======================================

Requirements:
-------------

Perl version 5.000 or higher, a compiler complying with ANSI C standards (!).
                              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
What does it do:
----------------

The package provides a Perl interface to a C library which offers a wide
variety of date calculations, complying with the ISO/R 2015-1971 and DIN
1355 standards which specify things as what leap years are, when they
occur, how the week numbers are defined, what's the first day of the week,
how many weeks (52 or 53) a given year has, and so on (Gregorian calendar,
as opposed to the Julian calendar, which was used until 1582).

To give you an idea of what the package can do, here a list of all the
functions it exports:

  $flag = leap($year);
  $date = compress($yy,$mm,$dd);
  ($cc,$yy,$mm,$dd) = uncompress($date);
  $flag = check_compressed($date);
  $datestr = compressed_to_short($date);
  $flag = check_date($year,$mm,$dd);
  $days = calc_days($year,$mm,$dd);
  $weekday = day_of_week($year,$mm,$dd);
  $days = dates_difference($year1,$mm1,$dd1,$year2,$mm2,$dd2);
  ($year,$mm,$dd) = calc_new_date($year,$mm,$dd,$offset);
  ($days,$hh,$mm,$ss) = date_time_difference
  (
      $year1,$month1,$day1,$hh1,$mm1,$ss1,  # calculates date2
      $year2,$month2,$day2,$hh2,$mm2,$ss2   # minus date1
  );
  ($year,$month,$day,$hh,$mm,$ss) = calc_new_date_time
  (
      $year,$month,$day,$hh,$mm,$ss,
      $days_offset,$hh_offset,$mm_offset,$ss_offset
  );
  $datestr = date_to_short($year,$mm,$dd);
  $datestr = date_to_string($year,$mm,$dd);
  ($week,$year) = week_number($year,$mm,$dd);
  ($year,$mm,$dd) = first_in_week($week,$year);
  $weeks = weeks_in_year($year);
  $day_name = day_name_tab($weekday);
  $month_name = month_name_tab($month);
  $weekday = decode_day($day_name);
  $month = decode_month($month_name);
  ($year,$mm,$dd) = decode_date($date);
  $days = days_in_month($year,$mm);
  $version = Date::DateCalc::Version();

For more details, see the Date::DateCalc(3) man page!

What's new in version 2.0:
--------------------------

The two functions "day_short_tab" and "month_short_tab" are gone,
these tables are not needed any longer internally. Substitute them
with substr(day_name_tab($dd),0,3) and substr(month_name_tab($mm),0,3),
respectively.

The functions "encode", "decode", "valid_date" and "date_string"
have been renamed to "compress", "uncompress", "check_compressed"
and "compressed_to_short", respectively, to reflect the fact that
they belong together and to make the user interface more consistent.

Two new functions have been added: "decode_day" and "decode_month".
They take the name of a day or month as their argument and return
its number.

The function "day_of_week" has been changed. It now returns values
in the range 1..7 (as opposed to 0..6 previously). This is to make
things more consistent and to make the function "decode_day" work
exactly as "decode_month" (which was already present in previous
versions but was not exported, btw).

Since the table "day_name_tab" has been changed accordingly, you'll
probably don't need to change existing code.

Two more functions are new: "date_time_difference" and "calc_new_date_time".
They allow to calculate differences in dates and new dates which include not
only year, month and day, but also hour, minute, and second. They are exten-
sions of the functions "dates_difference" and "calc_new_date" (which they
also use).

A utility has been added to the package ("parse_date.pl") which allows
you to parse dates as returned by the UNIX "date" command. You can also
parse the date of submitment of mails this way. This allows you to deter-
mine the time the mail took to arrive, or you can automatically increase
the priority of problem reports as time passes by, for instance. (This
latter tool can be obtained by sending me a mail <[email-masked]>.)

The german man-page is gone, it is too much effort to maintain two
versions of the man-page. Sorry.

Thanks:
-------

Many thanks to Tom Limoncelli <[email-masked]> for raising the question on
how to calculate the 2nd Thursday of a given month and year!

Many thanks to Bart Robinson <[email-masked]> for suggesting the "all"
export option and the "decode_day" and "decode_month" functions.

Also many thanks to Ron Savage <[email-masked]> for suggesting
the incorporation of time calculations into this module. (Sorry that I
didn't include the handling of time zones, which can be taken care of
more easily by adding/subtracting the appropriate time value in an extra,
preliminary step!)

Where to find:
--------------

At the usual ftp sites for Perl (CPAN = "Comprehensive Perl Archive Network"),

under     .../CPAN/authors/id/STBEY/

or        .../CPAN/modules/by-category/06_Data_Type_Utilities/Date/

or        .../CPAN/modules/by-module/Date/

(See news:comp.lang.perl.announce for a list of CPAN ftp servers)

Final note:
-----------

Please report any comments, problems, suggestions, findings, complaints,
questions, insights, compliments or donations ;-) and so on to:

[email-masked] (Steffen Beyer)

Have fun!

Best regards,
--
Steffen Beyer
mailto:[email-masked]        |s  |d &|m  |  software design & management GmbH&Co.KG
phone: +49 89 63812-244 |   |   |   |  Thomas-Dehler-Str. 27
fax:   +49 89 63812-150 |   |   |   |  81737 Munich, Germany.