1Date::ISO8601(3)      User Contributed Perl Documentation     Date::ISO8601(3)
2
3
4

NAME

6       Date::ISO8601 - the three ISO 8601 numerical calendars
7

SYNOPSIS

9           use Date::ISO8601 qw(present_y);
10
11           print present_y($y);
12
13           use Date::ISO8601 qw(
14               month_days cjdn_to_ymd ymd_to_cjdn present_ymd);
15
16           $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
22           use Date::ISO8601 qw(year_days cjdn_to_yd yd_to_cjdn present_yd);
23
24           $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
30           use Date::ISO8601 qw(
31               year_weeks cjdn_to_ywd ywd_to_cjdn present_ywd);
32
33           $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

DESCRIPTION

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
53       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
61       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
68       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
76       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
86       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

FUNCTIONS

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
101       All functions "die" if given invalid parameters.
102
103   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
109           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
115           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
125   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
131       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
135       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
139       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
144       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
150           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
156   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
161       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
165       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
169       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
174       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
180           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
185   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
191       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
195       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
199       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
203       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
208       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
214           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

SEE ALSO

221       Date::JD, DateTime
222

AUTHOR

224       Andrew Main (Zefram) <zefram@fysh.org>
225
227       Copyright (C) 2006, 2007, 2009, 2011, 2017 Andrew Main (Zefram)
228       <zefram@fysh.org>
229

LICENSE

231       This module is free software; you can redistribute it and/or modify it
232       under the same terms as Perl itself.
233
234
235
236perl v5.34.0                      2021-07-22                  Date::ISO8601(3)
Impressum