Provided by: libdate-iso8601-perl_0.005-1_all bug

NAME

       Date::ISO8601 - the three ISO 8601 numerical calendars

SYNOPSIS

           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);

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, 2017 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.