ruby-changes:72854
From: Burdette <ko1@a...>
Date: Mon, 8 Aug 2022 09:43:39 +0900 (JST)
Subject: [ruby-changes:72854] 1607c6d281 (master): [DOC] New doc about Julian/Gregorian (#70)
https://git.ruby-lang.org/ruby.git/commit/?id=1607c6d281 From 1607c6d2814cc4f71aa65bc273d745f28514e735 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Fri, 5 Aug 2022 13:06:03 -0500 Subject: [DOC] New doc about Julian/Gregorian (#70) --- doc/date/calendars.rdoc | 63 +++++++++++++++++++++++++++++++++++ ext/date/date_core.c | 87 ++++++++++++------------------------------------- 2 files changed, 83 insertions(+), 67 deletions(-) create mode 100644 doc/date/calendars.rdoc diff --git a/doc/date/calendars.rdoc b/doc/date/calendars.rdoc new file mode 100644 index 0000000000..e2118d3e9d --- /dev/null +++ b/doc/date/calendars.rdoc @@ -0,0 +1,63 @@ https://github.com/ruby/ruby/blob/trunk/doc/date/calendars.rdoc#L1 +== Julian and Gregorian Calendars + +The difference between the +{Julian calendar}[https://en.wikipedia.org/wiki/Julian_calendar] +and the +{Gregorian calendar}[https://en.wikipedia.org/wiki/Gregorian_calendar] +may matter to your program if it uses dates in the interval: + +- October 15, 1582. +- September 14, 1752. + +A date outside that interval (including all dates in modern times) +is the same in both calendars. +However, a date _within_ that interval will be different +in the two calendars. + +=== Different Calendar, Different \Date + +The reason for the difference is this: + +- On October 15, 1582, several countries changed + from the Julian calendar to the Gregorian calendar; + these included Italy, Poland, Portugal, and Spain. + Other contries in the Western world retained the Julian calendar. +- On September 14, 1752, most of the British empire + changed from the Julian calendar to the Gregorian calendar. + +When your code uses a date in this "gap" interval, +it will matter whether it considers the switchover date +to be the earlier date or the later date (or neither). + +=== Argument +start+ + +Certain methods in class \Date handle differences in the +{Julian and Gregorian calendars}[rdoc-ref:calendars.rdoc@Julian+and+Gregorian+Calendars] +by accepting an optional argument +start+, whose value may be: + +- Date::ITALY (the default): the created date is Julian + if before October 15, 1582, Gregorian otherwise: + + d = Date.new(1582, 10, 15) + d.prev_day.julian? # => true + d.julian? # => false + d.gregorian? # => true + +- Date::ENGLAND: the created date is Julian if before September 14, 1752, + Gregorian otherwise: + + d = Date.new(1752, 9, 14, Date::ENGLAND) + d.prev_day.julian? # => true + d.julian? # => false + d.gregorian? # => true + +- Date::JULIAN: the created date is Julian regardless of its value: + + d = Date.new(1582, 10, 15, Date::JULIAN) + d.julian? # => true + +- Date::GREGORIAN: the created date is Gregorian regardless of its value: + + d = Date.new(1752, 9, 14, Date::GREGORIAN) + d.prev_day.gregorian? # => true + diff --git a/ext/date/date_core.c b/ext/date/date_core.c index cee7b27faf..1c0d1c4920 100644 --- a/ext/date/date_core.c +++ b/ext/date/date_core.c @@ -2486,7 +2486,7 @@ date_s__valid_jd_p(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L2486 * * Date.valid_jd?(2451944) # => true * - * See argument {start}[rdoc-ref:Date@Argument+start]. + * See argument {start}[rdoc-ref:calendars.rdoc@Argument+start]. * * Related: Date.jd. */ @@ -2580,7 +2580,7 @@ date_s__valid_civil_p(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L2580 * Date.valid_date?(2001, 2, 29) # => false * Date.valid_date?(2001, 2, -1) # => true * - * See argument {start}[rdoc-ref:Date@Argument+start]. + * See argument {start}[rdoc-ref:calendars.rdoc@Argument+start]. * * Date.valid_date? is an alias for Date.valid_civil?. * @@ -2670,7 +2670,7 @@ date_s__valid_ordinal_p(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L2670 * Date.valid_ordinal?(2001, 34) # => true * Date.valid_ordinal?(2001, 366) # => false * - * See argument {start}[rdoc-ref:Date@Argument+start]. + * See argument {start}[rdoc-ref:calendars.rdoc@Argument+start]. * * Related: Date.jd, Date.ordinal. */ @@ -2760,7 +2760,7 @@ date_s__valid_commercial_p(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L2760 * * See Date.commercial. * - * See argument {start}[rdoc-ref:Date@Argument+start]. + * See argument {start}[rdoc-ref:calendars.rdoc@Argument+start]. * * Related: Date.jd, Date.commercial. */ @@ -3342,7 +3342,7 @@ static VALUE d_lite_plus(VALUE, VALUE); https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L3342 * * Date.jd(Date::ITALY - 1).julian? # => true * - * See argument {start}[rdoc-ref:Date@Argument+start]. + * See argument {start}[rdoc-ref:calendars.rdoc@Argument+start]. * * Related: Date.new. */ @@ -3407,7 +3407,7 @@ date_s_jd(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L3407 * * Raises an exception if +yday+ is zero or out of range. * - * See argument {start}[rdoc-ref:Date@Argument+start]. + * See argument {start}[rdoc-ref:calendars.rdoc@Argument+start]. * * Related: Date.jd, Date.new. */ @@ -3484,7 +3484,7 @@ date_s_civil(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L3484 * where +n+ is the number of days in the month; * when the argument is negative, counts backward from the end of the month. * - * See argument {start}[rdoc-ref:Date@Argument+start]. + * See argument {start}[rdoc-ref:calendars.rdoc@Argument+start]. * * Date.civil is an alias for Date.new. * @@ -3592,7 +3592,7 @@ date_initialize(int argc, VALUE *argv, VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L3592 * Date.commercial(2020, 1, 1).to_s # => "2019-12-30" Date.commercial(2020, 1, 7).to_s # => "2020-01-05" * - * See argument {start}[rdoc-ref:Date@Argument+start]. + * See argument {start}[rdoc-ref:calendars.rdoc@Argument+start]. * * Related: Date.jd, Date.new, Date.ordinal. */ @@ -3777,7 +3777,7 @@ static void set_sg(union DateData *, double); https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L3777 * * Date.today.to_s # => "2022-07-06" * - * See argument {start}[rdoc-ref:Date@Argument+start]. + * See argument {start}[rdoc-ref:calendars.rdoc@Argument+start]. * */ static VALUE @@ -4409,7 +4409,7 @@ date_s__strptime(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4409 * {Formats for Dates and Times}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html]. * (Unlike Date.strftime, does not support flags and width.) * - * See argument {start}[rdoc-ref:Date@Argument+start]. + * See argument {start}[rdoc-ref:calendars.rdoc@Argument+start]. * * See also {strptime(3)}[https://man7.org/linux/man-pages/man3/strptime.3.html]. * @@ -4556,7 +4556,7 @@ date_s__parse(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4556 * * See: * - * - Argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {start}[rdoc-ref:calendars.rdoc@Argument+start]. * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * * Related: Date._parse (returns a hash). @@ -4636,7 +4636,7 @@ date_s__iso8601(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4636 * * See: * - * - Argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {start}[rdoc-ref:calendars.rdoc@Argument+start]. * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * * Related: Date._iso8601 (returns a hash). @@ -4707,7 +4707,7 @@ date_s__rfc3339(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4707 * * See: * - * - Argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {start}[rdoc-ref:calendars.rdoc@Argument+start]. * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * * Related: Date._rfc3339 (returns a hash). @@ -4776,7 +4776,7 @@ date_s__xmlschema(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4776 * * See: * - * - Argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {start}[rdoc-ref:calendars.rdoc@Argument+start]. * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * * Related: Date._xmlschema (returns a hash). @@ -4849,7 +4849,7 @@ date_s__rfc2822(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4849 * * See: * - * - Argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {start}[rdoc-ref:calendars.rdoc@Argument+start]. * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * * Date.rfc822 is an alias for Date.rfc2822. @@ -4919,7 +4919,7 @@ date_s__httpdate(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4919 * * See: * - * - Argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {start}[rdoc-ref:calendars.rdoc@Argument+start]. * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * * Related: Date._httpdate (returns a hash). @@ -4991,7 +4991,7 @@ date_s__jisx0301(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4991 * * See: * - * - Argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {start}[rdoc-ref:calendars.rdoc@Argument+start]. * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * * Related: Date._jisx0301 (returns a hash). @@ -5755,7 +5755,7 @@ d_lite_leap_p(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L5755 * Date.new(2001, 2, 3, Date::GREGORIAN).start # => -Infinity * Date.new(2001, 2, 3, Date::JULIAN).start # => Infinity * - * See argument {start}[rdoc-ref:Date@Argument+start]. + * See argument {start}[rdoc-ref:calendars.rdoc@Ar (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/