From 540971a405498be30c9cef7ff6cf69f0099c15d6 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 3 Aug 2022 15:07:25 -0500 Subject: [PATCH 1/5] New doc about Julian/Gregorian --- .gitignore | 1 - doc/date/calendars.rdoc | 78 +++++++++++++++++++++++++++++++++++++++++ ext/date/date_core.c | 5 +-- 3 files changed, 81 insertions(+), 3 deletions(-) create mode 100644 doc/date/calendars.rdoc diff --git a/.gitignore b/.gitignore index 11d1d4d..a31186c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,6 @@ /.bundle/ /Gemfile.lock /coverage/ -/doc/ /pkg/ *.bundle *.dll diff --git a/doc/date/calendars.rdoc b/doc/date/calendars.rdoc new file mode 100644 index 0000000..d1c09f0 --- /dev/null +++ b/doc/date/calendars.rdoc @@ -0,0 +1,78 @@ +== 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 + +For a \Date object created with Date::JULIAN or Date::GREGORIAN, +there are implications when the date is incremented or decremented: + + # Julian date, incremented to a Gregorian date. + d0 = Date.new(1582, 1, 1, Date::ITALY) # => # + d0.julian? # => true + d1 = d0.next_year # => # + d1.gregorian? # => true + + # Gregorian date, decremented to a Julian date. + d0 = Date.new(1583, 1, 1, Date::ITALY) # => # + d0.gregorian? # => true + d1 = d0.prev_year # => # + d1.julian? # => true + diff --git a/ext/date/date_core.c b/ext/date/date_core.c index cee7b27..5ee64d9 100644 --- a/ext/date/date_core.c +++ b/ext/date/date_core.c @@ -9537,7 +9537,7 @@ Init_date_core(void) * * The value of the +start+ argument may be: * - * - Date::ITALY (the default) - the changeover date is October 10, 1582: + * - Date::ITALY (the default) - the changeover date is October 15, 1582: * * Date::ITALY # => 2299161 * Date.jd(Date::ITALY).to_s # => "1582-10-15" @@ -9552,7 +9552,7 @@ Init_date_core(void) * # Gregorian base date, Julian result date. * (Date.new(1583, 1, 1, Date::ITALY) - 365).to_s # => "1581-12-22" * - * - Date::ENGLAND - the changeover date is September 9, 1752: + * - Date::ENGLAND - the changeover date is September 14, 1752: * * Date::ENGLAND # => 2361222 * Date.jd(Date::ENGLAND).to_s # => "1752-09-14" @@ -9584,6 +9584,7 @@ Init_date_core(void) * - Other non-numeric: raises TypeError. * */ + cDate = rb_define_class("Date", rb_cObject); /* Exception for invalid date/time */ From 4f2b8079c1f42e66b0a2f36bd3196c8a6fc40c93 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 4 Aug 2022 10:06:03 -0500 Subject: [PATCH 2/5] New doc about Julian/Gregorian --- ext/date/date_core.c | 86 ++++++++++---------------------------------- 1 file changed, 19 insertions(+), 67 deletions(-) diff --git a/ext/date/date_core.c b/ext/date/date_core.c index 5ee64d9..1c0d1c4 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) * * 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) * 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) * 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) * * 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); * * 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) * * 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) * 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) * 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); * * 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) * {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) * * 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) * * 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) * * 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) * * 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) * * 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) * * 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) * * 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) * 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@Argument+start]. * */ static VALUE @@ -5830,7 +5830,7 @@ dup_obj_with_new_start(VALUE obj, double sg) * d1 = d0.new_start(Date::JULIAN) * d1.julian? # => true * - * See argument {start}[rdoc-ref:Date@Argument+start]. + * See argument {start}[rdoc-ref:calendars.rdoc@Argument+start]. * */ static VALUE @@ -9522,54 +9522,6 @@ Init_date_core(void) * d += 1 #=> # * d.strftime('%a %d %b %Y') #=> "Sun 04 Feb 2001" * - * === Argument +start+ - * - * Certain calculations and comparisons for a \Date object - * are affected by what the object considers to have been - * the changeover date from the - * {Julian}[https://en.wikipedia.org/wiki/Julian_calendar] to the - * {Gregorian}[https://en.wikipedia.org/wiki/Gregorian_calendar] - * calendar; - * this is set by argument +start+ when the object is created: - * - * - Dates before the changeover are considered to be Julian. - * - Dates after the changeover are considered to be Gregorian. - * - * The value of the +start+ argument may be: - * - * - Date::ITALY (the default) - the changeover date is October 15, 1582: - * - * Date::ITALY # => 2299161 - * Date.jd(Date::ITALY).to_s # => "1582-10-15" - * - * # Julian base date, Julian result date. - * (Date.new(1581, 1, 1, Date::ITALY) + 365).to_s # => "1582-01-01" - * # Gregorian base date, Gregorian result date. - * (Date.new(1583, 1, 1, Date::ITALY) + 365).to_s # => "1584-01-01" - * - * # Julian base date, Gregorian result date. - * (Date.new(1582, 1, 1, Date::ITALY) + 365).to_s # => "1583-01-11" - * # Gregorian base date, Julian result date. - * (Date.new(1583, 1, 1, Date::ITALY) - 365).to_s # => "1581-12-22" - * - * - Date::ENGLAND - the changeover date is September 14, 1752: - * - * Date::ENGLAND # => 2361222 - * Date.jd(Date::ENGLAND).to_s # => "1752-09-14" - * - * # Julian base date, Julian result date. - * (Date.new(1751, 1, 1, Date::ENGLAND) + 365).to_s # => "1752-01-01" - * # Gregorian base date, Gregorian result date. - * (Date.new(1753, 1, 1, Date::ENGLAND) + 365).to_s # => "1754-01-01" - * - * # Julian base date, Gregorian result date. - * (Date.new(1752, 1, 1, Date::ENGLAND) + 365).to_s # => "1753-01-11" - * # Gregorian base date, Julian result date. - * (Date.new(1753, 1, 1, Date::ENGLAND) - 365).to_s # => "1751-12-22" - * - * - Date::JULIAN - no changeover date; all dates are Julian. - * - Date::GREGORIAN - no changeover date; all dates are Gregorian. - * * === Argument +limit+ * * Certain singleton methods in \Date that parse string arguments From d8e8ee32670ad1ddc8001db81cf40d0352fa5821 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 4 Aug 2022 13:59:05 -0500 Subject: [PATCH 3/5] New doc about Julian/Gregorian --- .document | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.document b/.document index 7f60f8e..b02980f 100644 --- a/.document +++ b/.document @@ -1,3 +1,5 @@ README.md ext/date/*.[ch] lib/date.rb +doc/date/calendars.rdoc + From 45002f7248cce77d9c11cd0bde3560fb03ab8119 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 4 Aug 2022 14:42:28 -0500 Subject: [PATCH 4/5] New doc about Julian/Gregorian --- doc/date/calendars.rdoc | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/doc/date/calendars.rdoc b/doc/date/calendars.rdoc index d1c09f0..e2118d3 100644 --- a/doc/date/calendars.rdoc +++ b/doc/date/calendars.rdoc @@ -61,18 +61,3 @@ by accepting an optional argument +start+, whose value may be: d = Date.new(1752, 9, 14, Date::GREGORIAN) d.prev_day.gregorian? # => true -For a \Date object created with Date::JULIAN or Date::GREGORIAN, -there are implications when the date is incremented or decremented: - - # Julian date, incremented to a Gregorian date. - d0 = Date.new(1582, 1, 1, Date::ITALY) # => # - d0.julian? # => true - d1 = d0.next_year # => # - d1.gregorian? # => true - - # Gregorian date, decremented to a Julian date. - d0 = Date.new(1583, 1, 1, Date::ITALY) # => # - d0.gregorian? # => true - d1 = d0.prev_year # => # - d1.julian? # => true - From ae64281ae1c60827ee4c2a35a302dbabc5ed1856 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Fri, 5 Aug 2022 13:03:28 -0500 Subject: [PATCH 5/5] Update .document Co-authored-by: Peter Zhu --- .document | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.document b/.document index b02980f..aa07ea7 100644 --- a/.document +++ b/.document @@ -1,5 +1,5 @@ README.md ext/date/*.[ch] lib/date.rb -doc/date/calendars.rdoc +doc/date/*