Subject: ANNOUNCE: Date::DateCalc 3.1
From: [email-masked] (Steffen Beyer)
Date: 15 Jun 1997 16:06:52 GMT
Newsgroups: comp.lang.perl.announce,comp.lang.perl.modules

I am glad and proud to submit

                   ========================================
                     Package "Date::DateCalc" Version 3.1
                   ========================================
                       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.

to the Perl community.

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

  +  Where to find
  +  Prerequisites
  +  What's new in version 3.1
  +  This distribution contains
  +  What does it do

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

You can 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/

You should also be able to find this module on any CPAN ftp site (CPAN =
"Comprehensive Perl Archive Network"), where the file "DateCalc-3.1.tar.gz"
should 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.1.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

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

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

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

This piece of code is the C version of the new "calendar" function.

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

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!

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

I hope you will find this module benefitful!

Yours,
--
    Steffen Beyer <[email-masked]> 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
   >> Unsolicited commercial email goes directly to /dev/null <<