Subject: ANNOUNCE: Date::DateCalc 3.0
From: [email-masked] (Steffen Beyer)
Date: 17 Feb 1997 14:26:04 GMT
Newsgroups: comp.lang.perl.announce,comp.lang.perl.modules

I am glad to announce

========================================
  Package "Date::DateCalc" Version 3.0
========================================

to the Perl community.

I have just uploaded the new distribution ("DateCalc-3.0.tar.gz") to
PAUSE, from where it should propagate to a CPAN ftp site near you in
a matter of a few days (this message was submitted on 16-Feb-1997).

Contents of this message:
-------------------------

    -   What's new?
    -   Legal stuff
    -   Requirements
    -   What does it do
    -   Credits
    -   Where to find
    -   Final note

What's new?
-----------

In version 3.0 of the "Date::DateCalc" module, the convention for unsuccess-
ful return has been changed for all functions which return a LIST of values:
instead of returning zeros in all list items as in previous versions, an
EMPTY LIST is now returned.

Affected functions are:

    +   ($cc,$yy,$mm,$dd) = uncompress($date);

    +   ($year,$mm,$dd) = calc_new_date($year,$mm,$dd,$offset);

    +   ($days,$hh,$mm,$ss) = date_time_difference
        (
            $year1,$month1,$day1,$hh1,$mm1,$ss1,
            $year2,$month2,$day2,$hh2,$mm2,$ss2
        );

    +   ($year,$month,$day,$hh,$mm,$ss) = calc_new_date_time
        (
            $year,$month,$day,$hh,$mm,$ss,
            $days_offset,$hh_offset,$mm_offset,$ss_offset
        );

    +   ($week,$year) = week_number($year,$mm,$dd);

    +   ($year,$mm,$dd) = first_in_week($week,$year);

    +   ($year,$mm,$dd) = decode_date($date);

This way it is now possible to assign the return values to a list of
variables or an array and to test wether the function call was success-
ful at the same time, i.e.:

        if (($year,$mm,$dd) = decode_date($date))
        {
            # do something with the data returned...
        }
        else
        {
            # issue an error message or do something else...
        }

(Note that the "demo" program has been changed accordingly!)

Note also that these changes had deep repercussions into the associated
C library (file "lib_date.c"). The code of the corresponding C functions
has changed significantly in some places, as well as their return values
(from "void" to "boolean").

Moreover, in version 3.0 of the "Date::DateCalc" package, a new module
called "Date::DateCalcLib" has been added which offers some useful date
calculation functions for some special problems like the nth weekday in
a given month and year, calculating a new date with year, month and day
offsets, calculating easter sunday, and more. (See the "Date::DateCalcLib"
man page for more details!)

This module incorporates a couple of functions that previously were loosely
spread over a number of perl script files, i.e., it now contains the func-
tions previously implemented in "demo2" and "demo_us", which now rather use
this module, and the functionality of the "parse_date.pl" script, which has
become obsolete and is gone in this version.

Note that the functions in this module which return lists also follow the
new convention for return values in case of error and return an empty list
if their arguments are illegal. Note further that the programs "demo2" and
"demo_us" have been adapted accordingly.

Legal stuff:
------------

Copyright (c) 1995, 1996, 1997 by Steffen Beyer. All rights reserved.
This package is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

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

Perl version 5.000 or higher, a C compiler capable of the ANSI C standard (!)
                              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

What does it do:
----------------

The package provides a Perl interface to a C library which offers a wide
variety of date calculations based on the Gregorian calendar (the one
used in all western countries today), 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.
 
Although the Gregorian calendar was only adopted 1582 by most (not all)
European countries (some countries continued to use the Julian calendar
until as late as the beginning of the 20th century!), this package allows
you to extrapolate the Gregorian calendar back until the year 1.

This module is not intended to be the most comfortable approach to every
date calculation problem there is, but instead it's meant to be a *minimal*
and *complete* (in the sense of computation theory!) set of tools to solve
any date calculation problem you might ever encounter.

Therefore, the interfaces of these routines are designed for a maximum of
flexibility and a minimum of overhead. Just like the UNIX commands "cat",
"grep" and so on which do very simple tasks but can do many useful jobs
when combined in a cunning way, the routines in this package are intended
to be *elementary*, i.e., indivisible basic functions.

Moreover, the module is mainly written in C so that the C part can be used
as a stand-alone library in other applications than Perl. (!!!)

A library of useful date calculation functions is available for some special
problems like the nth weekday in a given month and year, calculating a new
date with year, month and day offsets, calculating easter sunday, and more.
(See the "Date::DateCalcLib" man page for more details!)

To give you an idea of what the "Date:DateCalc" module can do, here a list
of all the functions it exports:

  $flag = leap($year);
  $flag = check_date($year,$mm,$dd);
  $date = compress($yy,$mm,$dd);
  ($cc,$yy,$mm,$dd) = uncompress($date);
  $flag = check_compressed($date);
  $datestr = compressed_to_short($date);
  $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,
      $year2,$month2,$day2,$hh2,$mm2,$ss2
  );
  ($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" man page!

Credits:
--------

Many thanks to Jonas Liljegren <[email-masked]> for posting a subroutine
for calculating easter monday in news:comp.lang.perl.modules and thereby
triggering my writing of the new "Date::DateCalcLib" module which has been
added in version 3.0 of the "Date::DateCalc" distribution.

Also many thanks to Claus Tondering <[email-masked]> for his excellent
web pages and FAQ in news:news.answers about calendars and how to calcu-
late easter sunday.

Thanks to Reinhold Stansich <[email-masked]> for posting a list
of christian feast days and their offsets from easter sunday in news:
comp.databases.ms-access and to Tammo Schnieder <[email-masked]>
for sending me his posting.

Many thanks to Max Ruffert <[email-masked]> at the Max Planck
Institute for Astrophysics in Garching for looking up Gauss' Rule for
calculating easter sunday (the algorithm which is implemented in the
"Date::DateCalcLib" module) for me and dictating it to me over the
phone!

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

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

The file

        DateCalc-3.0.tar.gz

can be found in directory

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

or

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

or

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

See "The Perl 5 Module List" by Tim Bunce and Andreas Koenig in news:
comp.lang.perl.modules for a list of CPAN ftp servers, or direct your
WWW browser to

http://www.perl.com/CPAN/modules/by-module/Date/DateCalc-3.0.tar.gz

and you will automatically be redirected to a CPAN ftp server near you.

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

If you need any assistance or have any comments, problems, suggestions,
findings, complaints, questions, insights, compliments or donations to give ;-)
then please don't hesitate to send me a mail:

[email-masked] (Steffen Beyer)

In fact I'd be glad if you could drop me an e-mail when you are using this
package, so I can see how much interest exists in it and how much time is
reasonable to spend on its further development.

Therefore, I would also be glad to know what you liked and what you disliked
about this package!

And I would also be very interested to know what your application is in
which you found this package to be useful, just to get an idea what can
all be done with it and in which direction it should be developed further.

Many thanks in advance!!

With kind regards,
--
          _____        _____      .__        
        _/ ____\____ _/ ____\____ |__|______ 
        \   __\\__  \\   __\/    \|  \_  __ \       Steffen Beyer
         |  |   / __ \|  | |   |  \  ||  | \/         [email-masked]
         |__|  (____  /__| |___|  /__||__|           [email-masked]
                    \/          \/