[前][次][番号順一覧][スレッド一覧]

ruby-changes:72933

From: Burdette <ko1@a...>
Date: Mon, 15 Aug 2022 22:16:35 +0900 (JST)
Subject: [ruby-changes:72933] 8d40ede2e0 (master): [ruby/date] [DOC] Enhanced intro for Date (https://github.com/ruby/date/pull/72)

https://git.ruby-lang.org/ruby.git/commit/?id=8d40ede2e0

From 8d40ede2e005439cbc84abfd50c98932a33448f4 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Y...>
Date: Mon, 15 Aug 2022 08:16:13 -0500
Subject: [ruby/date] [DOC] Enhanced intro for Date
 (https://github.com/ruby/date/pull/72)

https://github.com/ruby/date/commit/59a6673221
---
 ext/date/date_core.c | 184 ++++++++++++++-------------------------------------
 1 file changed, 51 insertions(+), 133 deletions(-)

diff --git a/ext/date/date_core.c b/ext/date/date_core.c
index c68f70e5f8..83d493c794 100644
--- a/ext/date/date_core.c
+++ b/ext/date/date_core.c
@@ -4505,6 +4505,9 @@ date_s__parse_internal(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4505
  * <b>Note</b>:
  * This method recognizes many forms in +string+,
  * but it is not a validator.
+ * For formats, see
+ * {"Specialized Format Strings" in Formats for Dates and Times}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html#label-Specialized+Format+Strings]
+ *
  * If +string+ does not specify a valid date,
  * the result is unpredictable;
  * consider using Date._strptime instead.
@@ -4537,6 +4540,8 @@ date_s__parse(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4540
  * <b>Note</b>:
  * This method recognizes many forms in +string+,
  * but it is not a validator.
+ * For formats, see
+ * {"Specialized Format Strings" in Formats for Dates and Times}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html#label-Specialized+Format+Strings]
  * If +string+ does not specify a valid date,
  * the result is unpredictable;
  * consider using Date._strptime instead.
@@ -4671,7 +4676,7 @@ date_s_iso8601(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4676
  *   Date._rfc3339(string, limit: 128) -> hash
  *
  * Returns a hash of values parsed from +string+, which should be a valid
- * {RFC 3339 format}[https://datatracker.ietf.org/doc/html/rfc3339]:
+ * {RFC 3339 format}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html#label-RFC+3339+Format]:
  *
  *   d = Date.new(2001, 2, 3)
  *   s = d.rfc3339     # => "2001-02-03T00:00:00+00:00"
@@ -4699,7 +4704,7 @@ date_s__rfc3339(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4704
  *
  * 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]:
+ * {RFC 3339 format}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html#label-RFC+3339+Format]:
  *
  *   d = Date.new(2001, 2, 3)
  *   s = d.rfc3339   # => "2001-02-03T00:00:00+00:00"
@@ -4811,7 +4816,7 @@ date_s_xmlschema(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4816
  *   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://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html#label-RFC+2822+Format]:
  *
  *   d = Date.new(2001, 2, 3)
  *   s = d.rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000"
@@ -4841,7 +4846,7 @@ date_s__rfc2822(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4846
  *
  * 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://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html#label-RFC+2822+Format]:
  *
  *   d = Date.new(2001, 2, 3)
  *   s = d.rfc2822   # => "Sat, 3 Feb 2001 00:00:00 +0000"
@@ -4885,7 +4890,7 @@ date_s_rfc2822(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4890
  *   Date._httpdate(string, limit: 128) -> hash
  *
  * Returns a hash of values parsed from +string+, which should be a valid
- * HTTP date format:
+ * {HTTP date format}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html#label-HTTP+Format]:
  *
  *   d = Date.new(2001, 2, 3)
  *   s = d.httpdate # => "Sat, 03 Feb 2001 00:00:00 GMT"
@@ -4911,7 +4916,7 @@ date_s__httpdate(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4916
  *
  * 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]:
+ * {HTTP date format}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html#label-HTTP+Format]:
  *
  *   d = Date.new(2001, 2, 3)
      s = d.httpdate   # => "Sat, 03 Feb 2001 00:00:00 GMT"
@@ -4953,7 +4958,7 @@ date_s_httpdate(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4958
  *   Date._jisx0301(string, limit: 128) -> hash
  *
  * Returns a hash of values parsed from +string+, which should be a valid
- * JIS X 0301 date format:
+ * {JIS X 0301 date format}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html#label-JIS+X+0301+Format]:
  *
  *   d = Date.new(2001, 2, 3)
  *   s = d.jisx0301    # => "H13.02.03"
@@ -4979,7 +4984,7 @@ date_s__jisx0301(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4984
  *   Date.jisx0301(string = '-4712-01-01', start = Date::ITALY, limit: 128) -> date
  *
  * Returns a new \Date object with values parsed from +string+,
- * which should be a valid JIS X 0301 format:
+ * which should be a valid {JIS X 0301 format}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html#label-JIS+X+0301+Format]:
  *
  *   d = Date.new(2001, 2, 3)
  *   s = d.jisx0301   # => "H13.02.03"
@@ -9383,151 +9388,65 @@ Init_date_core(void) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L9388
     negative_inf = -INFINITY;
 
     /*
-     * date and datetime class - Tadayoshi Funaba 1998-2011
-     *
-     * 'date' provides two classes: Date and DateTime.
-     *
-     * == Terms and Definitions
-     *
-     * Some terms and definitions are based on ISO 8601 and JIS X 0301.
-     *
-     * === Calendar Date
-     *
-     * The calendar date is a particular day of a calendar year,
-     * identified by its ordinal number within a calendar month within
-     * that year.
+     * \Class \Date provides methods for storing and manipulating
+     * calendar dates.
      *
-     * In those classes, this is so-called "civil".
+     * Consider using
+     * {class Time}[https://docs.ruby-lang.org/en/master/Time.html]
+     * instead of class \Date if:
      *
-     * === Ordinal Date
+     * - You need both dates and times; \Date handles only dates.
+     * - You need only Gregorian dates (and not Julian dates);
+     *   see {Julian and Gregorian Calendars}[rdoc-ref:calendars.rdoc].
      *
-     * The ordinal date is a particular day of a calendar year identified
-     * by its ordinal number within the year.
+     * A \Date object, once created, is immutable, and cannot be modified.
      *
-     * In those classes, this is so-called "ordinal".
+     * == Creating a \Date
      *
-     * === Week Date
+     * You can create a date for the current date, using Date.today:
      *
-     * The week date is a date identified by calendar week and day numbers.
+     *   Date.today # => #<Date: 1999-12-31>
      *
-     * The calendar week is a seven day period within a calendar year,
-     * starting on a Monday and identified by its ordinal number within
-     * the year; the first calendar week of the year is the one that
-     * includes the first Thursday of that year. In the Gregorian
-     * calendar, this is equivalent to the week which includes January 4.
+     * You can create a specific date from various combinations of arguments:
      *
-     * In those classes, this is so-called "commercial".
+     * - Date.new takes integer year, month, and day-of-month:
      *
-     * === Julian Day Number
+     *     Date.new(1999, 12, 31) # => #<Date: 1999-12-31>
      *
-     * The Julian day number is in elapsed days since noon (Greenwich Mean
-     * Time) on January 1, 4713 BCE (in the Julian calendar).
+     * - Date.ordinal takes integer year and day-of-year:
      *
-     * In this document, the astronomical Julian day number is the same as
-     * the original Julian day number. And the chronological Julian day
-     * number is a variation of the Julian day number. Its days begin at
-     * midnight on local time.
+     *     Date.ordinal(1999, 365) # => #<Date: 1999-12-31>
      *
-     * In this document, when the term "Julian day number" simply appears,
-     * it just refers to "chronological Julian day number", not the
-     * original.
+     * - Date.jd takes integer Julian day:
      *
-     * In those classes, those are so-called "ajd" and "jd".
+     *     Date.jd(2451544) # => #<Date: 1999-12-31>
      *
-     * === Modified Julian Day Number
+     * - Date.commercial takes integer commercial data (year, week, day-of-week):
      *
-     * The modified Julian day number is in elapsed days since midnight
-     * (Coordinated Universal Time) on November 17, 1858 CE (in the
-     * Gregorian calendar).
+     *     Date.commercial(1999, 52, 5) # => #<Date: 1999-12-31>
      *
-     * In this document, the astronomical modified Julian day number is
-     * the same as the original modified Julian day number. And the
-     * chronological modified Julian day number is a variation of the
-     * modified Julian day number. Its days begin at midnight on local
-     * time.
+     * - Date.parse takes a string, which it parses heuristically:
      *
-     * In this document, when the term "modified Julian day number" simply
-     * appears, it just refers to "chronological modified Julian day
-     * number", not  (... truncated)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/

[前][次][番号順一覧][スレッド一覧]