                     ====================================
                       Package "Date::Calc" Version 4.2
                     ====================================


            Copyright (c) 1995, 1996, 1997, 1998 by Steffen Beyer.
                             All rights reserved.


Example applications:
---------------------

You will find some example applications (several in Perl, one in C)
in the "examples" subdirectory of this distribution:

                        examples/age_in_days_eu.pl
                        examples/age_in_days_us.pl
                        examples/cal.c
                        examples/nth_weekday.pl


age_in_days_eu.pl, age_in_days_us.pl:
-------------------------------------

"age_in_days_eu.pl" and "age_in_days_us.pl" are a demonstration of the
multi-language capabilities of this package, as well as of its scanning
capabilities for dates.

First build and install this package (for instructions, see the file
"INSTALL.txt" in this distribution), then change directory to the
"examples" subdirectory, and finally start these two demo programs
with
                        > perl age_in_days_eu.pl
and
                        > perl age_in_days_us.pl
respectively.

They first ask you to choose a language; any uniquely identifying
abbreviation for one of the six languages initially provided by this
package (English, French, German, Spanish, Portuguese, Dutch) will
suffice, like "en" for "English", "es" for "Español" (Spanish),
"f" for "Français" (French), and so on.

These applications then ask you to enter the date of your birthday.

The two applications only differ in the expected format for dates:
In "age_in_days_eu.pl", the order day-month-year is assumed, whereas
"age_in_days_us.pl" assumes the order month-day-year.

For the month you can (at your option) either enter the corresponding
number, or any uniquely identifying abbreviation of the month's name
(or the name of the month in full length) IN THE CHOSEN LANGUAGE.

Moreover, virtually any format for dates is supported:

Examples include "03/01/64", "3.1.1964", "January 3rd, 1964", "030164",
and so on.

Experiment!

Note that the scanning itself is actually performed by two powerful
routines written in C, and not using the regular expressions from Perl
(which would make this task rather trivial in Perl, but which wouldn't
be easily accessible to C programmers).

After confirming your entry, the program will print out your age in days.

If the system call "time()" (and hence, "localtime()") is not available
on your system, the program will also ask you to enter today's date.

Otherwise the program will automatically use the system-supplied current
date.


cal.c:
------

This little program is a substitute for the UNIX "cal" command.

In contrast to the UNIX "cal" command, however, this program allows you
to choose a language which will be used for generating the calendar for
the chosen month and year.

(Also in contrast to the UNIX "cal" command, this program will NOT
generate a tiled overview of ALL the months for a given year, however.)

Moreover, you can (at your option) either enter the number of the desired
language, or any uniquely identifying abbreviation of its name (or the name
in full length).

For the month you can also (at your option) either enter the corresponding
number, or any uniquely identifying abbreviation of the month's name (or
the name of the month in full length) *IN THE CHOSEN LANGUAGE*.

In order to compile this little program, first copy the file "cal.c" from
the "examples" subdirectory to the main directory of this distribution.

BEWARE that you should REMOVE this file ("cal.c") from the MAIN directory
of this distribution BEFORE building this package (i.e., before issuing
the command "perl Makefile.PL"), because you may get compiler or runtime
errors (like "duplicate main() function") otherwise. At the very least,
this will inflate your shared library ("Calc.so") unnecessarily if you
don't.

In order to successfully compile the "cal.c" program, you do NOT need
to build this package first, however.

Then change directory to the main directory of this distribution,
if you haven't done so already.

Finally, if you have Perl available on your system (no matter wether
UNIX or Win32), you can compile this program with the following command:

            > perl tools/compile.pl cal.c DateCalc.c
or
            > perl tools\compile.pl cal.c DateCalc.c

Otherwise, if you have the GNU C compiler ("gcc") available on your system,
you can also do so (UNIX only) using the command

            > ./tools/compile.sh cal.c DateCalc.c

On a MSDOS/Windows system, if your ANSI C compiler can be called with "cl",
you can also compile the program using the command

            > tools\compile cal DateCalc.c

(Note the missing ".c" at the end of the filename "cal" in this case!)

Otherwise, compile the program with your favourite ANSI C compiler in a
similar fashion.

Now start the program with the command "./cal" (UNIX) or simply "cal"
(MSDOS/Windows).

(Note that this program is not confined to Win32 systems, it also compiles
and runs perfectly well on pure MS-DOS or other Windows systems!)

The first parameter is the desired language (currently 1..6 or "English",
"Français", "Deutsch", "Español", "Português" and "Nederlands"),
the second the month and the third the year.

Example:
                        > cal en apr 1998

This will print:

                            April 1998
                    Mon Tue Wed Thu Fri Sat Sun
                              1   2   3   4   5
                      6   7   8   9  10  11  12
                     13  14  15  16  17  18  19
                     20  21  22  23  24  25  26
                     27  28  29  30

If you start the "cal" program without parameters, it will print a usage
and exit.

Experiment!

If you like this program, you might want to copy it to some directory in
your search path, like "/usr/local/bin" (UNIX) or "C:\DOS" (MSDOS/Windows).

If you are running this program on a PC (e.g. MS-DOS, Windows DOS box,
GNU/Linux or FreeBSD console), you might want to pipe its output through
the "iso2pc" filter from the "tools" subdirectory (see the file "TOOLS.txt"
in this distribution for instructions on how to compile and install this
filter), in order to convert the special international characters from
the ISO-Latin-1 character set (used throughout this package) to one of
the (two) character sets commonly used on PC's, as follows:

                    > cal Portug Mar 1998 | iso2pc [-dos]

(for older versions of MS-DOS and the PC-UNIX console) or

                    > cal Portug Mar 1998 | iso2pc -win

(for newer versions of MS-DOS and the Win32 DOS box).


nth_weekday.pl:
---------------

This program is a demonstration of the function "Nth_Weekday_of_Month_Year()"
and the scanning capabilities of this package (in particular the day of week
and month, in this case).

It calculates the date of the "n"th occurrence of the given day of week
in the chosen month and year -- such as, for example, the 3rd Thursday
of a given month and year.

First build and install this package (for instructions, see the file
"INSTALL.txt" in this distribution), then change directory to the
"examples" subdirectory, and finally start this program with the
following command (example):

            > perl nth_weekday.pl 3rd Thursday April 1998

This will print:

        The 3rd Thursday in April 1998 is Thursday, April 16th 1998.

If you start this program without parameters, it will print a usage
and exit.

Note that you can enter the factor ("3rd" in the above example) either
using plain numeric digits ("1", "2", "3", "4" and "5"), or in the usual
abbreviated (English) form as "1st", "2nd", "3rd", "4th" and "5th".

You can also enter the day of week either numerically ("1" through "7"),
or as any uniquely identifying abbreviation of the name of the desired
day of week (or its name in full length) in English.

For the month you can similarly either enter the corresponding number
("1" through "12"), or any uniquely identifying abbreviation of the
month's name (or the name of the month in full length) in English.

Experiment!


