                   ========================================
                     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:
----------------------

   -   Where to find
   -   Legal stuff (-> LICENSE, ARTISTIC, COPYING)
   -   Prerequisites
   -   Installation (-> INSTALL)
   -   Changes over previous versions (-> CHANGES)
   -   This distribution contains
   -   What does it do
   -   Credits (-> CREDITS)
   -   Author's note


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

At any CPAN ftp site (CPAN = "Comprehensive Perl Archive Network"),
the file "DateCalc-3.2.tar.gz" can be found in any of the following
directories:

    .../CPAN/authors/id/STBEY/
    .../CPAN/modules/by-category/06_Data_Type_Utilities/Date/
    .../CPAN/modules/by-module/Date/

To find a CPAN ftp site, you can either direct your web browser to

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

(which will automatically redirect you to a CPAN ftp server near you) or
look into "The Perl 5 Module List" by Tim Bunce and Andreas Koenig either
on USENET in the "comp.lang.perl.modules" newsgroup or at

    http://www.perl.com/CPAN/modules/00modlist.long.html

You can also download this module directly from the author's web site,
where you will also find my other modules and a couple of logos illustrating
what the modules do:

    http://www.engelschall.com/u/sb/download/


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

Please see the file "LICENSE" in this distribution (and the associated files
"ARTISTIC" and "COPYING") for details about the exact terms under which this
package may be used and distributed.


Prerequisites:
--------------

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

Installation:
-------------

Please see the file "INSTALL" in this distribution for instructions on how
to install this package.


Changes over previous versions:
-------------------------------

Please refer to the file "CHANGES" in this distribution for a list of new
features in this new version and for change history records.


This distribution contains:
---------------------------

   *   a "lib_date" C library (can be used stand-alone!)

       (files "lib_defs.h", "lib_date.h" and "lib_date.c")

          +   efficient (fast) and complete date calculations
              based on the gregorian calendar and the ISO/R
              2015-1971 and DIN 1355 standard

   *   a "Date::DateCalc" module

       (files "lib_defs.h", "lib_date.h", "lib_date.c",
        "DateCalc.xs" and "DateCalc.pm")

          +   a toolbox for any date calculation problem you
              will ever encounter

   *   a "Date::DateCalcLib" library module

       (file "DateCalcLib.pm")

          +   a library of useful date calculation applications

   *   demonstration programs

       (files "cal.c_", "demo", "demo2" and "demo_us")

          +   to help you write your own


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 clever 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:
--------

Please refer to the file "CREDITS" in this distribution for a list of
contributors.


Author's 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 some e-mail:

sb@sdm.de (Steffen Beyer)

In fact I'd be glad if you could drop me a note if you are using this
package, so I can see how much interest exists in it and in which direction
it should be developed further.

Please tell me what you liked and what you disliked about this package!

Also, I would be very interested to know what your application is in
which you found this package to be useful! (Just in order to get an idea)

Many thanks in advance!

Share and enjoy!

Yours,
--
    Steffen Beyer <sb@sdm.de> http://www.engelschall.com/u/sb/
     "There is enough for the need of everyone in this world,
      but not for the greed of everyone." - Mahatma Gandhi
