ruby-changes:72519
From: Burdette <ko1@a...>
Date: Wed, 13 Jul 2022 03:21:46 +0900 (JST)
Subject: [ruby-changes:72519] 8309b1366c (master): [DOC] Enhanced RDoc for Time (#6118)
https://git.ruby-lang.org/ruby.git/commit/?id=8309b1366c From 8309b1366c3307ab8d9cda5b61b91540cf6cc8aa Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Tue, 12 Jul 2022 13:21:32 -0500 Subject: [DOC] Enhanced RDoc for Time (#6118) Treats: ::utc ::local #to_i #to_f #to_r #usec #nsec #subsec #<=> #eql? --- time.c | 180 ++++++++++++++++++++++++++++++----------------------------------- 1 file changed, 82 insertions(+), 98 deletions(-) diff --git a/time.c b/time.c index dc454572ec..56dfb5d8a3 100644 --- a/time.c +++ b/time.c @@ -3334,7 +3334,7 @@ tmcmp(struct tm *a, struct tm *b) https://github.com/ruby/ruby/blob/trunk/time.c#L3334 /* * call-seq: - * Time.utc(year, month=1, day=1, hour=0, min=0, sec_i=0, usec=0) -> new_time + * 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; @@ -3351,9 +3351,9 @@ tmcmp(struct tm *a, struct tm *b) https://github.com/ruby/ruby/blob/trunk/time.c#L3351 * 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"] + * # => [55, 14, 10, 7, 7, 2022, 4, 188, true, "Central Daylight Time"] * array[5] = 2000 - * Time.utc(*array) # => 2000-04-24 13:26:57 UTC + * Time.utc(*array) # => 2000-07-07 10:14:55 UTC * * Parameters: * :include: doc/time/year.rdoc @@ -3361,8 +3361,8 @@ tmcmp(struct tm *a, struct tm *b) https://github.com/ruby/ruby/blob/trunk/time.c#L3361 * :include: doc/time/sec_i.rdoc * :include: doc/time/usec.rdoc * - * Alias: Time.gm. - + * Time.gm is an alias for Time.utc. + * * Related: Time.local. * */ @@ -3377,7 +3377,7 @@ time_s_mkutc(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/time.c#L3377 /* * call-seq: - * Time.local(year, month=1, day=1, hour=0, min=0, sec_i=0, usec=0) -> new_time + * 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; @@ -3394,9 +3394,9 @@ time_s_mkutc(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/time.c#L3394 * 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"] + * # => [57, 18, 10, 7, 7, 2022, 4, 188, true, "Central Daylight Time"] * array[5] = 2000 - * Time.local(*array) # => 2000-04-24 13:26:57 -0500 + * Time.local(*array) # => 2000-07-07 10:18:57 -0500 * * Parameters: * :include: doc/time/year.rdoc @@ -3404,7 +3404,7 @@ time_s_mkutc(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/time.c#L3404 * :include: doc/time/sec_i.rdoc * :include: doc/time/usec.rdoc * - * Alias: Time.mktime. + * Time.mktime is an alias for Time.local. * * Related: Time.utc. */ @@ -3420,16 +3420,20 @@ time_s_mktime(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/time.c#L3420 /* * call-seq: - * time.to_i -> int - * time.tv_sec -> int + * to_i -> integer * - * Returns the value of _time_ as an integer number of seconds - * since the Epoch. + * Returns the number of seconds since the Epoch + * for the time represented in +self+: + * + * Time.utc(1970, 1, 1).to_i # => 0 + * t = Time.now.to_i # => 1595263289 * - * If _time_ contains subsecond, they are truncated. + * Subseconds are omitted: * - * t = Time.now #=> 2020-07-21 01:41:29.746012609 +0900 - * t.to_i #=> 1595263289 + * t = Time.now # => 2022-07-12 09:13:48.5075976 -0500 + * t.to_i # => 1657635228 + * + * Time#tv_sec is an alias for Time#to_i. */ static VALUE @@ -3443,26 +3447,18 @@ time_to_i(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3447 /* * call-seq: - * time.to_f -> float - * - * Returns the value of _time_ as a floating point number of - * seconds since the Epoch. - * The return value approximate the exact value in the Time object - * because floating point numbers cannot represent all rational numbers - * exactly. - * - * t = Time.now #=> 2020-07-20 22:00:29.38740268 +0900 - * t.to_f #=> 1595250029.3874028 - * t.to_i #=> 1595250029 - * - * Note that IEEE 754 double is not accurate enough to represent - * the exact number of nanoseconds since the Epoch. - * (IEEE 754 double has 53bit mantissa. - * So it can represent exact number of nanoseconds only in - * <tt>2 ** 53 / 1_000_000_000 / 60 / 60 / 24 = 104.2</tt> days.) - * When Ruby uses a nanosecond-resolution clock function, - * such as +clock_gettime+ of POSIX, to obtain the current time, - * Time#to_f can lose information of a Time object created with +Time.now+. + * to_f -> float + * + * Returns the value of +self+ as a Float number of seconds + * since the Epoch. + * The stored value of +self+ is a + * {Rational}[rdoc-ref:Rational@#method-i-to_f], + * which means that the returned value may be approximate: + * + * t = Time.now # => 2022-07-07 11:23:18.0784889 -0500 + * t.to_f # => 1657210998.0784888 + * t.to_i # => 1657210998 + * */ static VALUE @@ -3476,16 +3472,13 @@ time_to_f(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3472 /* * call-seq: - * time.to_r -> a_rational + * time.to_r -> rational * - * Returns the value of _time_ as a rational number of seconds - * since the Epoch. + * Returns the value of +self+ as a Rational number of seconds + * since the Epoch, which is exact: * - * t = Time.now #=> 2020-07-20 22:03:45.212167333 +0900 - * t.to_r #=> (1595250225212167333/1000000000) + * Time.now.to_r # => (16571402750320203/10000000) * - * This method is intended to be used to get an accurate value - * representing the seconds (including subsecond) since the Epoch. */ static VALUE @@ -3504,22 +3497,18 @@ time_to_r(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3497 /* * call-seq: - * time.usec -> int - * time.tv_usec -> int + * usec -> integer * - * Returns the number of microseconds for the subsecond part of _time_. - * The result is a non-negative integer less than 10**6. + * Returns the number of microseconds in the subseconds part of +self+ + * in the range (0..999_999); + * lower-order digits are truncated, not rounded: * - * t = Time.now #=> 2020-07-20 22:05:58.459785953 +0900 - * t.usec #=> 459785 + * t = Time.now # => 2022-07-11 14:59:47.5484697 -0500 + * t.usec # => 548469 * - * If _time_ has fraction of microsecond (such as nanoseconds), - * it is truncated. + * Related: Time#subsec (returns exact subseconds). * - * t = Time.new(2000,1,1,0,0,0.666_777_888_999r) - * t.usec #=> 666777 - * - * Time#subsec can be used to obtain the subsecond part exactly. + * Time#tv_usec is an alias for Time#usec. */ static VALUE @@ -3537,22 +3526,18 @@ time_usec(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3526 /* * call-seq: - * time.nsec -> int - * time.tv_nsec -> int - * - * Returns the number of nanoseconds for the subsecond part of _time_. - * The result is a non-negative integer less than 10**9. + * time.nsec -> integer * - * t = Time.now #=> 2020-07-20 22:07:10.963933942 +0900 - * t.nsec #=> 963933942 + * Returns the number of nanoseconds in the subseconds part of +self+ + * in the range (0..999_999_999); + * lower-order digits are truncated, not rounded: * - * If _time_ has fraction of nanosecond (such as picoseconds), - * it is truncated. + * t = Time.now # => 2022-07-11 15:04:53.3219637 -0500 + * t.nsec # => 321963700 * - * t = Time.new(2000,1,1,0,0,0.666_777_888_999r) - * t.nsec #=> 666777888 + * Related: Time#subsec (returns exact subseconds). * - * Time#subsec can be used to obtain the subsecond part exactly. + * Time#tv_nsec is an alias for Time#usec. */ static VALUE @@ -3566,22 +3551,18 @@ time_nsec(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3551 /* * call-seq: - * time.subsec -> number + * subsec -> numeric * - * Returns the subsecond for _time_. + * Returns the exact subseconds for +self+ as a Numeric + * (Integer or Rational): * - * The return value can be a rational number. + * t = Time.now # => 2022-07-11 15:11:36.8490302 -0500 + * t.subsec # => (4245151/5000000) * - * t = Time.now #=> 2020-07-20 15:40:26.867462289 +0900 - * t.subsec #=> (867462289/1000000000) + * If the subseconds is zero, returns integer zero: * - * t = Time.now #=> 2020-07-20 15:40:50.313828595 +0900 - * t.subsec #=> (62765719/200000000) - * - * t = Time.new(2000,1,1,2,3,4) #=> 2000-01-01 02:03:04 +0900 - * t.subsec #=> 0 - * - * Time.new(2000,1,1,0,0,1/3r,"UTC").subsec #=> (1/3) + * t = Time.new(2000, 1, 1, 2, 3, 4) # => 2000-01-01 02:03:04 -0600 + * t.subsec # => 0 * */ @@ -3596,27 +3577,30 @@ time_subsec(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3577 /* * call-seq: - * time <=> other_time -> -1, 0, +1, or nil + * self <=> other_time -> -1, 0, +1, or nil * - * Compares +time+ with +other_time+. + * Compares +self+ with +other_time+; returns: * - * -1, 0, +1 or nil depending on whether +time+ is less than, equal to, or - * greater than +other_time+. + * - +-1+, if +self+ is less than +other_time+. + * - +0+, if +self+ is equal to +other_time+. + * - +1+, if +self+ is greater then +other_time+ (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/