From 90872b064b6287791c93568819ffa61afa37f105 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sun, 31 Jul 2022 09:39:18 -0500 Subject: [PATCH 1/3] Enhanced RDoc for parser methods --- ext/date/date_core.c | 227 ++++++++++++++++++++++++------------------- 1 file changed, 126 insertions(+), 101 deletions(-) diff --git a/ext/date/date_core.c b/ext/date/date_core.c index 762fb72..d345e2e 100644 --- a/ext/date/date_core.c +++ b/ext/date/date_core.c @@ -4493,23 +4493,26 @@ date_s__parse_internal(int argc, VALUE *argv, VALUE klass) * call-seq: * Date._parse(string, comp = true, limit: 128) -> hash * - * Parses the given representation of date and time, and returns a - * hash of parsed elements. + * Note: + * This method recognizes many forms in +string+, + * but it is not a validator. + * If +string+ does not specify a valid date, + * the result is unpredictable; + * consider using Date._strptime instead. * - * This method *does* *not* function as a validator. If the input - * string does not match valid formats strictly, you may get a cryptic - * result. Should consider to use Date._strptime or DateTime._strptime - * instead of this method as possible. + * Returns a hash of values parsed from +string+: * - * If the optional second argument is true and the detected year is in - * the range "00" to "99", considers the year a 2-digit form and makes - * it full. + * Date._parse('2001-02-03') # => {:year=>2001, :mon=>2, :mday=>3} * - * Date._parse('2001-02-03') #=> {:year=>2001, :mon=>2, :mday=>3} + * If +comp+ is +true+ and the given year is in the range (0..99), + * the current century is supplied; + * otherwise, the year is taken as given: + * + * Date._parse('01-02-03', true) # => {:year=>2001, :mon=>2, :mday=>3} + * Date._parse('01-02-03', false) # => {:year=>1, :mon=>2, :mday=>3} + * + * See argument {limit}[rdoc-ref:Date@Argument+limit]. * - * Raise an ArgumentError when the string length is longer than _limit_. - * You can stop this check by passing limit: nil, but note - * that it may take a long time to parse. */ static VALUE date_s__parse(int argc, VALUE *argv, VALUE klass) @@ -4521,27 +4524,29 @@ date_s__parse(int argc, VALUE *argv, VALUE klass) * call-seq: * Date.parse(string = '-4712-01-01', comp = true, start = Date::ITALY, limit: 128) -> date * - * Parses the given representation of date and time, and creates a - * date object. + * Note: + * This method recognizes many forms in +string+, + * but it is not a validator. + * If +string+ does not specify a valid date, + * the result is unpredictable; + * consider using Date._strptime instead. * - * This method *does* *not* function as a validator. If the input - * string does not match valid formats strictly, you may get a cryptic - * result. Should consider to use Date.strptime instead of this method - * as possible. + * Returns a new \Date object with values parsed from +string+: * - * If the optional second argument is true and the detected year is in - * the range "00" to "99", considers the year a 2-digit form and makes - * it full. + * Date.parse('2001-02-03') # => # * - * Date.parse('2001-02-03') #=> # - * Date.parse('20010203') #=> # - * Date.parse('3rd Feb 2001') #=> # + * If +comp+ is +true+ and the given year is in the range (0..99), + * the current century is supplied; + * otherwise, the year is taken as given: * - * Raise an ArgumentError when the string length is longer than _limit_. - * You can stop this check by passing limit: nil, but note - * that it may take a long time to parse. + * Date.parse('01-02-03', true) # => # + * Date.parse('01-02-03', false) # => # + * + * See: + * + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. + * - Argument {start}[rdoc-ref:Date@Argument+start]. * - * See argument {start}[rdoc-ref:Date@Argument+start]. */ static VALUE date_s_parse(int argc, VALUE *argv, VALUE klass) @@ -4582,11 +4587,14 @@ VALUE date__jisx0301(VALUE); * call-seq: * Date._iso8601(string, limit: 128) -> hash * - * Returns a hash of parsed elements. + * Returns a hash of values parsed from +string+, which should contain + * an {ISO 8601 formatted date}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html#label-ISO+8601+Format+Specifications]: * - * Raise an ArgumentError when the string length is longer than _limit_. - * You can stop this check by passing limit: nil, but note - * that it may take a long time to parse. + * d = Date.new(2001, 2, 3) + * s = d.iso8601 # => "2001-02-03" + * Date._iso8601(s) # => {:mday=>3, :year=>2001, :mon=>2} + * + * See argument {limit}[rdoc-ref:Date@Argument+limit]. */ static VALUE date_s__iso8601(int argc, VALUE *argv, VALUE klass) @@ -4603,18 +4611,18 @@ date_s__iso8601(int argc, VALUE *argv, VALUE klass) * call-seq: * Date.iso8601(string = '-4712-01-01', start = Date::ITALY, limit: 128) -> date * - * Creates a new Date object by parsing from a string according to - * some typical ISO 8601 formats. + * Returns a new \Date object with values parsed from +string+, + * which should contain + * an {ISO 8601 formatted date}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html#label-ISO+8601+Format+Specifications]: * - * Date.iso8601('2001-02-03') #=> # - * Date.iso8601('20010203') #=> # - * Date.iso8601('2001-W05-6') #=> # + * d = Date.new(2001, 2, 3) + * s = d.iso8601 # => "2001-02-03" + * Date.iso8601(s) # => # * - * Raise an ArgumentError when the string length is longer than _limit_. - * You can stop this check by passing limit: nil, but note - * that it may take a long time to parse. + * See: * - * See argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. + * - Argument {start}[rdoc-ref:Date@Argument+start]. */ static VALUE date_s_iso8601(int argc, VALUE *argv, VALUE klass) @@ -4645,11 +4653,15 @@ date_s_iso8601(int argc, VALUE *argv, VALUE klass) * call-seq: * Date._rfc3339(string, limit: 128) -> hash * - * Returns a hash of parsed elements. + * Returns a hash of values parsed from +string+, which should be a valid + * {RFC 3339 format}[https://datatracker.ietf.org/doc/html/rfc3339]: * - * Raise an ArgumentError when the string length is longer than _limit_. - * You can stop this check by passing limit: nil, but note - * that it may take a long time to parse. + * d = Date.new(2001, 2, 3) + * s = d.rfc3339 # => "2001-02-03T00:00:00+00:00" + * Date._rfc3339(s) + * # => {:year=>2001, :mon=>2, :mday=>3, :hour=>0, :min=>0, :sec=>0, :zone=>"+00:00", :offset=>0} + * + * See argument {limit}[rdoc-ref:Date@Argument+limit]. */ static VALUE date_s__rfc3339(int argc, VALUE *argv, VALUE klass) @@ -4666,16 +4678,18 @@ date_s__rfc3339(int argc, VALUE *argv, VALUE klass) * call-seq: * Date.rfc3339(string = '-4712-01-01T00:00:00+00:00', start = Date::ITALY, limit: 128) -> date * - * Creates a new Date object by parsing from a string according to - * some typical RFC 3339 formats. + * Returns a new \Date object with values parsed from +string+, + * which should be a valid + * {RFC 3339 format}[https://datatracker.ietf.org/doc/html/rfc3339]: * - * Date.rfc3339('2001-02-03T04:05:06+07:00') #=> # + * d = Date.new(2001, 2, 3) + * s = d.rfc3339 # => "2001-02-03T00:00:00+00:00" + * Date.rfc3339(s) # => # * - * Raise an ArgumentError when the string length is longer than _limit_. - * You can stop this check by passing limit: nil, but note - * that it may take a long time to parse. + * See: * - * See argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. + * - Argument {start}[rdoc-ref:Date@Argument+start]. */ static VALUE date_s_rfc3339(int argc, VALUE *argv, VALUE klass) @@ -4706,11 +4720,14 @@ date_s_rfc3339(int argc, VALUE *argv, VALUE klass) * call-seq: * Date._xmlschema(string, limit: 128) -> hash * - * Returns a hash of parsed elements. + * Returns a hash of values parsed from +string+, which should be a valid + * XML date format: * - * Raise an ArgumentError when the string length is longer than _limit_. - * You can stop this check by passing limit: nil, but note - * that it may take a long time to parse. + * d = Date.new(2001, 2, 3) + * s = d.xmlschema # => "2001-02-03" + * Date._xmlschema(s) # => {:year=>2001, :mon=>2, :mday=>3} + * + * See argument {limit}[rdoc-ref:Date@Argument+limit]. */ static VALUE date_s__xmlschema(int argc, VALUE *argv, VALUE klass) @@ -4727,17 +4744,17 @@ date_s__xmlschema(int argc, VALUE *argv, VALUE klass) * call-seq: * Date.xmlschema(string = '-4712-01-01', start = Date::ITALY, limit: 128) -> date * - * Creates a new Date object by parsing from a string according to - * some typical XML Schema formats. - * - * Date.xmlschema('2001-02-03') #=> # + * Returns a new \Date object with values parsed from +string+, + * which should be a valid XML date format: * - * Raise an ArgumentError when the string length is longer than _limit_. - * You can stop this check by passing limit: nil, but note - * that it may take a long time to parse. + * d = Date.new(2001, 2, 3) + * s = d.xmlschema # => "2001-02-03" + * Date.xmlschema(s) # => # * - * See argument {start}[rdoc-ref:Date@Argument+start]. + * See: * + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. + * - Argument {start}[rdoc-ref:Date@Argument+start]. */ static VALUE date_s_xmlschema(int argc, VALUE *argv, VALUE klass) @@ -4768,11 +4785,15 @@ date_s_xmlschema(int argc, VALUE *argv, VALUE klass) * call-seq: * Date._rfc2822(string, limit: 128) -> hash * - * Returns a hash of parsed elements. + * Returns a hash of values parsed from +string+, which should be a valid + * {RFC 2822 date format:}[https://datatracker.ietf.org/doc/html/rfc2822]: * - * Raise an ArgumentError when the string length is longer than _limit_. - * You can stop this check by passing limit: nil, but note - * that it may take a long time to parse. + * d = Date.new(2001, 2, 3) + * s = d.rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000" + * Date._rfc2822(s) + * # => {:wday=>6, :mday=>3, :mon=>2, :year=>2001, :hour=>0, :min=>0, :sec=>0, :zone=>"+0000", :offset=>0} + * + * See argument {limit}[rdoc-ref:Date@Argument+limit]. * * Date._rfc822 is an alias for Date._rfc2822. */ @@ -4791,17 +4812,18 @@ date_s__rfc2822(int argc, VALUE *argv, VALUE klass) * call-seq: * Date.rfc2822(string = 'Mon, 1 Jan -4712 00:00:00 +0000', start = Date::ITALY, limit: 128) -> date * - * Creates a new Date object by parsing from a string according to - * some typical RFC 2822 formats. + * Returns a new \Date object with values parsed from +string+, + * which should be a valid + * {RFC 2822 date format:}[https://datatracker.ietf.org/doc/html/rfc2822]: * - * Date.rfc2822('Sat, 3 Feb 2001 00:00:00 +0000') - * #=> # + * d = Date.new(2001, 2, 3) + * s = d.rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000" + * Date.rfc2822(s) # => # * - * Raise an ArgumentError when the string length is longer than _limit_. - * You can stop this check by passing limit: nil, but note - * that it may take a long time to parse. + * See: * - * See argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. + * - Argument {start}[rdoc-ref:Date@Argument+start]. * * Date.rfc822 is an alias for Date.rfc2822. */ @@ -4833,14 +4855,14 @@ date_s_rfc2822(int argc, VALUE *argv, VALUE klass) * call-seq: * Date._httpdate(string, limit: 128) -> hash * - * Returns a hash of values parsed from +string+: + * Returns a hash of values parsed from +string+, which should be a valid + * HTTP date format: * * d = Date.new(2001, 2, 3) * s = d.httpdate # => "Sat, 03 Feb 2001 00:00:00 GMT" * Date._httpdate(s) * # => {:wday=>6, :mday=>3, :mon=>2, :year=>2001, :hour=>0, :min=>0, :sec=>0, :zone=>"GMT", :offset=>0} * - * See argument {limit}[rdoc-ref:Date@Argument+limit]. */ static VALUE date_s__httpdate(int argc, VALUE *argv, VALUE klass) @@ -4857,18 +4879,18 @@ date_s__httpdate(int argc, VALUE *argv, VALUE klass) * call-seq: * Date.httpdate(string = 'Mon, 01 Jan -4712 00:00:00 GMT', start = Date::ITALY, limit: 128) -> date * - * Creates a new Date object by parsing from a string according to - * some RFC 2616 format. - * - * Date.httpdate('Sat, 03 Feb 2001 00:00:00 GMT') - * #=> # + * Returns a new \Date object with values parsed from +string+, + * which should be a valid + * {RFC 2616 date format:}[https://datatracker.ietf.org/doc/html/rfc2616]: * - * Raise an ArgumentError when the string length is longer than _limit_. - * You can stop this check by passing limit: nil, but note - * that it may take a long time to parse. + * d = Date.new(2001, 2, 3) + s = d.httpdate # => "Sat, 03 Feb 2001 00:00:00 GMT" + Date.httpdate(s) # => # * - * See argument {start}[rdoc-ref:Date@Argument+start]. + * See: * + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. + * - Argument {start}[rdoc-ref:Date@Argument+start]. */ static VALUE date_s_httpdate(int argc, VALUE *argv, VALUE klass) @@ -4898,11 +4920,14 @@ date_s_httpdate(int argc, VALUE *argv, VALUE klass) * call-seq: * Date._jisx0301(string, limit: 128) -> hash * - * Returns a hash of parsed elements. + * Returns a hash of values parsed from +string+, which should be a valid + * JIS X 0301 date format: * - * Raise an ArgumentError when the string length is longer than _limit_. - * You can stop this check by passing limit: nil, but note - * that it may take a long time to parse. + * d = Date.new(2001, 2, 3) + * s = d.jisx0301 # => "H13.02.03" + * Date._jisx0301(s) # => {:year=>2001, :mon=>2, :mday=>3} + * + * See argument {limit}[rdoc-ref:Date@Argument+limit]. */ static VALUE date_s__jisx0301(int argc, VALUE *argv, VALUE klass) @@ -4919,21 +4944,21 @@ date_s__jisx0301(int argc, VALUE *argv, VALUE klass) * call-seq: * Date.jisx0301(string = '-4712-01-01', start = Date::ITALY, limit: 128) -> date * - * Creates a new Date object by parsing from a string according to - * some typical JIS X 0301 formats. + * Returns a new \Date object with values parsed from +string+, + * which should be a valid JIS X 0301 format: * - * Date.jisx0301('H13.02.03') #=> # + * d = Date.new(2001, 2, 3) + * s = d.jisx0301 # => "H13.02.03" + * Date.jisx0301(s) # => # * * For no-era year, legacy format, Heisei is assumed. * - * Date.jisx0301('13.02.03') #=> # + * Date.jisx0301('13.02.03') # => # * - * Raise an ArgumentError when the string length is longer than _limit_. - * You can stop this check by passing limit: nil, but note - * that it may take a long time to parse. - * - * See argument {start}[rdoc-ref:Date@Argument+start]. + * See: * + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. + * - Argument {start}[rdoc-ref:Date@Argument+start]. */ static VALUE date_s_jisx0301(int argc, VALUE *argv, VALUE klass) From 893b963766c0dd29a81b7071953d07f19a11de27 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Mon, 1 Aug 2022 08:29:10 -0500 Subject: [PATCH 2/3] Enhanced RDoc for parser methods --- ext/date/date_core.c | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/ext/date/date_core.c b/ext/date/date_core.c index d345e2e..62ffa93 100644 --- a/ext/date/date_core.c +++ b/ext/date/date_core.c @@ -4533,7 +4533,9 @@ date_s__parse(int argc, VALUE *argv, VALUE klass) * * Returns a new \Date object with values parsed from +string+: * - * Date.parse('2001-02-03') # => # + * Date.parse('2001-02-03') # => # + * Date.parse('20010203') # => # + * Date.parse('3rd Feb 2001') # => # * * If +comp+ is +true+ and the given year is in the range (0..99), * the current century is supplied; @@ -4544,8 +4546,8 @@ date_s__parse(int argc, VALUE *argv, VALUE klass) * * See: * - * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * - Argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * */ static VALUE @@ -4621,8 +4623,9 @@ date_s__iso8601(int argc, VALUE *argv, VALUE klass) * * See: * - * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * - Argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. + * */ static VALUE date_s_iso8601(int argc, VALUE *argv, VALUE klass) @@ -4688,8 +4691,9 @@ date_s__rfc3339(int argc, VALUE *argv, VALUE klass) * * See: * - * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * - Argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. + * */ static VALUE date_s_rfc3339(int argc, VALUE *argv, VALUE klass) @@ -4753,8 +4757,9 @@ date_s__xmlschema(int argc, VALUE *argv, VALUE klass) * * See: * - * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * - Argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. + * */ static VALUE date_s_xmlschema(int argc, VALUE *argv, VALUE klass) @@ -4786,7 +4791,7 @@ date_s_xmlschema(int argc, VALUE *argv, VALUE klass) * Date._rfc2822(string, limit: 128) -> hash * * Returns a hash of values parsed from +string+, which should be a valid - * {RFC 2822 date format:}[https://datatracker.ietf.org/doc/html/rfc2822]: + * {RFC 2822 date format}[https://datatracker.ietf.org/doc/html/rfc2822]: * * d = Date.new(2001, 2, 3) * s = d.rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000" @@ -4814,7 +4819,7 @@ date_s__rfc2822(int argc, VALUE *argv, VALUE klass) * * Returns a new \Date object with values parsed from +string+, * which should be a valid - * {RFC 2822 date format:}[https://datatracker.ietf.org/doc/html/rfc2822]: + * {RFC 2822 date format}[https://datatracker.ietf.org/doc/html/rfc2822]: * * d = Date.new(2001, 2, 3) * s = d.rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000" @@ -4822,8 +4827,8 @@ date_s__rfc2822(int argc, VALUE *argv, VALUE klass) * * See: * - * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * - Argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * * Date.rfc822 is an alias for Date.rfc2822. */ @@ -4881,7 +4886,7 @@ date_s__httpdate(int argc, VALUE *argv, VALUE klass) * * Returns a new \Date object with values parsed from +string+, * which should be a valid - * {RFC 2616 date format:}[https://datatracker.ietf.org/doc/html/rfc2616]: + * {RFC 2616 date format}[https://datatracker.ietf.org/doc/html/rfc2616]: * * d = Date.new(2001, 2, 3) s = d.httpdate # => "Sat, 03 Feb 2001 00:00:00 GMT" @@ -4889,8 +4894,9 @@ date_s__httpdate(int argc, VALUE *argv, VALUE klass) * * See: * - * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * - Argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. + * */ static VALUE date_s_httpdate(int argc, VALUE *argv, VALUE klass) @@ -4957,8 +4963,9 @@ date_s__jisx0301(int argc, VALUE *argv, VALUE klass) * * See: * - * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * - Argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. + * */ static VALUE date_s_jisx0301(int argc, VALUE *argv, VALUE klass) From 2972e6006a7fb5fc3736736c7cd05557ff41add7 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Tue, 2 Aug 2022 09:10:55 -0500 Subject: [PATCH 3/3] Update ext/date/date_core.c Co-authored-by: Peter Zhu --- ext/date/date_core.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ext/date/date_core.c b/ext/date/date_core.c index 62ffa93..9fd0f52 100644 --- a/ext/date/date_core.c +++ b/ext/date/date_core.c @@ -4534,8 +4534,8 @@ date_s__parse(int argc, VALUE *argv, VALUE klass) * Returns a new \Date object with values parsed from +string+: * * Date.parse('2001-02-03') # => # - * Date.parse('20010203') # => # - * Date.parse('3rd Feb 2001') # => # + * Date.parse('20010203') # => # + * Date.parse('3rd Feb 2001') # => # * * If +comp+ is +true+ and the given year is in the range (0..99), * the current century is supplied;