From f4791418709b36219e5531831b3278d86faa8739 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Mon, 4 Jul 2022 17:24:39 -0500 Subject: [PATCH 1/4] Enhanced RDoc --- ext/date/date_core.c | 94 ++++++++++++++++++++++++++++++++++---------- 1 file changed, 74 insertions(+), 20 deletions(-) diff --git a/ext/date/date_core.c b/ext/date/date_core.c index 3ba66ce..a523466 100644 --- a/ext/date/date_core.c +++ b/ext/date/date_core.c @@ -2732,7 +2732,7 @@ date_s__valid_commercial_p(int argc, VALUE *argv, VALUE klass) /* * call-seq: - * Date.valid_commercial?(cwyear, cweek, cwday, start = Date::ITALY) -> true or false + * Date.valid_commercial?(cwyear, cweek, cwday, start = Date::ITALY) -> true or false * * Returns +true+ if the arguments define a valid commercial date, * +false+ otherwise: @@ -2740,6 +2740,8 @@ date_s__valid_commercial_p(int argc, VALUE *argv, VALUE klass) * Date.valid_commercial?(2001, 5, 6) # => true * Date.valid_commercial?(2001, 5, 8) # => false * + * See Date.commercial. + * * See {Argument start}[rdoc-ref:Date@Argument+start]. * * Related: Date.jd, Date.commercial. @@ -3527,19 +3529,64 @@ date_initialize(int argc, VALUE *argv, VALUE self) /* * call-seq: - * Date.commercial([cwyear=-4712[, cweek=1[, cwday=1[, start=Date::ITALY]]]]) -> date + * Date.commercial(cwyear=-4712, cweek=1, cwday=1, start=Date::ITALY) -> date + * + * Returns a new \Date object constructed from the arguments. + * + * Argument +cwyear+ should be an integer. + * The actual year in the new date is: + * + * - +cwyear+, if January 1 of that year is a Friday, Saturday, + * Sunday, or Monday + * (that is, if the first Monday in calendar year +cwyear+ + * is on or before January 4): + * + * [2010, 2000, 2006, 2001].each do |year| + * wday = Date::ABBR_DAYNAMES[Date.new(year, 1, 1).wday] + * cdate = Date.commercial(year) + * p [year, wday, cdate.to_s] + * end + * + * Output: + * + * [2010, "Fri", "2010-01-04"] + * [2000, "Sat", "2000-01-03"] + * [2006, "Sun", "2006-01-02"] + * [2001, "Mon", "2001-01-01"] + * + * - cwyear - 1, otherwise: + * + * [2002, 2003, 2004].each do |year| + * wday = Date::ABBR_DAYNAMES[Date.new(year, 1, 1).wday] + * cdate = Date.commercial(year) + * p [year, wday, cdate.to_s] + * end * - * Creates a date object denoting the given week date. + * Output: * - * The week and the day of week should be a negative or a positive - * number (as a relative week/day from the end of year/week when - * negative). They should not be zero. + * [2002, "Tue", "2001-12-31"] + * [2003, "Wed", "2002-12-30"] + * [2004, "Thu", "2003-12-29"] * - * Date.commercial(2001) #=> # - * Date.commercial(2002) #=> # - * Date.commercial(2001,5,6) #=> # + * Argument +cweek+ gives the index of the week within the year, + * and should be in range (1..53) or (-53..-1); + * in some years, 53 or -53 will be out-of-range; + * if negative, counts backward from the end of the year: * - * See also ::jd and ::new. + * Date.commercial(2022, 1, 1).to_s # => "2022-01-03" + * Date.commercial(2022, 52, 1).to_s # => "2022-12-26" + * + * Argument +cwday+ gives the indes of the weekday within the week, + * and should be in range (1..7) or (-7..-1); + * 1 or -7 is Monday; + * if negative, counts backward from the end of the week: + * + * Date.commercial(2022, 1, 1).to_s # => "2022-01-03" + * Date.commercial(2022, 1, -7).to_s # => "2022-01-03" + * + * See {Argument start}[rdoc-ref:Date@Argument+start]. + * + * Related: Date.jd, Date.new, Date.ordinal. */ static VALUE date_s_commercial(int argc, VALUE *argv, VALUE klass) @@ -5226,12 +5273,14 @@ d_lite_day_fraction(VALUE self) /* * call-seq: - * d.cwyear -> integer + * cwyear -> integer + * + * Returns commercial-date year for +self+ + * (see Date.commercial): * - * Returns the calendar week based year. + * Date.new(2001, 2, 3).cwyear # => 2001 + * Date.new(2000, 1, 1).cwyear # => 1999 * - * Date.new(2001,2,3).cwyear #=> 2001 - * Date.new(2000,1,1).cwyear #=> 1999 */ static VALUE d_lite_cwyear(VALUE self) @@ -5242,11 +5291,13 @@ d_lite_cwyear(VALUE self) /* * call-seq: - * d.cweek -> fixnum + * cweek -> integer * - * Returns the calendar week number (1-53). + * Returns commercial-date week index for +self+ + * (see Date.commercial): + * + * Date.new(2001, 2, 3).cweek # => 5 * - * Date.new(2001,2,3).cweek #=> 5 */ static VALUE d_lite_cweek(VALUE self) @@ -5257,11 +5308,14 @@ d_lite_cweek(VALUE self) /* * call-seq: - * d.cwday -> fixnum + * cwday -> integer + * + * Returns the commercial-date weekday index for +self+ + * (see Date.commercial); + * 1 is Monday: * - * Returns the day of calendar week (1-7, Monday is 1). + * Date.new(2001, 2, 3).cwday # => 6 * - * Date.new(2001,2,3).cwday #=> 6 */ static VALUE d_lite_cwday(VALUE self) From 189f16caea9afcb34b7b135f36d1d87994452058 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 5 Jul 2022 09:35:24 -0500 Subject: [PATCH 2/4] Enhanced RDoc --- ext/date/date_core.c | 37 ++++++++++++++++++++----------------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/ext/date/date_core.c b/ext/date/date_core.c index a523466..9ac85ca 100644 --- a/ext/date/date_core.c +++ b/ext/date/date_core.c @@ -3534,7 +3534,26 @@ date_initialize(int argc, VALUE *argv, VALUE self) * Returns a new \Date object constructed from the arguments. * * Argument +cwyear+ should be an integer. - * The actual year in the new date is: + * + * Argument +cweek+ gives the index of the week within the year, + * and should be in range (1..53) or (-53..-1); + * in some years, 53 or -53 will be out-of-range; + * if negative, counts backward from the end of the year: + * + * Date.commercial(2022, 1, 1).to_s # => "2022-01-03" + * Date.commercial(2022, 52, 1).to_s # => "2022-12-26" + * + * Argument +cwday+ gives the indes of the weekday within the week, + * and should be in range (1..7) or (-7..-1); + * 1 or -7 is Monday; + * if negative, counts backward from the end of the week: + * + * Date.commercial(2022, 1, 1).to_s # => "2022-01-03" + * Date.commercial(2022, 1, -7).to_s # => "2022-01-03" + * + * When +cweek+ is 1, the actual year in the new date + * may be different from +cwyear+; + * the actual year is: * * - +cwyear+, if January 1 of that year is a Friday, Saturday, * Sunday, or Monday @@ -3568,22 +3587,6 @@ date_initialize(int argc, VALUE *argv, VALUE self) * [2003, "Wed", "2002-12-30"] * [2004, "Thu", "2003-12-29"] * - * Argument +cweek+ gives the index of the week within the year, - * and should be in range (1..53) or (-53..-1); - * in some years, 53 or -53 will be out-of-range; - * if negative, counts backward from the end of the year: - * - * Date.commercial(2022, 1, 1).to_s # => "2022-01-03" - * Date.commercial(2022, 52, 1).to_s # => "2022-12-26" - * - * Argument +cwday+ gives the indes of the weekday within the week, - * and should be in range (1..7) or (-7..-1); - * 1 or -7 is Monday; - * if negative, counts backward from the end of the week: - * - * Date.commercial(2022, 1, 1).to_s # => "2022-01-03" - * Date.commercial(2022, 1, -7).to_s # => "2022-01-03" - * * See {Argument start}[rdoc-ref:Date@Argument+start]. * * Related: Date.jd, Date.new, Date.ordinal. From ac2526c7c8080abcf7624eff8f11c0eb83a43f76 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 5 Jul 2022 16:51:37 -0500 Subject: [PATCH 3/4] Enhanced RDoc --- ext/date/date_core.c | 43 +++++++++++-------------------------------- 1 file changed, 11 insertions(+), 32 deletions(-) diff --git a/ext/date/date_core.c b/ext/date/date_core.c index 9ac85ca..c668097 100644 --- a/ext/date/date_core.c +++ b/ext/date/date_core.c @@ -3533,7 +3533,7 @@ date_initialize(int argc, VALUE *argv, VALUE self) * * Returns a new \Date object constructed from the arguments. * - * Argument +cwyear+ should be an integer. + * Argument +cwyear+ gives the year, and should be an integer. * * Argument +cweek+ gives the index of the week within the year, * and should be in range (1..53) or (-53..-1); @@ -3551,41 +3551,20 @@ date_initialize(int argc, VALUE *argv, VALUE self) * Date.commercial(2022, 1, 1).to_s # => "2022-01-03" * Date.commercial(2022, 1, -7).to_s # => "2022-01-03" * - * When +cweek+ is 1, the actual year in the new date - * may be different from +cwyear+; - * the actual year is: + * When +cweek+ is 1: * - * - +cwyear+, if January 1 of that year is a Friday, Saturday, - * Sunday, or Monday - * (that is, if the first Monday in calendar year +cwyear+ - * is on or before January 4): + * - If January 1 is a Friday, Saturday, Sunday, or Monday, + * the first week begins in the year +cwyear+: * - * [2010, 2000, 2006, 2001].each do |year| - * wday = Date::ABBR_DAYNAMES[Date.new(year, 1, 1).wday] - * cdate = Date.commercial(year) - * p [year, wday, cdate.to_s] - * end + * # January 1 is a Monday. + * Date.commercial(2001, 1, 1).to_s # => "2001-01-01" + * Date.commercial(2001, 1, 7).to_s # => "2001-01-07" * - * Output: + * - Otherwise, the first begins in the year cwyear + 1: * - * [2010, "Fri", "2010-01-04"] - * [2000, "Sat", "2000-01-03"] - * [2006, "Sun", "2006-01-02"] - * [2001, "Mon", "2001-01-01"] - * - * - cwyear - 1, otherwise: - * - * [2002, 2003, 2004].each do |year| - * wday = Date::ABBR_DAYNAMES[Date.new(year, 1, 1).wday] - * cdate = Date.commercial(year) - * p [year, wday, cdate.to_s] - * end - * - * Output: - * - * [2002, "Tue", "2001-12-31"] - * [2003, "Wed", "2002-12-30"] - * [2004, "Thu", "2003-12-29"] + * # January 1 is a Thursday. + * Date.commercial(2004, 1, 1).to_s # => "2003-12-29" + * Date.commercial(2004, 1, 7).to_s # => "2004-01-04" * * See {Argument start}[rdoc-ref:Date@Argument+start]. * From ee7d43cd0575d26a7565271baed9dc843574ee56 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 6 Jul 2022 10:18:35 -0500 Subject: [PATCH 4/4] Enhanced RDoc --- ext/date/date_core.c | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/ext/date/date_core.c b/ext/date/date_core.c index c668097..dc0f001 100644 --- a/ext/date/date_core.c +++ b/ext/date/date_core.c @@ -3553,18 +3553,19 @@ date_initialize(int argc, VALUE *argv, VALUE self) * * When +cweek+ is 1: * - * - If January 1 is a Friday, Saturday, Sunday, or Monday, - * the first week begins in the year +cwyear+: + * - If January 1 is a Friday, Saturday, or Sunday, + * the first week begins in the week after: * - * # January 1 is a Monday. - * Date.commercial(2001, 1, 1).to_s # => "2001-01-01" - * Date.commercial(2001, 1, 7).to_s # => "2001-01-07" + * Date::ABBR_DAYNAMES[Date.new(2023, 1, 1).wday] # => "Sun" + * Date.commercial(2023, 1, 1).to_s # => "2023-01-02" + Date.commercial(2023, 1, 7).to_s # => "2023-01-08" * - * - Otherwise, the first begins in the year cwyear + 1: + * - Otherwise, the first week is the week of January 1, + * which may mean some of the days fall on the year before: * - * # January 1 is a Thursday. - * Date.commercial(2004, 1, 1).to_s # => "2003-12-29" - * Date.commercial(2004, 1, 7).to_s # => "2004-01-04" + * Date::ABBR_DAYNAMES[Date.new(2020, 1, 1).wday] # => "Wed" + * 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]. *