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