forked from gitpan/Date-Pcalc
/
README.htm
141 lines (104 loc) · 7.69 KB
/
README.htm
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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<TITLE>Date::Pcalc Readme Page</TITLE>
</HEAD>
<BODY>
<P>
<HR NOSHADE SIZE="2">
<P>
<CENTER>
If you are looking for information on <A HREF="CHANGES.txt">what is new</A> in this version, prerequisites and <A HREF="INSTALL.txt">installation instructions</A>, you will find it either in the <A HREF="README.txt">README</A> file included in this distribution, <A HREF="http://www.engelschall.com/~sb/download/pkg/Date-Pcalc-6.1.README">on my website</A> or <A HREF="http://cpansearch.perl.org/src/STBEY/Date-Pcalc-6.1/README.txt">on CPAN</A>.
</CENTER>
<P>
<HR NOSHADE SIZE="2">
<P>
<H3>See</H3>
<A HREF="http://search.cpan.org/search?module=Date::Pcalc"><IMG SRC="http://www.engelschall.com/u/sb/download/Date-Calc/img/cpan_banner.png" ALT="[search.cpan.org]" BORDER="0"></A>
<H3>for the latest manual page.</H3>
<P>
<H1>Date::Pcalc</H1>
<A HREF="http://www.engelschall.com/u/sb/demo/"><IMG SRC="http://www.engelschall.com/u/sb/download/img/Date-Calc.gif" ALT="[Date::Pcalc]" WIDTH="455" HEIGHT="230" BORDER="0"></A>
<P>
<H3>What is it for?</H3>
Date calculations, e.g.
<UL>
<LI>"Basic stuff" like leap year, "Julian day" (or "date"), day-of-week, days in month/year, etc.
<LI>Comparing dates
<LI>Conversion from a date (e.g. 01-Jun-2004) to the number of days (e.g. 731733) and vice-versa
<LI>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)
<LI>Calculating the nth day-of-week of a month and year (e.g. the first Tuesday of July 2004 = 06-Jul-2004)
<LI>Calculating differences between dates (and/or times)
<LI>Calculating Easter Sunday and holidays depending on it
<LI>...
</UL>
based on
<UL>
<LI>the Gregorian calendar (decreed in 1582 by pope Gregor I)
<LI><A HREF="http://www.engelschall.com/u/sb/download/Date-Calc/DIN1355/">DIN 1355</A>
<LI><A HREF="http://www.iso.ch/iso/en/prods-services/popstds/datesandtime.html">ISO 8601</A> (to some extent, where applicable)
<BR>(See also <A HREF="http://www.w3.org/TR/NOTE-datetime">W3C</A>, <A HREF="http://www.mcs.vuw.ac.nz/technical/software/SGML/doc/iso8601/ISO8601.html">Victoria University of Wellington</A> or <A HREF="http://en.wikipedia.org/wiki/ISO_8601">Wikipedia</A>)
</UL>
<H3>Philosophy</H3>
<UL>
<LI>Toolbox, not a (heavy) ready-made application
<LI>Interoperable, "LEGO system"
<LI>Spirit of UNIX command-line tools (be small, do only one thing, and be good at it)
<LI>Be computationally complete, i.e., everything should be computable (even if it takes a little more than only one function call)
</UL>
<H3>What it is <B><U>NOT</U></B></H3>
<UL>
<LI>A jack-of-all-trades (see e.g. <A HREF="http://search.cpan.org/search?module=Date::Manip">Date::Manip</A> instead)
<LI>A module specializing in date parsing (see e.g. <A HREF="http://search.cpan.org/search?module=Date::Parse">Date::Parse</A>, <A HREF="http://search.cpan.org/search?module=Time::ParseDate">Time::ParseDate</A> or <A HREF="http://search.cpan.org/search?module=Date::Manip">Date::Manip</A> instead)
<LI>A module specializing in date formatting (see e.g. <A HREF="http://search.cpan.org/search?module=Date::Format">Date::Format</A> or <A HREF="http://search.cpan.org/search?module=Date::Manip">Date::Manip</A> instead)
<LI>A module specializing in the handling of timezones (see e.g. <A HREF="http://search.cpan.org/search?module=Time::Timezone">Time::Timezone</A> or <A HREF="http://search.cpan.org/search?module=Time::Zone">Time::Zone</A> instead)
</UL>
<H3>What it <B><U>IS</U></B></H3>
<UL>
<LI>A module <B><U>primarily</U></B> for performing <B><U>calculations</U></B> with dates (nomen est omen)
<LI>A module intended to be <B><U>small</B></U> (low memory footprint) and <B><U>fast</B></U> (for heavy-duty applications)
</UL>
<P>
<H3>Features</H3>
<UL>
<LI>Extrapolates the Gregorian calendar back beyond 1582 until 1 A.D.
<BR>(historically <B><U>not</B></U> meaningful, but may nevertheless be useful)
<LI>Numerical range extends as far as "int" data type permits, i.e., at least until the year 32767
<LI>Basic date parsing (input) and formatting (output)
<LI>Support for various languages (input and output)
<BR>(Currently 14 as of version 6.1; English, French, German, Spanish, Portuguese, Dutch, Italian, Norwegian, Swedish, Danish, Finnish, Hungarian, Polish and Romanian)
<LI>Calculations on dates, with and without time (including timezone offsets)
<LI>Interface to localtime(), gmtime(), mktime() plus own conversion routines (with more predictable results)
<LI><B>Internally written in C for smaller memory usage, faster execution and possibility to use in C applications</B>
<LI>The <A HREF="http://search.cpan.org/search?module=Date::Pcalc">documentation</A> of "Date::Pcalc" gives model solutions to common problems in its "<A HREF="http://search.cpan.org/~stbey/Date-Pcalc-6.1/Pcalc.pod#RECIPES">RECIPES</A>" section
<LI>Optionally provides date objects (i.e., an OO interface) for greater ease of use (Perl only) (<A HREF="http://search.cpan.org/search?module=Date::Pcalc::Object">Date::Pcalc::Object</A>)
<LI>Comprises a module for date calculations taking legal holidays into account (Perl only) (<A HREF="http://search.cpan.org/search?module=Date::Pcalendar">Date::Pcalendar</A>)
<LI>Provides a rich set of holiday profiles for numerous countries (Perl only) (<A HREF="http://search.cpan.org/search?module=Date::Pcalendar::Profiles">Date::Pcalendar::Profiles</A>)
</UL>
<H3>Limitations</H3>
<UL>
<LI>The language setting in "Date::Pcalc" is a global variable (= BEWARE when using threads!)
<LI>The modules "Date::Pcalendar" and "Date::Pcalendar::Year" only operate on years between 1583 and 2299
<LI>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)
<LI><FONT COLOR="#FF0000"><B>The calendar profiles included in this module usually do not take historical irregularities into account</B></FONT> (even though some do in order to show how this can be done),<BR>
<FONT COLOR="#FF0000"><B>they only provide means for calculating <U>regularly</U> recurring events (<U>the profiles should therefore not be relied upon for historical faithfulness</U>)</B></FONT>
</UL>
<P>
<H3>See also</H3>
<UL>
<LI>The <A HREF="http://www.engelschall.com/u/sb/calendar/">International Eternal Gregorian Calendar</A> showing a calendar with holidays in selectable languages and countries
<LI>The <A HREF="http://www.engelschall.com/u/sb/demo/">Sports Club Events Calendar</A> showing how this module can be used to manage people attending events in a calendar
<LI>The <A HREF="http://www.engelschall.com/u/sb/datecalc/">Simple Date Calculator</A> for determining the difference between two dates / a new date based on a date plus a difference
<LI>"<A HREF="http://www.tondering.dk/claus/calendar.html">The Calendar FAQ</A>" by <A HREF="mailto:claus@tondering.dk">Claus Tøndering</A>
</UL>
<P>
<HR NOSHADE SIZE="2">
<P>
<CENTER>
If you are looking for information on <A HREF="CHANGES.txt">what is new</A> in this version, prerequisites and <A HREF="INSTALL.txt">installation instructions</A>, you will find it either in the <A HREF="README.txt">README</A> file included in this distribution, <A HREF="http://www.engelschall.com/~sb/download/pkg/Date-Pcalc-6.1.README">on my website</A> or <A HREF="http://cpansearch.perl.org/src/STBEY/Date-Pcalc-6.1/README.txt">on CPAN</A>.
</CENTER>
<P>
<HR NOSHADE SIZE="2">
<P>
</BODY>
</HTML>