.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Date::ISO8601 3pm"
.TH Date::ISO8601 3pm "2017-08-03" "perl v5.26.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Date::ISO8601 \- the three ISO 8601 numerical calendars
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Date::ISO8601 qw(present_y);
\&
\&    print present_y($y);
\&
\&    use Date::ISO8601 qw(
\&        month_days cjdn_to_ymd ymd_to_cjdn present_ymd);
\&
\&    $md = month_days(2000, 2);
\&    ($y, $m, $d) = cjdn_to_ymd(2406029);
\&    $cjdn = ymd_to_cjdn(1875, 5, 20);
\&    print present_ymd(2406029);
\&    print present_ymd(1875, 5, 20);
\&
\&    use Date::ISO8601 qw(year_days cjdn_to_yd yd_to_cjdn present_yd);
\&
\&    $yd = year_days(2000);
\&    ($y, $d) = cjdn_to_yd(2406029);
\&    $cjdn = yd_to_cjdn(1875, 140);
\&    print present_yd(2406029);
\&    print present_yd(1875, 140);
\&
\&    use Date::ISO8601 qw(
\&        year_weeks cjdn_to_ywd ywd_to_cjdn present_ywd);
\&
\&    $yw = year_weeks(2000);
\&    ($y, $w, $d) = cjdn_to_ywd(2406029);
\&    $cjdn = ywd_to_cjdn(1875, 20, 4);
\&    print present_ywd(2406029);
\&    print present_ywd(1875, 20, 4);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The international standard \s-1ISO 8601\s0 \*(L"Data elements and interchange formats
\&\- Information interchange \- Representation of dates and times\*(R" defines
three distinct calendars by which days can be labelled.  It also defines
textual formats for the representation of dates in these calendars.
This module provides functions to convert dates between these three
calendars and Chronological Julian Day Numbers, which is a suitable
format to do arithmetic with.  It also supplies functions that describe
the shape of these calendars, to assist in calendrical calculations.
It also supplies functions to represent dates textually in the \s-1ISO
8601\s0 formats.  \s-1ISO 8601\s0 also covers time of day and time periods, but
this module does nothing relating to those parts of the standard; this
is only about labelling days.
.PP
The first \s-1ISO 8601\s0 calendar divides time up into years, months, and days.
It corresponds exactly to the Gregorian calendar, invented by Aloysius
Lilius and promulgated by Pope Gregory \s-1XIII\s0 in the late sixteenth century,
with \s-1AD\s0 (\s-1CE\s0) year numbering.  This calendar is applied to all time,
not just to dates after its invention nor just to years 1 and later.
Thus for ancient dates it is the proleptic Gregorian calendar with
astronomical year numbering.
.PP
The second \s-1ISO 8601\s0 calendar divides time up into the same years as
the first, but divides the year directly into days, with no months.
The standard calls this \*(L"ordinal dates\*(R".  Ordinal dates are commonly
referred to as \*(L"Julian dates\*(R", a mistake apparently deriving from true
Julian Day Numbers, which divide time up solely into linearly counted
days.
.PP
The third \s-1ISO 8601\s0 calendar divides time up into years, weeks, and days.
The years approximate the years of the first two calendars, so they stay
in step in the long term, but the boundaries differ.  This week-based
calendar is sometimes called \*(L"the \s-1ISO\s0 calendar\*(R", apparently in the belief
that \s-1ISO 8601\s0 does not define any other.  It is also referred to as
\&\*(L"business dates\*(R", because it is most used by certain businesses to whom
the week is the most important temporal cycle.
.PP
The Chronological Julian Day Number is an integral number labelling each
day, where the day extends from midnight to midnight in whatever time zone
is of interest.  It is a linear count of days, where each day's number
is one greater than the previous day's number.  It is directly related to
the Julian Date system: in the time zone of the prime meridian, the \s-1CJDN\s0
equals the \s-1JD\s0 at noon.  By way of epoch, the day on which the Convention
of the Metre was signed, which \s-1ISO 8601\s0 defines to be 1875\-05\-20 (and
1875\-140 and 1875\-W20\-4), is \s-1CJDN 2406029.\s0
.PP
This module places no limit on the range of dates to which it may be
applied.  All function arguments are permitted to be \f(CW\*(C`Math::BigInt\*(C'\fR or
\&\f(CW\*(C`Math::BigRat\*(C'\fR objects in order to achieve arbitrary range.  Native Perl
integers are also permitted, as a convenience when the range of dates
being handled is known to be sufficiently small.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
Numbers in this \s-1API\s0 may be native Perl integers, \f(CW\*(C`Math::BigInt\*(C'\fR objects,
or integer-valued \f(CW\*(C`Math::BigRat\*(C'\fR objects.  All three types are acceptable
for all parameters, in any combination.  In all conversion functions,
the most-significant part of the result (which is the only part with
unlimited range) is of the same type as the most-significant part of
the input.  Less-significant parts of results (which have a small range)
are consistently native Perl integers.
.PP
All functions \f(CW\*(C`die\*(C'\fR if given invalid parameters.
.SS "Years"
.IX Subsection "Years"
.IP "present_y(\s-1YEAR\s0)" 4
.IX Item "present_y(YEAR)"
Puts the given year number into \s-1ISO 8601\s0 textual presentation format.
For years [0, 9999] this is simply four digits.  For years outside that
range it is a sign followed by at least four digits.
.Sp
This is the minimum-length presentation format.  If it is desired to
use a form that is longer than necessary, such as to use at least five
digits for all year numbers (as the Long Now Foundation does), then the
right tool is \f(CW\*(C`sprintf\*(C'\fR (see \*(L"sprintf\*(R" in perlfunc).
.Sp
This format is unconditionally conformant to all versions of \s-1ISO 8601\s0
for years [1583, 9999].  For years [0, 1582], preceding the historical
introduction of the Gregorian calendar, it is conformant only where
it is mutually agreed that such dates (represented in the proleptic
Gregorian calendar) are acceptable.  For years outside the range [0,
9999], where the expanded format must be used, the result is only
conformant to \s-1ISO 8601:2004\s0 (earlier versions lacked these formats),
and only where it is mutually agreed to use this format.
.SS "Gregorian calendar"
.IX Subsection "Gregorian calendar"
Each year is divided into twelve months, numbered [1, 12]; month number
1 is January.  Each month is divided into days, numbered sequentially
from 1.  The month lengths are irregular.  The year numbers have
unlimited range.
.IP "month_days(\s-1YEAR, MONTH\s0)" 4
.IX Item "month_days(YEAR, MONTH)"
The parameters identify a month, and the function returns the number of
days in that month as a native Perl integer.
.IP "cjdn_to_ymd(\s-1CJDN\s0)" 4
.IX Item "cjdn_to_ymd(CJDN)"
This function takes a Chronological Julian Day Number and returns a list
of a year, month, and day.
.IP "ymd_to_cjdn(\s-1YEAR, MONTH, DAY\s0)" 4
.IX Item "ymd_to_cjdn(YEAR, MONTH, DAY)"
This performs the reverse of the translation that \f(CW\*(C`cjdn_to_ymd\*(C'\fR does.
It takes year, month, and day numbers, and returns the corresponding \s-1CJDN.\s0
.IP "present_ymd(\s-1CJDN\s0)" 4
.IX Item "present_ymd(CJDN)"
.PD 0
.IP "present_ymd(\s-1YEAR, MONTH, DAY\s0)" 4
.IX Item "present_ymd(YEAR, MONTH, DAY)"
.PD
Puts the given date into \s-1ISO 8601\s0 Gregorian textual presentation format.
The `extended' format (with \*(L"\-\*(R" separators) is used.  The conformance
notes for \f(CW\*(C`present_y\*(C'\fR apply to this function also.
.Sp
If the date is given as a (\s-1YEAR, MONTH, DAY\s0) triplet then these are not
checked for consistency.  The \s-1MONTH\s0 and \s-1DAY\s0 values are only checked to
ensure that they fit into the fixed number of digits.  This allows the
use of this function on data other than actual Gregorian dates.
.SS "Ordinal dates"
.IX Subsection "Ordinal dates"
Each year is divided into days, numbered sequentially from 1.  The year
lengths are irregular.  The years correspond exactly to those of the
Gregorian calendar.
.IP "year_days(\s-1YEAR\s0)" 4
.IX Item "year_days(YEAR)"
The parameter identifies a year, and the function returns the number of
days in that year as a native Perl integer.
.IP "cjdn_to_yd(\s-1CJDN\s0)" 4
.IX Item "cjdn_to_yd(CJDN)"
This function takes a Chronological Julian Day Number and returns a
list of a year and ordinal day.
.IP "yd_to_cjdn(\s-1YEAR, DAY\s0)" 4
.IX Item "yd_to_cjdn(YEAR, DAY)"
This performs the reverse of the translation that \f(CW\*(C`cjdn_to_yd\*(C'\fR does.
It takes year and ordinal day numbers, and returns the corresponding \s-1CJDN.\s0
.IP "present_yd(\s-1CJDN\s0)" 4
.IX Item "present_yd(CJDN)"
.PD 0
.IP "present_yd(\s-1YEAR, DAY\s0)" 4
.IX Item "present_yd(YEAR, DAY)"
.PD
Puts the given date into \s-1ISO 8601\s0 ordinal textual presentation format.
The `extended' format (with \*(L"\-\*(R" separators) is used.  The conformance
notes for \f(CW\*(C`present_y\*(C'\fR apply to this function also.
.Sp
If the date is given as a (\s-1YEAR, DAY\s0) pair then these are not checked
for consistency.  The \s-1DAY\s0 value is only checked to ensure that it fits
into the fixed number of digits.  This allows the use of this function
on data other than actual ordinal dates.
.SS "Week-based calendar"
.IX Subsection "Week-based calendar"
Each year is divided into weeks, numbered sequentially from 1.  Each week
is divided into seven days, numbered [1, 7]; day number 1 is Monday.
The year lengths are irregular.  The year numbers have unlimited range.
.PP
The years correspond to those of the Gregorian calendar.  Each week is
associated with the Gregorian year that contains its Thursday and hence
contains the majority of its days.
.IP "year_weeks(\s-1YEAR\s0)" 4
.IX Item "year_weeks(YEAR)"
The parameter identifies a year, and the function returns the number of
weeks in that year as a native Perl integer.
.IP "cjdn_to_ywd(\s-1CJDN\s0)" 4
.IX Item "cjdn_to_ywd(CJDN)"
This function takes a Chronological Julian Day Number and returns a list
of a year, week, and day.
.IP "ywd_to_cjdn(\s-1YEAR, WEEK, DAY\s0)" 4
.IX Item "ywd_to_cjdn(YEAR, WEEK, DAY)"
This performs the reverse of the translation that \f(CW\*(C`cjdn_to_ywd\*(C'\fR does.
It takes year, week, and day numbers, and returns the corresponding \s-1CJDN.\s0
.IP "present_ywd(\s-1CJDN\s0)" 4
.IX Item "present_ywd(CJDN)"
.PD 0
.IP "present_ywd(\s-1YEAR, WEEK, DAY\s0)" 4
.IX Item "present_ywd(YEAR, WEEK, DAY)"
.PD
Puts the given date into \s-1ISO 8601\s0 week-based textual presentation format.
The `extended' format (with \*(L"\-\*(R" separators) is used.  The conformance
notes for \f(CW\*(C`present_y\*(C'\fR apply to this function also.
.Sp
If the date is given as a (\s-1YEAR, WEEK, DAY\s0) triplet then these are not
checked for consistency.  The \s-1WEEK\s0 and \s-1DAY\s0 values are only checked to
ensure that they fit into the fixed number of digits.  This allows the
use of this function on data other than actual week-based dates.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Date::JD,
DateTime
.SH "AUTHOR"
.IX Header "AUTHOR"
Andrew Main (Zefram) <zefram@fysh.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2006, 2007, 2009, 2011, 2017
Andrew Main (Zefram) <zefram@fysh.org>
.SH "LICENSE"
.IX Header "LICENSE"
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.