ruby-changes:62336
From: Tanaka <ko1@a...>
Date: Tue, 21 Jul 2020 20:29:23 +0900 (JST)
Subject: [ruby-changes:62336] 48eb1ad2c3 (master): [DOC] time.c document updated.
https://git.ruby-lang.org/ruby.git/commit/?id=48eb1ad2c3 From 48eb1ad2c3aa1a14bd8ef61cbd72a791b0b67418 Mon Sep 17 00:00:00 2001 From: Tanaka Akira <akr@f...> Date: Tue, 21 Jul 2020 20:28:36 +0900 Subject: [DOC] time.c document updated. * fraction -> subsecond for consistency with method name * The sentence, "A non-portable feature allows the offset to be negative on some systems.", is removed. Time before 1970 should work portably now. If localtime() doesn't work before 1970, Ruby should extrapolate it. * Time::new -> Time.new "::" for method call is not common notation now. * Time#to_i truncates subsecond * Time#to_f approximates a value in Time object * Time#to_r The sentence, "You can use this method to convert _time_ to another Epoch.", is removed. It is not clear because no actual example of "another Epoch" is given. * Time#usec truncates fraction of microseconds. * Time#nsec truncates fraction of nanoseconds. * describe Time#inspect shows subsecond since Ruby 2.7.0. diff --git a/time.c b/time.c index b1dfce0..8d72068 100644 --- a/time.c +++ b/time.c @@ -1303,7 +1303,7 @@ gmtimew(wideval_t timew, struct vtm *result) https://github.com/ruby/ruby/blob/trunk/time.c#L1303 static struct tm *localtime_with_gmtoff_zone(const time_t *t, struct tm *result, long *gmtoff, VALUE *zone); /* - * The idea is borrowed from Perl: + * The idea, extrapolate localtime() function, is borrowed from Perl: * http://web.archive.org/web/20080211114141/http://use.perl.org/articles/08/02/07/197204.shtml * * compat_common_month_table is generated by the following program. @@ -2394,12 +2394,12 @@ time_init_1(int argc, VALUE *argv, VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L2394 * It is initialized to the current system time if no argument is given. * * *Note:* The new object will use the resolution available on your - * system clock, and may include fractional seconds. + * system clock, and may include subsecond. * * If one or more arguments are specified, the time is initialized to the * specified time. * - * +sec+ may have fraction if it is a rational. + * +sec+ may have subsecond if it is a rational. * * +tz+ specifies the timezone. * It can be an offset from UTC, given either as a string such as "+09:00" @@ -2408,11 +2408,11 @@ time_init_1(int argc, VALUE *argv, VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L2408 * Or it can be a timezone object, * see {Timezone argument}[#class-Time-label-Timezone+argument] for details. * - * a = Time.new #=> 2007-11-19 07:50:02 -0600 - * b = Time.new #=> 2007-11-19 07:50:02 -0600 + * a = Time.new #=> 2020-07-21 01:27:44.917547285 +0900 + * b = Time.new #=> 2020-07-21 01:27:44.917617713 +0900 * a == b #=> false - * "%.6f" % a.to_f #=> "1195480202.282373" - * "%.6f" % b.to_f #=> "1195480202.283415" + * "%.6f" % a.to_f #=> "1595262464.917547" + * "%.6f" % b.to_f #=> "1595262464.917618" * * Time.new(2008,6,21, 13,30,0, "+09:00") #=> 2008-06-21 13:30:00 +0900 * @@ -2795,12 +2795,11 @@ get_scale(VALUE unit) https://github.com/ruby/ruby/blob/trunk/time.c#L2795 * +seconds+ and +microseconds_with_frac+ since the Epoch. * +seconds_with_frac+ and +microseconds_with_frac+ * can be an Integer, Float, Rational, or other Numeric. - * A non-portable feature allows the offset to be negative on some systems. * * If +in+ argument is given, the result is in that timezone or UTC offset, or * if a numeric argument is given, the result is in local time. * The +in+ argument accepts the same types of arguments as +tz+ argument of - * Time::new: string, number of seconds, or a timezone object. + * Time.new: string, number of seconds, or a timezone object. * * * Time.at(0) #=> 1969-12-31 18:00:00 -0600 @@ -3511,7 +3510,7 @@ time_s_mkutc(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/time.c#L3510 * 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::gm, but interprets the values in the + * 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 @@ -3534,9 +3533,10 @@ time_s_mktime(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/time.c#L3533 * Returns the value of _time_ as an integer number of seconds * since the Epoch. * - * t = Time.now - * "%10.5f" % t.to_f #=> "1270968656.89607" - * t.to_i #=> 1270968656 + * If _time_ contains subsecond, they are truncated. + * + * t = Time.now #=> 2020-07-21 01:41:29.746012609 +0900 + * t.to_i #=> 1595263289 */ static VALUE @@ -3554,13 +3554,22 @@ time_to_i(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3554 * * 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 - * "%10.5f" % t.to_f #=> "1270968744.77658" - * t.to_i #=> 1270968744 + * 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 + * `2 ** 53 / 1_000_000_000 / 60 / 60 / 24 = 104.2` days.) + * When Ruby uses a nanosecond-resolution clock function, + * such as +clock_gettime+ of POSIX, to obtain the current time, + * Time#to_f can lost information of a Time object created with +Time.now+. */ static VALUE @@ -3579,12 +3588,11 @@ time_to_f(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3588 * Returns the value of _time_ as a rational number of seconds * since the Epoch. * - * t = Time.now - * t.to_r #=> (1270968792716287611/1000000000) + * t = Time.now #=> 2020-07-20 22:03:45.212167333 +0900 + * t.to_r #=> (1595250225212167333/1000000000) * - * This methods is intended to be used to get an accurate value - * representing the nanoseconds since the Epoch. You can use this method - * to convert _time_ to another Epoch. + * This method is intended to be used to get an accurate value + * representing the seconds (including subsecond) since the Epoch. */ static VALUE @@ -3606,11 +3614,19 @@ time_to_r(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3614 * time.usec -> int * time.tv_usec -> int * - * Returns the number of microseconds for _time_. + * Returns the number of microseconds for the subsecond part of _time_. + * The result is a non-negative integer less than 10**6. + * + * t = Time.now #=> 2020-07-20 22:05:58.459785953 +0900 + * t.usec #=> 459785 * - * t = Time.now #=> 2007-11-19 08:03:26 -0600 - * "%10.6f" % t.to_f #=> "1195481006.775195" - * t.usec #=> 775195 + * If _time_ has fraction of microsecond (such as nanoseconds), + * it is truncated. + * + * 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. */ static VALUE @@ -3631,17 +3647,19 @@ time_usec(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3647 * time.nsec -> int * time.tv_nsec -> int * - * Returns the number of nanoseconds for _time_. + * Returns the number of nanoseconds for the subsecond part of _time_. + * The result is a non-negative integer less than 10**9. * - * t = Time.now #=> 2007-11-17 15:18:03 +0900 - * "%10.9f" % t.to_f #=> "1195280283.536151409" - * t.nsec #=> 536151406 + * t = Time.now #=> 2020-07-20 22:07:10.963933942 +0900 + * t.nsec #=> 963933942 * - * The lowest digits of #to_f and #nsec are different because - * IEEE 754 double is not accurate enough to represent - * the exact number of nanoseconds since the Epoch. + * If _time_ has fraction of nanosecond (such as picoseconds), + * it is truncated. + * + * t = Time.new(2000,1,1,0,0,0.666_777_888_999r) + * t.nsec #=> 666777888 * - * The more accurate value is returned by #nsec. + * Time#subsec can be used to obtain the subsecond part exactly. */ static VALUE @@ -3657,19 +3675,21 @@ time_nsec(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3675 * call-seq: * time.subsec -> number * - * Returns the fraction for _time_. + * Returns the subsecond for _time_. * * The return value can be a rational number. * - * t = Time.now #=> 2009-03-26 22:33:12 +0900 - * "%10.9f" % t.to_f #=> "1238074392.940563917" - * t.subsec #=> (94056401/100000000) + * t = Time.now #=> 2020-07-20 15:40:26.867462289 +0900 + * t.subsec #=> (867462289/1000000000) * - * The lowest digits of #to_f and #subsec are different because - * IEEE 754 double is not accurate enough to represent - * the rational number. + * 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) * - * The more accurate value is returned by #subsec. */ static VALUE @@ -3685,9 +3705,9 @@ time_subsec(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3705 * call- (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/