Debian Codegraph @

README

raw
1 NAME
2
3 Date::ISO8601 - the three ISO 8601 numerical calendars
4
5 DESCRIPTION
6
7 The international standard ISO 8601 "Data elements and interchange formats
8 - Information interchange - Representation of dates and times" defines
9 three distinct calendars by which days can be labelled. It also defines
10 textual formats for the representation of dates in these calendars.
11 This module provides functions to convert dates between these three
12 calendars and Chronological Julian Day Numbers, which is a suitable
13 format to do arithmetic with. It also supplies functions that describe
14 the shape of these calendars, to assist in calendrical calculations.
15 It also supplies functions to represent dates textually in the ISO
16 8601 formats. ISO 8601 also covers time of day and time periods, but
17 this module does nothing relating to those parts of the standard; this
18 is only about labelling days.
19
20 The first ISO 8601 calendar divides time up into years, months, and days.
21 It corresponds exactly to the Gregorian calendar, invented by Aloysius
22 Lilius and promulgated by Pope Gregory XIII in the late sixteenth century,
23 with AD (CE) year numbering. This calendar is applied to all time,
24 not just to dates after its invention nor just to years 1 and later.
25 Thus for ancient dates it is the proleptic Gregorian calendar with
26 astronomical year numbering.
27
28 The second ISO 8601 calendar divides time up into the same years as
29 the first, but divides the year directly into days, with no months.
30 The standard calls this "ordinal dates". Ordinal dates are commonly
31 referred to as "Julian dates", a mistake apparently deriving from true
32 Julian Day Numbers, which divide time up solely into linearly counted
33 days.
34
35 The third ISO 8601 calendar divides time up into years, weeks, and days.
36 The years approximate the years of the first two calendars, so they stay
37 in step in the long term, but the boundaries differ. This week-based
38 calendar is sometimes called "the ISO calendar", apparently in the belief
39 that ISO 8601 does not define any other. It is also referred to as
40 "business dates", because it is most used by certain businesses to whom
41 the week is the most important temporal cycle.
42
43 The Chronological Julian Day Number is an integral number labelling each
44 day, where the day extends from midnight to midnight in whatever time zone
45 is of interest. It is a linear count of days, where each day's number
46 is one greater than the previous day's number. It is directly related to
47 the Julian Date system: in the time zone of the prime meridian, the CJDN
48 equals the JD at noon. By way of epoch, the day on which the Convention
49 of the Metre was signed, which ISO 8601 defines to be 1875-05-20 (and
50 1875-140 and 1875-W20-4), is CJDN 2406029.
51
52 This module places no limit on the range of dates to which it may be
53 applied. All function arguments are permitted to be "Math::BigInt" or
54 "Math::BigRat" objects in order to achieve arbitrary range. Native Perl
55 integers are also permitted, as a convenience when the range of dates
56 being handled is known to be sufficiently small.
57
58 INSTALLATION
59
60 perl Build.PL
61 ./Build
62 ./Build test
63 ./Build install
64
65 AUTHOR
66
67 Andrew Main (Zefram) <[email protected]>
68
69 COPYRIGHT
70
71 Copyright (C) 2006, 2007, 2009, 2011, 2017
72 Andrew Main (Zefram) <[email protected]>
73
74 LICENSE
75
76 This module is free software; you can redistribute it and/or modify it
77 under the same terms as Perl itself.