Subject: ANNOUNCE: Date::DateCalc 1.3 and Set::IntegerFast 1.0
From: [email-masked] (Steffen Beyer)
Date: 14 Dec 1995 18:26:47 GMT
Newsgroups: comp.lang.perl.announce,comp.lang.perl.misc

The module "Date::DateCalc" has been further refined and is now available
as version 1.3 at the usual ftp sites (see below for more details).

=======================================
  Module "Date::DateCalc" Version 1.3
=======================================

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();

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").

Version 1.3 now compiles the C library "lib_date.c" separately; it is no
longer '#include'd in the XS file. Moreover, the function "days_in_month"
has been added.

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.

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

At the usual ftp sites for Perl (CPAN = Comprehensive Perl Archive Network),

under     .../CPAN/authors/id/STBEY/

or        .../CPAN/modules/by-category/06_Data_Type_Utilities/Date/

or        .../CPAN/modules/by-module/Date/

(See "The Perl 5 Module List" by Tim Bunce in news:comp.lang.perl.announce
for a list of CPAN ftp servers)

=========================================
  Module "Set::IntegerFast" Version 1.0
=========================================

What does it do:
----------------

This package lets you dynamically create sets of arbitrary (but fixed) size
(only limited by the size of a machine word and available memory on your system)
of (positive) integers and to perform all the basic operations for sets on them,
like adding or removing elements, testing for the presence of a certain element,
computing the union, intersection, difference or complement of sets, copying
sets, testing two sets for equality or inclusion, and computing the minimum,
the maximum and the norm (number of elements) of a set.

The package is mainly intended for mathematical or algorithmical computations.
There are a number of efficient algorithms that rely on sets, like, for exam-
ple, Kruskal's algorithm for minimal spanning trees in graphs (which uses a
different representation of sets (trees stored in an array), however, than
the one used by this package (bit vectors), which is included here for those
interested as a Perl program), or the "Seave of Erathostenes" for calculating
prime numbers, which is included here as a demo program.

Another important field of application is the computation of "first", "follow"
and "look-ahead" character sets for the construction of LL, SLR, LR and LALR
parsers for compilers (or a compiler-compiler, like "yacc").

(This is what the C code in this package was initially written for)

(See Aho, Hopcroft, Ullman, "The Design and Analysis of Computer Algorithms"
for an excellent book on efficient algorithms and the famous "Dragon Book" on
how to build compilers by Aho, Sethi, Ullman)

The package is designed for efficiency, not comfort. Therefore, it only
offers a basic functionality and leaves it up to your application to add
whatever special handling it needs (for example, negative indices can
be realized by "shifting" the whole range with an offset).

If you want a package for sets that offers more comfort for not so time-
critical tasks, consider using the module "Set::Scalar" written by Jarkko
Hietaniemi <[email-masked]>, which allows you to use all kinds of
Perl scalars as elements and offers an abundant range of methods to handle
these sets.

Sets in this package are implemented as bit vectors, and elements are positive
integers from zero to the maximum number of elements (which you specify when
creating the set) minus one.

Each element (i.e., number or "index") thus corresponds to one bit in the
bit array. Bit number 0 of word number 0 corresponds to element number 0,
element number 1 corresponds to bit number 1 of word number 0, and so on.

The package doesn't use bytes as basic storage unit, it rather uses machine
words, assuming that a machine word is the most efficiently handled size of
all scalar types on any system.

In order to achieve this, it automatically determines the number of bits
in a machine word on your system and then sets its internal basic constants
accordingly.

The greater the size of this basic storage unit, the better the complexity
of the routines in this package (but also the greater the average waste of
unused bits in the last word).

See the Set::IntegerFast(3) man page for a detailed analysis of the com-
plexity of each method!

Here a brief description of all the available methods:

     Version       returns a version string
     Create        the set object constructor
     Destroy       free() the memory occupied by a set
     Empty         delete all elements in the set
     Fill          insert all possible elements into the set
     Insert        insert a given element
     Delete        delete a given element
     in            test the presence of a given element
     Union         calculate the union of two sets   (in-place is possible)
     Intersection  calculate the intersection of two sets            (idem)
     Difference    calculate the difference of two sets ("A\B")      (idem)
     Complement    calculate the complement of a set (in-place is possible)
     equal         test two sets for equality relation
     inclusion     test two sets for inclusion relation
     lexorder      test two sets for lexical order relation
     Compare       compare two sets - yields -1, 0 or 1 for <, = or >
     Norm          calculate the norm (number of elements) of the set
     Min           return the minimum of the set ( min{} = +infinity )
     Max           return the maximum of the set ( max{} = -infinity )
     Copy          copy one set to another

For more details, see the Set::IntegerFast(3) man page!

Thanks:
-------

Many thanks to Jarkko Hietaniemi for his suggestions while I was developing
this package!

Many thanks also to the people of the perl5-porters <[email-masked]>
mailing list, specifically:

Andreas Koenig <[email-masked]>
Tim Bunce <[email-masked]>
Jarkko Hietaniemi <[email-masked]>
Felix Gallo <[email-masked]>
Mark A Biggar <[email-masked]>
Nick Ing-Simmons <[email-masked]>
John Macdonald <[email-masked]>

for discussing and clarifying the naming and other issues of this package!

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

At the usual ftp sites for Perl (CPAN = Comprehensive Perl Archive Network),

under     .../CPAN/authors/id/STBEY/

or        .../CPAN/modules/by-category/06_Data_Type_Utilities/Set/

or        .../CPAN/modules/by-module/Set/

(See "The Perl 5 Module List" by Tim Bunce in news:comp.lang.perl.announce
for a list of CPAN ftp servers)

Have fun!

Best regards,
--
Steffen Beyer
mailto:[email-masked]        |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.