Date::ISO8601(3) User Contributed Perl Documentation Date::ISO8601(3)NAMEDate::ISO8601 - the three ISO 8601 numerical calendars
SYNOPSIS
use Date::ISO8601qw(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);
DESCRIPTION
The international standard ISO 8601 "Data elements and interchange
formats - Information interchange - Representation of dates and times"
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 ISO 8601 formats. ISO 8601 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.
The first ISO 8601 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 XIII in the late
sixteenth century, with AD (CE) 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.
The second ISO 8601 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 "ordinal dates". Ordinal dates are commonly
referred to as "Julian dates", a mistake apparently deriving from true
Julian Day Numbers, which divide time up solely into linearly counted
days.
The third ISO 8601 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 "the ISO calendar", apparently
in the belief that ISO 8601 does not define any other. It is also
referred to as "business dates", because it is most used by certain
businesses to whom the week is the most important temporal cycle.
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 CJDN equals the JD at noon. By way of epoch, the
day on which the Convention of the Metre was signed, which ISO 8601
defines to be 1875-05-20 (and 1875-140 and 1875-W20-4), is CJDN
2406029.
This module places no limit on the range of dates to which it may be
applied. All function arguments are permitted to be "Math::BigInt" or
"Math::BigRat" 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.
FUNCTIONS
Numbers in this API may be native Perl integers, "Math::BigInt"
objects, or integer-valued "Math::BigRat" 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.
All functions "die" if given invalid parameters.
Years
present_y(YEAR)
Puts the given year number into ISO 8601 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.
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 "sprintf" (see "sprintf" in
perlfunc).
This format is unconditionally conformant to all versions of ISO
8601 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 ISO 8601:2004 (earlier
versions lacked these formats), and only where it is mutually
agreed to use this format.
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.
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.
cjdn_to_ymd(CJDN)
This function takes a Chronological Julian Day Number and returns a
list of a year, month, and day.
ymd_to_cjdn(YEAR, MONTH, DAY)
This performs the reverse of the translation that "cjdn_to_ymd"
does. It takes year, month, and day numbers, and returns the
corresponding CJDN.
present_ymd(CJDN)
present_ymd(YEAR, MONTH, DAY)
Puts the given date into ISO 8601 Gregorian textual presentation
format. The `extended' format (with "-" separators) is used. The
conformance notes for "present_y" apply to this function also.
If the date is given as a (YEAR, MONTH, DAY) triplet then these are
not checked for consistency. The MONTH and DAY 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.
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.
year_days(YEAR)
The parameter identifies a year, and the function returns the
number of days in that year as a native Perl integer.
cjdn_to_yd(CJDN)
This function takes a Chronological Julian Day Number and returns a
list of a year and ordinal day.
yd_to_cjdn(YEAR, DAY)
This performs the reverse of the translation that "cjdn_to_yd"
does. It takes year and ordinal day numbers, and returns the
corresponding CJDN.
present_yd(CJDN)
present_yd(YEAR, DAY)
Puts the given date into ISO 8601 ordinal textual presentation
format. The `extended' format (with "-" separators) is used. The
conformance notes for "present_y" apply to this function also.
If the date is given as a (YEAR, DAY) pair then these are not
checked for consistency. The DAY 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.
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.
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.
year_weeks(YEAR)
The parameter identifies a year, and the function returns the
number of weeks in that year as a native Perl integer.
cjdn_to_ywd(CJDN)
This function takes a Chronological Julian Day Number and returns a
list of a year, week, and day.
ywd_to_cjdn(YEAR, WEEK, DAY)
This performs the reverse of the translation that "cjdn_to_ywd"
does. It takes year, week, and day numbers, and returns the
corresponding CJDN.
present_ywd(CJDN)
present_ywd(YEAR, WEEK, DAY)
Puts the given date into ISO 8601 week-based textual presentation
format. The `extended' format (with "-" separators) is used. The
conformance notes for "present_y" apply to this function also.
If the date is given as a (YEAR, WEEK, DAY) triplet then these are
not checked for consistency. The WEEK and DAY 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.
SEE ALSO
Date::JD, DateTime
AUTHOR
Andrew Main (Zefram) <zefram@fysh.org>
COPYRIGHT
Copyright (C) 2006, 2007, 2009, 2011 Andrew Main (Zefram)
<zefram@fysh.org>
LICENSE
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.14.1 2011-08-16 Date::ISO8601(3)
