Date::Pcalc Readme Page

If you are looking for information on what is new in this version, prerequisites and installation instructions, you will find it either in the README file included in this distribution, on my website or on CPAN.

### See

### for the latest manual page.

# Date::Pcalc

### What is it for?

Date calculations, e.g.

- "Basic stuff" like leap year, "Julian day" (or "date"), day-of-week, days in month/year, etc.
- Comparing dates
- Conversion from a date (e.g. 01-Jun-2004) to the number of days (e.g. 731733) and vice-versa
- Calculating a date (e.g. 01-Jun-2004) plus/minus a number of days (e.g. +35) yielding a new date (e.g. 06-Jul-2004)
- Calculating the nth day-of-week of a month and year (e.g. the first Tuesday of July 2004 = 06-Jul-2004)
- Calculating differences between dates (and/or times)
- Calculating Easter Sunday and holidays depending on it
- ...

based on

- the Gregorian calendar (decreed in 1582 by pope Gregor I)
- DIN 1355
- ISO 8601 (to some extent, where applicable)
  (See also W3C, Victoria University of Wellington or Wikipedia)

### Philosophy

- Toolbox, not a (heavy) ready-made application
- Interoperable, "LEGO system"
- Spirit of UNIX command-line tools (be small, do only one thing, and be good at it)
- Be computationally complete, i.e., everything should be computable (even if it takes a little more than only one function call)

### What it is NOT

- A jack-of-all-trades (see e.g. Date::Manip instead)
- A module specializing in date parsing (see e.g. Date::Parse, Time::ParseDate or Date::Manip instead)
- A module specializing in date formatting (see e.g. Date::Format or Date::Manip instead)
- A module specializing in the handling of timezones (see e.g. Time::Timezone or Time::Zone instead)

### What it IS

- A module primarily for performing calculations with dates (nomen est omen)
- A module intended to be small (low memory footprint) and fast (for heavy-duty applications)

### Features

- Extrapolates the Gregorian calendar back beyond 1582 until 1 A.D.
  (historically not meaningful, but may nevertheless be useful)
- Numerical range extends as far as "int" data type permits, i.e., at least until the year 32767
- Basic date parsing (input) and formatting (output)
- Support for various languages (input and output)
  (Currently 14 as of version 6.1; English, French, German, Spanish, Portuguese, Dutch, Italian, Norwegian, Swedish, Danish, Finnish, Hungarian, Polish and Romanian)
- Calculations on dates, with and without time (including timezone offsets)
- Interface to localtime(), gmtime(), mktime() plus own conversion routines (with more predictable results)
- Internally written in C for smaller memory usage, faster execution and possibility to use in C applications
- The documentation of "Date::Pcalc" gives model solutions to common problems in its "RECIPES" section
- Optionally provides date objects (i.e., an OO interface) for greater ease of use (Perl only) (Date::Pcalc::Object)
- Comprises a module for date calculations taking legal holidays into account (Perl only) (Date::Pcalendar)
- Provides a rich set of holiday profiles for numerous countries (Perl only) (Date::Pcalendar::Profiles)

### Limitations

- The language setting in "Date::Pcalc" is a global variable (= BEWARE when using threads!)
- The modules "Date::Pcalendar" and "Date::Pcalendar::Year" only operate on years between 1583 and 2299
- Uses the ISO-Latin-1 character set, even for languages (such as Polish) not entirely representable in that character set (uses the "plain" characters instead in such cases)
- The calendar profiles included in this module usually do not take historical irregularities into account (even though some do in order to show how this can be done),
  they only provide means for calculating regularly recurring events (the profiles should therefore not be relied upon for historical faithfulness)

### See also

- The International Eternal Gregorian Calendar showing a calendar with holidays in selectable languages and countries
- The Sports Club Events Calendar showing how this module can be used to manage people attending events in a calendar
- The Simple Date Calculator for determining the difference between two dates / a new date based on a date plus a difference
- "The Calendar FAQ" by Claus Tøndering

If you are looking for information on what is new in this version, prerequisites and installation instructions, you will find it either in the README file included in this distribution, on my website or on CPAN.