ruby-changes:72794
From: Burdette <ko1@a...>
Date: Wed, 3 Aug 2022 02:28:28 +0900 (JST)
Subject: [ruby-changes:72794] d8ea3a20fa (master): [ruby/date] [DOC] Enhanced RDoc for parser methods (https://github.com/ruby/date/pull/68)
https://git.ruby-lang.org/ruby.git/commit/?id=d8ea3a20fa From d8ea3a20fa7db0a670cde9c90d62fc5187217a23 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Tue, 2 Aug 2022 12:28:03 -0500 Subject: [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) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4493 * 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. + * <b>Note</b>: + * 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 <tt>(0..99)</tt>, + * 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 <code>limit: nil</code>, 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) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4524 * 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. + * <b>Note</b>: + * 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: 2001-02-03> + * Date.parse('20010203') # => #<Date: 2001-02-03> + * Date.parse('3rd Feb 2001') # => #<Date: 2001-02-03> * - * Date.parse('2001-02-03') #=> #<Date: 2001-02-03 ...> - * Date.parse('20010203') #=> #<Date: 2001-02-03 ...> - * Date.parse('3rd Feb 2001') #=> #<Date: 2001-02-03 ...> + * If +comp+ is +true+ and the given year is in the range <tt>(0..99)</tt>, + * 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 <code>limit: nil</code>, but note - * that it may take a long time to parse. + * Date.parse('01-02-03', true) # => #<Date: 2001-02-03> + * Date.parse('01-02-03', false) # => #<Date: 0001-02-03> + * + * 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); https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4589 * 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 <code>limit: nil</code>, 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) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4613 * 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: 2001-02-03 ...> - * Date.iso8601('20010203') #=> #<Date: 2001-02-03 ...> - * Date.iso8601('2001-W05-6') #=> #<Date: 2001-02-03 ...> + * d = Date.new(2001, 2, 3) + * s = d.iso8601 # => "2001-02-03" + * Date.iso8601(s) # => #<Date: 2001-02-03> * - * Raise an ArgumentError when the string length is longer than _limit_. - * You can stop this check by passing <code>limit: nil</code>, 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) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4656 * 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 <code>limit: nil</code>, 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) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4681 * 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') #=> #<Date: 2001-02-03 ...> + * d = Date.new(2001, 2, 3) + * s = d.rfc3339 # => "2001-02-03T00:00:00+00:00" + * Date.rfc3339(s) # => #<Date: 2001-02-03> * - * Raise an ArgumentError when the string length is longer than _limit_. - * You can stop this check by passing <code>limit: nil</code>, 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) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4724 * 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 <code>limit: nil</code>, 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) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4748 (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/