=======================================
  Module "Date::DateCalc" Version 1.5
=======================================

--------------------------------------------------------------------------------
 Extension package for Perl 5.001m (should work with Perl 5.000 and up as well)
--------------------------------------------------------------------------------


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

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

Many users have craved for a simple module that uses the XS interface to
incorporate a C library, in order to be able to learn from it, since the
PERLAPI and PERLGUTS sections of the Perl 5 manual are not complete and
easy to put into practice. So here it is!

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

  $flag = leap($year);
  $date = encode($yy,$mm,$dd);
  ($cc,$yy,$mm,$dd) = decode($date);
  $flag = valid_date($date);
  $datestr = date_string($date);
  $flag = check_date($year,$mm,$dd);
  $days = calc_days($year,$mm,$dd);
  $days = dates_difference($year1,$mm1,$dd1,$year2,$mm2,$dd2);
  $weekday = day_of_week($year,$mm,$dd);
  ($year,$mm,$dd) = calc_new_date($year,$mm,$dd,$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);
  ($year,$mm,$dd) = decode_date($buffer);
  $day = day_short_tab($weekday);
  $day = day_name_tab($weekday);
  $month = month_short_tab($mm);
  $month = month_name_tab($mm);
  $days = days_in_month($year,$mm);
  $version = Date::DateCalc::Version();

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


How to install it:
------------------

Please unpack and build this package OUTSIDE the Perl source and distribution
tree!!

 1) Change directory to the directory that has been created by unpacking this
    package ("DateCalc-1.5").

 2) Type "perl5 Makefile.PL" (or whatever the name and path of your Perl 5
    binary is).

    This will create a "Makefile" with the appropriate parameters for your
    system (for instance, where the install directories are, and so on).

 3) Type "make".

    This will create a dynamically linkable library file that will be linked
    to Perl later, at runtime, provided your system supports dynamic linking.

    Please refer to the MakeMaker documentation for instructions on how
    to build a new Perl with statically linked libraries (invoke "perldoc
    ExtUtils::MakeMaker" for this), if your system DOESN'T support dynamic
    linking!

    (Note, however, that I didn't test this since my system does support
    dynamic linking.)

    Should you encounter any compiler warnings or errors (like the redefini-
    tion of certain types already defined by your system), please contact
    me by mail at 'sb@sdm.de', sending me your compiler output (both STDOUT
    and STDERR). Thank you!

    Should you get the error messages

    DateCalc.c: 15: Unable to find include file 'EXTERN.h'.
    DateCalc.c: 16: Unable to find include file 'perl.h'.
    DateCalc.c: 17: Unable to find include file 'XSUB.h'.

    then edit the file Makefile.PL and change the line

    'INC'	=> '',     # e.g., '-I/opt/pkg/perl5.001m/dist' 

    in such a way that it points to your Perl 5 distribution tree, e.g.,

    'INC'       => '-I/usr/ctr/dlt/private/perl/perl5.001m',

    or the like, and start over with the generation of the Makefile at 2).

 4) Now issue "make test".

    The output should look somewhat like this:

    /opt/bin/perl5 -I./blib -I./blib -I/opt/lib/perl5.001m/hpux
    -I/opt/lib/perl5.001m -e 'use Test::Harness qw(&runtests $verbose);
    $verbose=0; runtests @ARGV;' t/*.t
    t/f000..............ok
    t/f001..............ok
    t/f002..............ok
    t/f003..............ok
    t/f004..............ok
    t/f005..............ok
    t/f006..............ok
    t/f007..............ok
    t/f008..............ok
    t/f009..............ok
    t/f010..............ok
    t/f011..............ok
    t/f012..............ok
    t/f013..............ok
    t/f014..............ok
    t/f015..............ok
    t/f016..............ok
    t/f017..............ok
    t/f018..............ok
    t/f019..............ok
    All tests successful.
    Files=20,  Tests=165,  4 secs ( 2.37 cusr  1.06 csys =  3.43 cpu)

 5) Currently there are two versions of the man page "Date::DateCalc.3":
    "Date::DateCalc.3.deutsch" and "Date::DateCalc.3.english". Rename the
    one which is appropriate for you to "Date::DateCalc.3".

    After this, you will have to manually copy this man page to your man
    directory, probably one of "/usr/lang/man/cat3", "/usr/local/man/cat3",
    "/usr/man/cat3", or the like (consult your MANPATH environment variable).

    (The current version of MakeMaker doesn't yet support the copying of the
    man pages to their destination directory.)

    If, however, you have installed a newer version of Makemaker which
    supports installing of the man pages, you can skip this step as it's
    automatically taken care of by the "make install" in the next step.

    You may also first try "make install", and if it doesn't install the
    man page, copy it manually.

 6) Finally, type "make install".
        
 7) Now you may try to run the "demo". Start it with "perl5 demo" (or what-
    ever the name and path of your Perl 5 binary is).

    It will ask you for your birthday and the current date and calculate your
    age in days. You may enter the dates in almost any format, provided that
    you enter them in the order day - month - year. You may also use an (up
    to 3 letters) abbreviation for the month. You might try "03-Jan-1964",
    for example. Experiment!

    "demo_us" is (in principle) the same program as "demo", but it expects
    dates in U.S. american format in the order month - day - year. Moreover,
    the decoding is done entirely in Perl, whereas "demo" uses the package's
    C function "decode_date".

 8) Enjoy!


Version history:
----------------

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

Version 1.01 tried to fix some "violations" of programming standards for
Perl extension modules I wasn't aware of. (I'm rather new at all this!)

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) seems to have
succeeded in fixing the system "typedef"s problem, I am re-releasing 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 includes a notice that you need a compiler capable of
processing ANSI C in order to successfully compile this module, and
contains a second demo for decoding dates in U.S. american format.


Thanks:
-------

Many thanks to Andreas Koenig for his efforts as upload-manager for the
CPAN, his patience, and lots of very good advice and suggestions! Thank
you for doing such a tremendous (and very time-consuming) job!!

Also many thanks to David Jenkins for reviewing this README file and the
english man page.

Thanks to Jarkko Hietaniemi for suggesting the "days_in_month" function.

Many thanks to Christian <chrisi@vm.akh-wien.ac.at> for reporting the bug
fixed in version 1.4, which showed up on an HP E55 running HP-UX 10.01 and
Perl 5.001m with the c89 Ansi 89 compiler from HP.

Also many thanks to David Thompson <dlt@dewey.csun.edu> for reporting a
problem he encountered concerning the inclusion of the Perl distribution
("Unable to find include file ...") and for suggesting a solution for this
problem. (That's the most pleasant kind of problem report, of course! ;-) )


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

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

sb@sdm.de (Steffen Beyer)

With kind regards,
--
Steffen Beyer
mailto:sb@sdm.de        |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.
