1Date::ISO8601(3) User Contributed Perl Documentation Date::ISO8601(3)
2
6 Date::ISO8601 - the three ISO 8601 numerical calendars
7
9 use Date::ISO8601 qw(present_y);
10 print present_y($y);
12 use Date::ISO8601
14 qw(month_days cjdn_to_ymd ymd_to_cjdn present_ymd);
15 $md = month_days(2000, 2);
17 ($y, $m, $d) = cjdn_to_ymd(2406029);
18 $cjdn = ymd_to_cjdn(1875, 5, 20);
19 print present_ymd(2406029);
20 print present_ymd(1875, 5, 20);
21 use Date::ISO8601
23 qw(year_days cjdn_to_yd yd_to_cjdn present_yd);
24 $yd = year_days(2000);
26 ($y, $d) = cjdn_to_yd(2406029);
27 $cjdn = yd_to_cjdn(1875, 140);
28 print present_yd(2406029);
29 print present_yd(1875, 140);
30 use Date::ISO8601
32 qw(year_weeks cjdn_to_ywd ywd_to_cjdn present_ywd);
33 $yw = year_weeks(2000);
35 ($y, $w, $d) = cjdn_to_ywd(2406029);
36 $cjdn = ywd_to_cjdn(1875, 20, 4);
37 print present_ywd(2406029);
38 print present_ywd(1875, 20, 4);
39
41 The international standard ISO 8601 "Data elements and interchange
42 formats - Information interchange - Representation of dates and times"
43 defines three distinct calendars by which days can be labelled. It
44 also defines textual formats for the representation of dates in these
45 calendars. This module provides functions to convert dates between
46 these three calendars and Chronological Julian Day Numbers, which is a
47 suitable format to do arithmetic with. It also supplies functions that
48 describe the shape of these calendars, to assist in calendrical
49 calculations. It also supplies functions to represent dates textually
50 in the ISO 8601 formats. ISO 8601 also covers time of day and time
51 periods, but this module does nothing relating to those parts of the
52 standard; this is only about labelling days.
53 The first ISO 8601 calendar divides time up into years, months, and
55 days. It corresponds exactly to the Gregorian calendar, invented by
56 Aloysius Lilius and promulgated by Pope Gregory XIII in the late
57 sixteenth century, with AD (CE) year numbering. This calendar is
58 applied to all time, not just to dates after its invention nor just to
59 years 1 and later. Thus for ancient dates it is the proleptic
60 Gregorian calendar with astronomical year numbering.
61 The second ISO 8601 calendar divides time up into the same years as the
63 first, but divides the year directly into days, with no months. The
64 standard calls this "ordinal dates". Ordinal dates are commonly
65 referred to as "Julian dates", a mistake apparently deriving from true
66 Julian Day Numbers, which divide time up solely into linearly counted
67 days.
68 The third ISO 8601 calendar divides time up into years, weeks, and
70 days. The years approximate the years of the first two calendars, so
71 they stay in step in the long term, but the boundaries differ. This
72 week-based calendar is sometimes called "the ISO calendar", apparently
73 in the belief that ISO 8601 does not define any other. It is also
74 referred to as "business dates", because it is most used by certain
75 businesses to whom the week is the most important temporal cycle.
76 The Chronological Julian Day Number is an integral number labelling
78 each day, where the day extends from midnight to midnight in whatever
79 time zone is of interest. It is a linear count of days, where each
80 day's number is one greater than the previous day's number. It is
81 directly related to the Julian Date system: in the time zone of the
82 prime meridian, the CJDN equals the JD at noon. By way of epoch, the
83 day on which the Convention of the Metre was signed, which ISO 8601
84 defines to be 1875-05-20 (and 1875-140 and 1875-W20-4), is CJDN
85 2406029.
86 This module places no limit on the range of dates to which it may be
88 applied. All function arguments are permitted to be "Math::BigInt" or
89 "Math::BigRat" objects in order to achieve arbitrary range. Native
90 Perl integers are also permitted, as a convenience when the range of
91 dates being handled is known to be sufficiently small.
92
94 Numbers in this API may be native Perl integers, "Math::BigInt"
95 objects, or integer-valued "Math::BigRat" objects. All three types are
96 acceptable for all parameters, in any combination. In all conversion
97 functions, the most-significant part of the result (which is the only
98 part with unlimited range) is of the same type as the most-significant
99 part of the input. Less-significant parts of results (which have a
100 small range) are consistently native Perl integers.
101 All functions "die" if given invalid parameters.
103 Years
105 present_y(YEAR)
106 Puts the given year number into ISO 8601 textual presentation
107 format. For years [0, 9999] this is simply four digits. For years
108 outside that range it is a sign followed by at least four digits.
109 This is the minimum-length presentation format. If it is desired
111 to use a form that is longer than necessary, such as to use at
112 least five digits for all year numbers (as the Long Now Foundation
113 does), then the right tool is "sprintf" (see "sprintf" in
114 perlfunc).
115 This format is unconditionally conformant to all versions of ISO
117 8601 for years [1583, 9999]. For years [0, 1582], preceding the
118 historical introduction of the Gregorian calendar, it is conformant
119 only where it is mutually agreed that such dates (represented in
120 the proleptic Gregorian calendar) are acceptable. For years
121 outside the range [0, 9999], where the expanded format must be
122 used, the result is only conformant to ISO 8601:2004 (earlier
123 versions lacked these formats), and only where it is mutually
124 agreed to use this format.
125 Gregorian calendar
127 Each year is divided into twelve months, numbered [1, 12]; month number
128 1 is January. Each month is divided into days, numbered sequentially
129 from 1. The month lengths are irregular. The year numbers have
130 unlimited range.
131 month_days(YEAR, MONTH)
133 The parameters identify a month, and the function returns the
134 number of days in that month as a native Perl integer.
135 cjdn_to_ymd(CJDN)
137 This function takes a Chronological Julian Day Number and returns a
138 list of a year, month, and day.
139 ymd_to_cjdn(YEAR, MONTH, DAY)
141 This performs the reverse of the translation that "cjdn_to_ymd"
142 does. It takes year, month, and day numbers, and returns the
143 corresponding CJDN.
144 present_ymd(CJDN)
146 present_ymd(YEAR, MONTH, DAY)
147 Puts the given date into ISO 8601 Gregorian textual presentation
148 format. The `extended' format (with "-" separators) is used. The
149 conformance notes for "present_y" apply to this function also.
150 If the date is given as a (YEAR, MONTH, DAY) triplet then these are
152 not checked for consistency. The MONTH and DAY values are only
153 checked to ensure that they fit into the fixed number of digits.
154 This allows the use of this function on data other than actual
155 Gregorian dates.
156 Ordinal dates
158 Each year is divided into days, numbered sequentially from 1. The year
159 lengths are irregular. The years correspond exactly to those of the
160 Gregorian calendar.
161 year_days(YEAR)
163 The parameter identifies a year, and the function returns the
164 number of days in that year as a native Perl integer.
165 cjdn_to_yd(CJDN)
167 This function takes a Chronological Julian Day Number and returns a
168 list of a year and ordinal day.
169 yd_to_cjdn(YEAR, DAY)
171 This performs the reverse of the translation that "cjdn_to_yd"
172 does. It takes year and ordinal day numbers, and returns the
173 corresponding CJDN.
174 present_yd(CJDN)
176 present_yd(YEAR, DAY)
177 Puts the given date into ISO 8601 ordinal textual presentation
178 format. The `extended' format (with "-" separators) is used. The
179 conformance notes for "present_y" apply to this function also.
180 If the date is given as a (YEAR, DAY) pair then these are not
182 checked for consistency. The DAY value is only checked to ensure
183 that it fits into the fixed number of digits. This allows the use
184 of this function on data other than actual ordinal dates.
185 Week-based calendar
187 Each year is divided into weeks, numbered sequentially from 1. Each
188 week is divided into seven days, numbered [1, 7]; day number 1 is
189 Monday. The year lengths are irregular. The year numbers have
190 unlimited range.
191 The years correspond to those of the Gregorian calendar. Each week is
193 associated with the Gregorian year that contains its Thursday and hence
194 contains the majority of its days.
195 year_weeks(YEAR)
197 The parameter identifies a year, and the function returns the
198 number of weeks in that year as a native Perl integer.
199 cjdn_to_ywd(CJDN)
201 This function takes a Chronological Julian Day Number and returns a
202 list of a year, week, and day.
203 ywd_to_cjdn(YEAR, WEEK, DAY)
205 This performs the reverse of the translation that "cjdn_to_ywd"
206 does. It takes year, week, and day numbers, and returns the
207 corresponding CJDN.
208 present_ywd(CJDN)
210 present_ywd(YEAR, WEEK, DAY)
211 Puts the given date into ISO 8601 week-based textual presentation
212 format. The `extended' format (with "-" separators) is used. The
213 conformance notes for "present_y" apply to this function also.
214 If the date is given as a (YEAR, WEEK, DAY) triplet then these are
216 not checked for consistency. The WEEK and DAY values are only
217 checked to ensure that they fit into the fixed number of digits.
218 This allows the use of this function on data other than actual
219 week-based dates.
220
222 Date::JD, DateTime
223
225 Andrew Main (Zefram) <zefram@fysh.org>
226
228 Copyright (C) 2006, 2007, 2009, 2011 Andrew Main (Zefram)
229 <zefram@fysh.org>
230
232 This module is free software; you can redistribute it and/or modify it
233 under the same terms as Perl itself.
234perl v5.12.3 2011-08-16 Date::ISO8601(3)