======================================= Module "Date::DateCalc" Version 1.4 ======================================= -------------------------------------------------------------------------------- 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. 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.4"). 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@fluomedia.org', 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! 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 fixes a bug in DateCalc.xs where the function newSVnv(double) was used instead of newSViv(IV) although an integer value is passed to it. 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 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 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@fluomedia.org (Steffen Beyer) With kind regards, -- Steffen Beyer mailto:sb@fluomedia.org