ruby-changes:66021
From: Burdette <ko1@a...>
Date: Fri, 30 Apr 2021 12:03:16 +0900 (JST)
Subject: [ruby-changes:66021] 6ee55455a8 (master): Update Time documentation
https://git.ruby-lang.org/ruby.git/commit/?id=6ee55455a8 From 6ee55455a88d0f3542497b429d496abaf01fd353 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Sun, 25 Apr 2021 15:51:31 -0500 Subject: Update Time documentation --- doc/time/in.rdoc | 7 ++ doc/time/mon-min.rdoc | 8 ++ doc/time/msec.rdoc | 2 + doc/time/nsec.rdoc | 2 + doc/time/sec.rdoc | 2 + doc/time/sec_i.rdoc | 1 + doc/time/usec.rdoc | 2 + doc/time/year.rdoc | 1 + time.c | 220 ++++++++++++++++++++++++++++++++++++-------------- timev.rb | 138 +++++++++++++------------------ 10 files changed, 237 insertions(+), 146 deletions(-) create mode 100644 doc/time/in.rdoc create mode 100644 doc/time/mon-min.rdoc create mode 100644 doc/time/msec.rdoc create mode 100644 doc/time/nsec.rdoc create mode 100644 doc/time/sec.rdoc create mode 100644 doc/time/sec_i.rdoc create mode 100644 doc/time/usec.rdoc create mode 100644 doc/time/year.rdoc diff --git a/doc/time/in.rdoc b/doc/time/in.rdoc new file mode 100644 index 0000000..f47db76 --- /dev/null +++ b/doc/time/in.rdoc @@ -0,0 +1,7 @@ https://github.com/ruby/ruby/blob/trunk/doc/time/in.rdoc#L1 +- <tt>in: zone</tt>: a timezone _zone_, which may be: + - A string offset from UTC. + - A single letter offset from UTC, in the range <tt>'A'..'Z'</tt>, + <tt>'J'</tt> (the so-called military timezone) excluded. + - An integer number of seconds. + - A timezone object; + see {Timezone Argument}[#class-Time-label-Timezone+Argument] for details. diff --git a/doc/time/mon-min.rdoc b/doc/time/mon-min.rdoc new file mode 100644 index 0000000..5bd430c --- /dev/null +++ b/doc/time/mon-min.rdoc @@ -0,0 +1,8 @@ https://github.com/ruby/ruby/blob/trunk/doc/time/mon-min.rdoc#L1 +- +month+: a month value, which may be: + - An integer month in the range <tt>1..12</tt>. + - A 3-character string that matches regular expression + <tt>/jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec/i</tt>. +- +day+: an integer day in the range <tt>1..31</tt> + (less than 31 for some months). +- +hour+: an integer hour in the range <tt>0..23</tt>. +- +min+: an integer minute in the range <tt>0..59</tt>. diff --git a/doc/time/msec.rdoc b/doc/time/msec.rdoc new file mode 100644 index 0000000..ce5d1e6 --- /dev/null +++ b/doc/time/msec.rdoc @@ -0,0 +1,2 @@ https://github.com/ruby/ruby/blob/trunk/doc/time/msec.rdoc#L1 +- +msec+ is the number of milliseconds (Integer, Float, or Rational) + in the range <tt>0..1000</tt>. diff --git a/doc/time/nsec.rdoc b/doc/time/nsec.rdoc new file mode 100644 index 0000000..a2dfe2d --- /dev/null +++ b/doc/time/nsec.rdoc @@ -0,0 +1,2 @@ https://github.com/ruby/ruby/blob/trunk/doc/time/nsec.rdoc#L1 +- +nsec+ is the number of nanoseconds (Integer, Float, or Rational) + in the range <tt>0..1000000000</tt>. diff --git a/doc/time/sec.rdoc b/doc/time/sec.rdoc new file mode 100644 index 0000000..049c712 --- /dev/null +++ b/doc/time/sec.rdoc @@ -0,0 +1,2 @@ https://github.com/ruby/ruby/blob/trunk/doc/time/sec.rdoc#L1 +- +sec+ is the number of seconds (Integer, Float, or Rational) + in the range <tt>0..60</tt>. diff --git a/doc/time/sec_i.rdoc b/doc/time/sec_i.rdoc new file mode 100644 index 0000000..99c8edd --- /dev/null +++ b/doc/time/sec_i.rdoc @@ -0,0 +1 @@ +- +isec_i+ is the integer number of seconds in the range <tt>0..60</tt>. diff --git a/doc/time/usec.rdoc b/doc/time/usec.rdoc new file mode 100644 index 0000000..bb5a464 --- /dev/null +++ b/doc/time/usec.rdoc @@ -0,0 +1,2 @@ https://github.com/ruby/ruby/blob/trunk/doc/time/usec.rdoc#L1 +- +usec+ is the number of microseconds (Integer, Float, or Rational) + in the range <tt>0..1000000</tt>. diff --git a/doc/time/year.rdoc b/doc/time/year.rdoc new file mode 100644 index 0000000..2222b83 --- /dev/null +++ b/doc/time/year.rdoc @@ -0,0 +1 @@ +- +year+: an integer year. diff --git a/time.c b/time.c index e24bb5a..f23accf 100644 --- a/time.c +++ b/time.c @@ -3331,36 +3331,38 @@ tmcmp(struct tm *a, struct tm *b) https://github.com/ruby/ruby/blob/trunk/time.c#L3331 } /* - * call-seq: - * Time.utc(year) -> time - * Time.utc(year, month) -> time - * Time.utc(year, month, day) -> time - * Time.utc(year, month, day, hour) -> time - * Time.utc(year, month, day, hour, min) -> time - * Time.utc(year, month, day, hour, min, sec_with_frac) -> time - * Time.utc(year, month, day, hour, min, sec, usec_with_frac) -> time - * Time.utc(sec, min, hour, day, month, year, dummy, dummy, dummy, dummy) -> time - * Time.gm(year) -> time - * Time.gm(year, month) -> time - * Time.gm(year, month, day) -> time - * Time.gm(year, month, day, hour) -> time - * Time.gm(year, month, day, hour, min) -> time - * Time.gm(year, month, day, hour, min, sec_with_frac) -> time - * Time.gm(year, month, day, hour, min, sec, usec_with_frac) -> time - * Time.gm(sec, min, hour, day, month, year, dummy, dummy, dummy, dummy) -> time - * - * Creates a Time object based on given values, interpreted as UTC (GMT). The - * year must be specified. Other values default to the minimum value - * for that field (and may be +nil+ or omitted). Months may - * be specified by numbers from 1 to 12, or by the three-letter English - * month names. Hours are specified on a 24-hour clock (0..23). Raises - * an ArgumentError if any values are out of range. Will - * also accept ten arguments in the order output by Time#to_a. - * - * +sec_with_frac+ and +usec_with_frac+ can have a fractional part. - * - * Time.utc(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 UTC - * Time.gm(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 UTC + * call-seq: + * Time.utc(year, month=1, day=1, hour=0, min=0, sec_i=0, usec=0) -> new_time + * Time.utc(sec_i, min, hour, day, month, year, dummy, dummy, dummy, dummy) -> new_time + * + * Returns a new \Time object based the on given arguments; + * its timezone is UTC. + * + * In the first form (up to seven arguments), argument +year+ is required. + * + * Time.utc(2000) # => 2000-01-01 00:00:00 UTC + * Time.utc(0, 1, 2, 3, 4, 5, 6.5) # => 0000-01-02 03:04:05.0000065 UTC + * + * In the second form, all ten arguments are required, + * though the last four are ignored. + * This form is useful for creating a time from a 10-element array + * such as is returned by #to_a. + * + * array = Time.now.to_a + * p array # => [57, 26, 13, 24, 4, 2021, 6, 114, true, "Central Daylight Time"] + * array[5] = 2000 + * Time.utc(*array) # => 2000-04-24 13:26:57 UTC + * + * Parameters: + * :include: doc/time/year.rdoc + * :include: doc/time/mon-min.rdoc + * :include: doc/time/sec_i.rdoc + * :include: doc/time/usec.rdoc + * + * Alias: Time.gm. + + * Related: Time.local. + * */ static VALUE time_s_mkutc(int argc, VALUE *argv, VALUE klass) @@ -3372,28 +3374,37 @@ time_s_mkutc(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/time.c#L3374 } /* - * call-seq: - * Time.local(year) -> time - * Time.local(year, month) -> time - * Time.local(year, month, day) -> time - * Time.local(year, month, day, hour) -> time - * Time.local(year, month, day, hour, min) -> time - * Time.local(year, month, day, hour, min, sec_with_frac) -> time - * Time.local(year, month, day, hour, min, sec, usec_with_frac) -> time - * Time.local(sec, min, hour, day, month, year, dummy, dummy, isdst, dummy) -> time - * Time.mktime(year) -> time - * Time.mktime(year, month) -> time - * Time.mktime(year, month, day) -> time - * Time.mktime(year, month, day, hour) -> time - * Time.mktime(year, month, day, hour, min) -> time - * Time.mktime(year, month, day, hour, min, sec_with_frac) -> time - * Time.mktime(year, month, day, hour, min, sec, usec_with_frac) -> time - * Time.mktime(sec, min, hour, day, month, year, dummy, dummy, isdst, dummy) -> time - * - * Same as Time.utc, but interprets the values in the - * local time zone. - * - * Time.local(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 -0600 + * call-seq: + * Time.local(year, month=1, day=1, hour=0, min=0, sec_i=0, usec=0) -> new_time + * Time.local(sec, min, hour, day, month, year, dummy, dummy, dummy, dummy) -> new_time + * + * Returns a new \Time object based the on given arguments; + * its timezone is the local timezone. + * + * In the first form (up to seven arguments), argument +year+ is required. + * + * Time.local(2000) # => 2000-01-01 00:00:00 -0600 + * Time.local(0, 1, 2, 3, 4, 5, 6.5) # => 0000-01-02 03:04:05.0000065 -0600 + * + * In the second form, all ten arguments are required, + * though the last four are ignored. + * This form is useful for creating a time from a 10-element array + * such as those returned by #to_a. + * + * array = Time.now.to_a + * p array # => [57, 26, 13, 24, 4, 2021, 6, 114, true, "Central Daylight Time"] + * array[5] = 2000 + * Time.local(*array) # => 2000-04-24 13:26:57 -0500 + * + * Parameters: + * :include: doc/time/year.rdoc + * :include: doc/time/mon-min.rdoc + * :include: doc/time/sec_i.rdoc + * :include: doc/time/usec.rdoc + * + * Alias: Time.mktime. + * + * Related: Time.utc. */ static VALUE @@ -5378,7 +5389,7 @@ tm_from_time(VALUE klass, VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L5389 /* * call-seq: * - * Time::tm.new(year, month=nil, day=nil, hour=nil, min=nil, sec=nil, tz=nil) -> tm + * Time::tm.new(year, month=nil, day=nil, hour=nil, min=nil, sec=nil, zone=nil) -> tm * * Creates new Time::tm object. */ @@ -5590,17 +5601,19 @@ rb_time_zone_abbreviation(VALUE zone, VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L5601 * GMT is the older way of referring to these baseline times but persists in * the names of calls on POSIX systems. * + * Note: A \Time object uses the resolution available on your system clock. + * * All times may have subsecond. Be aware of this fact when comparing times * with each other -- times that are apparently equal when displayed (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/