======================================== 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://sb.fluomedia.org/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@fluomedia.org (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 http://sb.fluomedia.org/ "There is enough for the need of everyone in this world, but not for the greed of everyone." - Mahatma Gandhi