From d8ea3a20fa7db0a670cde9c90d62fc5187217a23 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Tue, 2 Aug 2022 12:28:03 -0500 Subject: [PATCH] [ruby/date] [DOC] Enhanced RDoc for parser methods (https://github.com/ruby/date/pull/68) Treats: ::_httpdate ::_iso8601 ::_jisx0301 ::_parse ::_rfc2822 ::_rfc3339 ::_xmlschema ::httpdate ::iso8601 ::jisx0301 ::parse ::rfc2822 ::rfc3339 ::xmlschema https://github.com/ruby/date/commit/24bdab600a --- ext/date/date_core.c | 228 ++++++++++++++++++++++++------------------- 1 file changed, 130 insertions(+), 98 deletions(-) diff --git a/ext/date/date_core.c b/ext/date/date_core.c index 762fb7281c..9fd0f52b48 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,31 @@ 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('20010203') # => # + * Date.parse('3rd Feb 2001') # => # * - * 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 {start}[rdoc-ref:Date@Argument+start]. + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * - * See argument {start}[rdoc-ref:Date@Argument+start]. */ static VALUE date_s_parse(int argc, VALUE *argv, VALUE klass) @@ -4582,11 +4589,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 +4613,19 @@ 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: + * + * - Argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * - * See argument {start}[rdoc-ref:Date@Argument+start]. */ static VALUE date_s_iso8601(int argc, VALUE *argv, VALUE klass) @@ -4645,11 +4656,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 +4681,19 @@ 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: + * + * - Argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * - * See argument {start}[rdoc-ref:Date@Argument+start]. */ static VALUE date_s_rfc3339(int argc, VALUE *argv, VALUE klass) @@ -4706,11 +4724,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,16 +4748,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. + * Returns a new \Date object with values parsed from +string+, + * which should be a valid XML date format: * - * Date.xmlschema('2001-02-03') #=> # + * d = Date.new(2001, 2, 3) + * s = d.xmlschema # => "2001-02-03" + * Date.xmlschema(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 {start}[rdoc-ref:Date@Argument+start]. + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * */ static VALUE @@ -4768,11 +4790,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 +4817,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 {start}[rdoc-ref:Date@Argument+start]. + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * * Date.rfc822 is an alias for Date.rfc2822. */ @@ -4833,14 +4860,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,17 +4884,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. + * 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]: * - * Date.httpdate('Sat, 03 Feb 2001 00:00:00 GMT') - * #=> # + * d = Date.new(2001, 2, 3) + s = d.httpdate # => "Sat, 03 Feb 2001 00:00:00 GMT" + Date.httpdate(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 {start}[rdoc-ref:Date@Argument+start]. + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * */ static VALUE @@ -4898,11 +4926,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,20 +4950,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: * - * See argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {start}[rdoc-ref:Date@Argument+start]. + * - Argument {limit}[rdoc-ref:Date@Argument+limit]. * */ static VALUE