ruby-changes:73089
From: Burdette <ko1@a...>
Date: Mon, 29 Aug 2022 06:50:10 +0900 (JST)
Subject: [ruby-changes:73089] aecc3b1252 (master): [DOC] Enhanced RDoc for Time (#6294)
https://git.ruby-lang.org/ruby.git/commit/?id=aecc3b1252 From aecc3b12528e1b02d24bcd5df746e93aa04ba211 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Sun, 28 Aug 2022 16:49:51 -0500 Subject: [DOC] Enhanced RDoc for Time (#6294) --- time.c | 37 +++++++++++++++++++++---------------- timev.rb | 62 +++++++++++++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 68 insertions(+), 31 deletions(-) diff --git a/time.c b/time.c index 505ab4835c..56ff35b34e 100644 --- a/time.c +++ b/time.c @@ -3487,18 +3487,18 @@ time_s_mktime(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/time.c#L3487 * call-seq: * to_i -> integer * - * Returns the number of seconds since the Epoch - * for the time represented in +self+: + * Returns the value of +self+ as integer + * {Epoch seconds}[rdoc-ref:Time@Epoch+Seconds]; + * subseconds are truncated (not rounded): * - * Time.utc(1970, 1, 1).to_i # => 0 - * t = Time.now.to_i # => 1595263289 - * - * Subseconds are omitted: - * - * t = Time.now # => 2022-07-12 09:13:48.5075976 -0500 - * t.to_i # => 1657635228 + * Time.utc(1970, 1, 1, 0, 0, 0).to_i # => 0 + * Time.utc(1970, 1, 1, 0, 0, 0, 999999).to_i # => 0 + * Time.utc(1950, 1, 1, 0, 0, 0).to_i # => -631152000 + * Time.utc(1990, 1, 1, 0, 0, 0).to_i # => 631152000 * * Time#tv_sec is an alias for Time#to_i. + * + * Related: Time#to_f Time#to_r. */ static VALUE @@ -3514,16 +3514,20 @@ time_to_i(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3514 * call-seq: * to_f -> float * - * Returns the value of +self+ as a Float number of seconds - * since the Epoch. + * Returns the value of +self+ as a Float number + * {Epoch seconds}[rdoc-ref:Time@Epoch+Seconds]; + * subseconds are included. + * * 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 + * Time.utc(1970, 1, 1, 0, 0, 0).to_f # => 0.0 + * Time.utc(1970, 1, 1, 0, 0, 0, 999999).to_f # => 0.999999 + * Time.utc(1950, 1, 1, 0, 0, 0).to_f # => -631152000.0 + * Time.utc(1990, 1, 1, 0, 0, 0).to_f # => 631152000.0 * + * Related: Time#to_i, Time#to_r. */ static VALUE @@ -3539,11 +3543,12 @@ time_to_f(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3543 * call-seq: * to_r -> rational * - * Returns the value of +self+ as a Rational number of seconds - * since the Epoch, which is exact: + * Returns the value of +self+ as a Rational exact number of + * {Epoch seconds}[rdoc-ref:Time@Epoch+Seconds]; * * Time.now.to_r # => (16571402750320203/10000000) * + * Related: Time#to_f, Time#to_i. */ static VALUE diff --git a/timev.rb b/timev.rb index ad97d63b55..48aabdc798 100644 --- a/timev.rb +++ b/timev.rb @@ -1,19 +1,49 @@ https://github.com/ruby/ruby/blob/trunk/timev.rb#L1 -# Time is an abstraction of dates and times. Time is stored internally as -# the number of seconds with subsecond since the _Epoch_, -# 1970-01-01 00:00:00 UTC. +# A \Time object represents a date and time: # -# The Time class treats GMT -# (Greenwich Mean Time) and UTC (Coordinated Universal Time) as equivalent. -# GMT is the older way of referring to these baseline times but persists in -# the names of calls on POSIX systems. +# Time.new(2000, 1, 1, 0, 0, 0) # => 2000-01-01 00:00:00 -0600 # -# Note: A \Time object uses the resolution available on your system clock. +# Although its value can be expressed as a single numeric +# (see {Epoch Seconds}[rdoc-ref:Time@Epoch+Seconds] below), +# it can be convenient to deal with the value by parts: # -# All times may have subsecond. Be aware of this fact when comparing times -# with each other -- times that are apparently equal when displayed may be -# different when compared. -# (Since Ruby 2.7.0, Time#inspect shows subsecond but -# Time#to_s still doesn't show subsecond.) +# t = Time.new(-2000, 1, 1, 0, 0, 0.0) +# # => -2000-01-01 00:00:00 -0600 +# t.year # => -2000 +# t.month # => 1 +# t.mday # => 1 +# t.hour # => 0 +# t.min # => 0 +# t.sec # => 0 +# t.subsec # => 0 +# +# t = Time.new(2000, 12, 31, 23, 59, 59.5) +# # => 2000-12-31 23:59:59.5 -0600 +# t.year # => 2000 +# t.month # => 12 +# t.mday # => 31 +# t.hour # => 23 +# t.min # => 59 +# t.sec # => 59 +# t.subsec # => (1/2) +# +# == Epoch Seconds +# +<i>Epoch seconds</i> is the exact number of seconds +(including fractional subseconds) since the Unix Epoch, January 1, 1970. +# +# You can retrieve that value exactly using method Time.to_r: +# +# Time.at(0).to_r # => (0/1) +# Time.at(0.999999).to_r # => (9007190247541737/9007199254740992) +# +# Other retrieval methods such as Time#to_i and Time#to_f +# may return a value that rounds or truncates subseconds. +# +# == \Time Resolution +# +# A \Time object derived from the system clock +# (for example, by method Time.now) +# has the resolution supported by the system. # # == Examples # @@ -229,7 +259,9 @@ class Time https://github.com/ruby/ruby/blob/trunk/timev.rb#L259 # # - A \Time object, whose value is the basis for the returned time; # also influenced by optional keyword argument +in:+ (see below). - # - A numeric number of seconds (since the epoch) for the returned time. + # - A numeric number of + # {Epoch seconds}[rdoc-ref:Time@Epoch+Seconds] + # for the returned time. # # Examples: # @@ -259,7 +291,7 @@ class Time https://github.com/ruby/ruby/blob/trunk/timev.rb#L291 # Time.at(secs, 1000000, :microsecond) # => 2001-01-01 00:00:00 -0600 # Time.at(secs, -1000000, :microsecond) # => 2000-12-31 23:59:58 -0600 # - # - +:nsec+ or +:nanosecond+: +subsec+ in nanoseconds: + # - +:nanosecond+ or +:nsec+: +subsec+ in nanoseconds: # # Time.at(secs, 0, :nanosecond) # => 2000-12-31 23:59:59 -0600 # Time.at(secs, 500000000, :nanosecond) # => 2000-12-31 23:59:59.5 -0600 -- cgit v1.2.1 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/