                   ========================================
                     Package "Date::DateCalc" Version 3.2
                   ========================================
                       for Perl version 5.000 and higher


     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.


Contents of this file:
----------------------

  -  What's new in version 3.2
  -  What's new in version 3.1
  -  Most important differences between versions 2.x and 3.0
  -  Most important differences between versions 1.x and 2.x
  -  Version history in details


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

A new function "week_of_year()" has been added to the C library "lib_date.c"
which implements the little piece of code that was formerly contained in the
XS function "week_number" (which now uses this new C function instead).

The Perl interface of the function "week_number" thus does NOT change.


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

A new function named "calendar" has been added to the "Date::DateCalcLib"
module which produces a calendar for a given month and year pretty much
like the UNIX "cal" command.

You can also copy this function into your own Perl code and then modify
it, for instance to make the day numbers clickable with hyperlinks when
the calendar is used in an HTML page.

A piece of C source code named "cal.c_" has been added to this package
which demonstrates how one can use the date calculation functions library
"lib_date.c" (the core of the "Date::DateCalc" module) *STAND-ALONE*.

(The trailing underscore has been added to the name of "cal.c_" in order
to prevent it from being automatically compiled and linked with the core
of the "Date::DateCalc" module when building this package.)

See at the end of the file "INSTALL" in this distribution for instructions
on how to compile and link this little demonstration utility.


Most important differences between versions 2.x and 3.0:
--------------------------------------------------------

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.


Most important differences between versions 1.x and 2.x:
--------------------------------------------------------

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, if you do need them.

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).

Since the table "day_name_tab" has been changed accordingly, you
probably won'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
call themselves).

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 to <sb@sdm.de>.)

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

From version 2.1 on:

The man page is no separate file anymore, it is now included in the
file "DateCalc.pm" in POD format, where it will automatically be found
and installed in your "man" directory by "make install".


Version history in details:
---------------------------

Version 1.0 was the initial release (released as an article in the news-
groups comp.lang.perl.misc and de.comp.lang.perl).

----------------------------------------------------------------------------

Version 1.01 tried to fix some "violations" of programming standards for
Perl extension modules I wasn't aware of. (Everything was very new to me!)

----------------------------------------------------------------------------

Version 1.1 supplied a much more elaborate set of test scripts which are
run and evaluated automatically by Test::Harness when "make test" is
issued, testing every single function in this package very thoroughly.

This version also tried to fix the problem with the redefinition of the
types "uint", "ulong" etc. that arose on some systems which define these
types themselves, by renaming them to "unint", "unlong" and so forth.

----------------------------------------------------------------------------

Version 1.2a was another attempt to solve the problem of the predefined
types by renaming them to some more unusual (and hence less probably
already defined) names. (See the file 'lib_defs.h' for details)

(Other developers beware: The type names "uint", "u_int" and "unint" (and
the like) are all taken! Do NOT use these names for your own types!)

It also "fixed" what I thought was a possible problem in the DateCalc.xs
file where the name of the stack pointer for argument and return value
passing seems to be "SP" and not "sp" (used in the EXTEND(sp,num) macro).

After carefully re-reading the PERLAPI manual, I found out that "SP" and
"sp" are "global" and "local" stack pointers, respectively. So the above
"fix" in version 1.2a is reversed in version 1.2b.

----------------------------------------------------------------------------

Since version 1.2a (where the "a" stands for "alpha", BTW) seemed to have
succeeded in fixing the system "typedef"s problem, I re-released it (with
only marginal corrections (like the one above, for example) and some small
refinements of the documentation) as version 1.2b ("b" for "beta").

----------------------------------------------------------------------------

From version 1.3 on, the C library "lib_date.c" is compiled separately; it is
no longer "#include"d in the XS file. Moreover, the function "days_in_month"
was added.

----------------------------------------------------------------------------

Version 1.4 fixed a bug in DateCalc.xs where the function newSVnv(double)
was used instead of newSViv(IV) although an integer value is passed to it.

----------------------------------------------------------------------------

Version 1.5 introduced a notice that you need a compiler capable of
processing ANSI C in order to successfully compile this module, and
contained a second demo for decoding dates in U.S. american format.

----------------------------------------------------------------------------

Version 1.6 was tested with Perl 5.002 for compatibility (positive)
and a third demo was added which shows how to calculate, for instance,
the 2nd Thursday of a given month and year. This version has never been
published on the Internet, however.

----------------------------------------------------------------------------

Version 2.0 offered new features, such as date/time calculations and a
few other new functions. The german man page was dropped because the
expense of maintaining two man pages is not bearable in the long run.
The functions "day_short_tab" and "month_short_tab" are gone, these
tables are not needed any longer internally. 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. Moreover, the values returned
by the function "day_of_week" have been shifted by one, they now go
from 1 to 7 (previously from 0 to 6), to make things more consistent
and to make the function "decode_day" work exactly as "decode_month"
(which was already present in former versions but was not exported).
The function and table "day_name_tab" has been changed accordingly.
The two functions "date_time_difference" and "calc_new_date_time"
are new, 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 extensions of the functions "dates_difference"
and "calc_new_date" (which they also use).

----------------------------------------------------------------------------

Version 2.1 fixed a minor bug in lib_date.c:
wrong:    if ((*ss <= 60) and (*mm <= 60) and (*hh <= 24) and
right:    if ((*ss < 60) and (*mm < 60) and (*hh < 24) and
among other minor adjustments in orthography and style, plus
adaptations to conform with new Perl 5.002 module standards.

----------------------------------------------------------------------------

Version 2.2 fixed a bug concerning arrays as parameters: enabling
prototypes in DateCalc.xs caused

    ($year,$mm,$dd) = first_in_week(week_number($year,$mm,$dd));

to generate Perl compilation errors, because "week_number" passes
an array to "first_in_week". To circumvent this, you had to pass
arrays explicitly, element by element:

    @w = week_number($year,$mm,$dd);
    ($year,$mm,$dd) = first_in_week( $w[0], $w[1] );

Since version 2.2, this workaround is obsolete.

----------------------------------------------------------------------------

Version 2.3 fixed a problem with unbalanced "malloc" and "free" calls
which was discovered only with Perl version 5.003: Calling "malloc" in
the C kernel of my module (compiled without the "perl.h" header file so
that you can also use it independently from Perl) and "free" in the XSUB
of my module (where the Perl "free" gets called!) produced a "bad free()
ignored" warning.

----------------------------------------------------------------------------

Version 3.0 adds a library of useful functions to solve special problems,
functions that have been kept in additional "demo" files until now.
Their (most important) contents (plus some new functions) have been moved
to the new "Date::DateCalcLib" module, which the demo programs now use.

Moreover, the convention for unsuccessful return has been changed: instead
of returning zeros in all return values, an empty list is returned. That
way it is possible to use the assignment to a list from a function call
as the condition in an "if" statement, which wasn't possible before.

----------------------------------------------------------------------------

Version 3.1 adds a "calendar" function (similar to the UNIX "cal" command)
to the "DateCalcLib" module as well as a piece of C source code to demons-
trate how to use the C library ("lib_date.c") in this package stand-alone.

----------------------------------------------------------------------------

In version 3.2, the piece of code in the file "DateCalc.xs" used to interpret
the week number returned by the C function "week_number()" has been moved to
the C library "lib_date.c", where it was used to create an additional function
named "week_of_year()". The XS function "week_number" now uses this new
function. The Perl function "week_number" thus stays exactly the same as
it was.

----------------------------------------------------------------------------

