ruby-changes:73385
From: Burdette <ko1@a...>
Date: Sat, 3 Sep 2022 04:12:08 +0900 (JST)
Subject: [ruby-changes:73385] c8c90e459e (master): Enhanced RDoc for Tim[DOC] (#6319)
https://git.ruby-lang.org/ruby.git/commit/?id=c8c90e459e From c8c90e459e37632fee74718d77c63c22814268f7 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Fri, 2 Sep 2022 14:11:53 -0500 Subject: Enhanced RDoc for Tim[DOC] (#6319) --- time.c | 358 ++++++++++++++++++++++++++++++++++++----------------------------- 1 file changed, 200 insertions(+), 158 deletions(-) diff --git a/time.c b/time.c index 2b4323a536..a02e53d7f1 100644 --- a/time.c +++ b/time.c @@ -4160,13 +4160,16 @@ time_add(const struct time_object *tobj, VALUE torig, VALUE offset, int sign) https://github.com/ruby/ruby/blob/trunk/time.c#L4160 /* * call-seq: - * time + numeric -> time + * self + numeric -> new_time * - * Adds some number of seconds (possibly including subsecond) to - * _time_ and returns that value as a new Time object. + * Returns a new \Time object whose value is the sum of the numeric value + * of +self+ and the given +numeric+: * - * t = Time.now #=> 2020-07-20 22:14:43.170490982 +0900 - * t + (60 * 60 * 24) #=> 2020-07-21 22:14:43.170490982 +0900 + * t = Time.new(2000) # => 2000-01-01 00:00:00 -0600 + * t + (60 * 60 * 24) # => 2000-01-02 00:00:00 -0600 + * t + 0.5 # => 2000-01-01 00:00:00.5 -0600 + * + * Related: Time#-. */ static VALUE @@ -4183,17 +4186,24 @@ time_plus(VALUE time1, VALUE time2) https://github.com/ruby/ruby/blob/trunk/time.c#L4186 /* * call-seq: - * time - other_time -> float - * time - numeric -> time + * self - numeric -> new_time + * self - other_time -> float + * + * When +numeric+ is given, + * returns a new \Time object whose value is the difference + * of the numeric value of +self+ and +numeric+: + * + * t = Time.new(2000) # => 2000-01-01 00:00:00 -0600 + * t - (60 * 60 * 24) # => 1999-12-31 00:00:00 -0600 + * t - 0.5 # => 1999-12-31 23:59:59.5 -0600 + * + * When +other_time+ is given, + * returns a Float whose value is the difference + * of the numeric values of +self+ and +other_time+: * - * Returns a difference in seconds as a Float - * between _time_ and +other_time+, or subtracts the given number - * of seconds in +numeric+ from _time_. + * t - t # => 0.0 * - * t = Time.now #=> 2020-07-20 22:15:49.302766336 +0900 - * t2 = t + 2592000 #=> 2020-08-19 22:15:49.302766336 +0900 - * t2 - t #=> 2592000.0 - * t2 - 2592000 #=> 2020-07-20 22:15:49.302766336 +0900 + * Related: Time#+. */ static VALUE @@ -4228,31 +4238,30 @@ ndigits_denominator(VALUE ndigits) https://github.com/ruby/ruby/blob/trunk/time.c#L4238 /* * call-seq: - * time.round([ndigits]) -> new_time - * - * Rounds subsecond to a given precision in decimal digits (0 digits by default). - * It returns a new Time object. - * +ndigits+ should be zero or a positive integer. - * - * t = Time.utc(2010,3,30, 5,43,25.123456789r) - * t #=> 2010-03-30 05:43:25.123456789 UTC - * t.round #=> 2010-03-30 05:43:25 UTC - * t.round(0) #=> 2010-03-30 05:43:25 UTC - * t.round(1) #=> 2010-03-30 05:43:25.1 UTC - * t.round(2) #=> 2010-03-30 05:43:25.12 UTC - * t.round(3) #=> 2010-03-30 05:43:25.123 UTC - * t.round(4) #=> 2010-03-30 05:43:25.1235 UTC - * - * t = Time.utc(1999,12,31, 23,59,59) - * (t + 0.4).round #=> 1999-12-31 23:59:59 UTC - * (t + 0.49).round #=> 1999-12-31 23:59:59 UTC - * (t + 0.5).round #=> 2000-01-01 00:00:00 UTC - * (t + 1.4).round #=> 2000-01-01 00:00:00 UTC - * (t + 1.49).round #=> 2000-01-01 00:00:00 UTC - * (t + 1.5).round #=> 2000-01-01 00:00:01 UTC - * - * t = Time.utc(1999,12,31, 23,59,59) #=> 1999-12-31 23:59:59 UTC - * (t + 0.123456789).round(4).iso8601(6) #=> 1999-12-31 23:59:59.1235 UTC + * round(ndigits = 0) -> new_time + * + * Returns a new \Time object whose numeric value is that of +self+, + * with its seconds value rounded to precision +ndigits+: + * + * t = Time.utc(2010, 3, 30, 5, 43, 25.123456789r) + * t # => 2010-03-30 05:43:25.123456789 UTC + * t.round # => 2010-03-30 05:43:25 UTC + * t.round(0) # => 2010-03-30 05:43:25 UTC + * t.round(1) # => 2010-03-30 05:43:25.1 UTC + * t.round(2) # => 2010-03-30 05:43:25.12 UTC + * t.round(3) # => 2010-03-30 05:43:25.123 UTC + * t.round(4) # => 2010-03-30 05:43:25.1235 UTC + * + * t = Time.utc(1999, 12,31, 23, 59, 59) + * t # => 1999-12-31 23:59:59 UTC + * (t + 0.4).round # => 1999-12-31 23:59:59 UTC + * (t + 0.49).round # => 1999-12-31 23:59:59 UTC + * (t + 0.5).round # => 2000-01-01 00:00:00 UTC + * (t + 1.4).round # => 2000-01-01 00:00:00 UTC + * (t + 1.49).round # => 2000-01-01 00:00:00 UTC + * (t + 1.5).round # => 2000-01-01 00:00:01 UTC + * + * Related: Time#ceil, Time#floor. */ static VALUE @@ -4278,29 +4287,29 @@ time_round(int argc, VALUE *argv, VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L4287 /* * call-seq: - * time.floor([ndigits]) -> new_time - * - * Floors subsecond to a given precision in decimal digits (0 digits by default). - * It returns a new Time object. - * +ndigits+ should be zero or a positive integer. - * - * t = Time.utc(2010,3,30, 5,43,25.123456789r) - * t #=> 2010-03-30 05:43:25.123456789 UTC - * t.floor #=> 2010-03-30 05:43:25 UTC - * t.floor(0) #=> 2010-03-30 05:43:25 UTC - * t.floor(1) #=> 2010-03-30 05:43:25.1 UTC - * t.floor(2) #=> 2010-03-30 05:43:25.12 UTC - * t.floor(3) #=> 2010-03-30 05:43:25.123 UTC - * t.floor(4) #=> 2010-03-30 05:43:25.1234 UTC - * - * t = Time.utc(1999,12,31, 23,59,59) - * (t + 0.4).floor #=> 1999-12-31 23:59:59 UTC - * (t + 0.9).floor #=> 1999-12-31 23:59:59 UTC - * (t + 1.4).floor #=> 2000-01-01 00:00:00 UTC - * (t + 1.9).floor #=> 2000-01-01 00:00:00 UTC - * - * t = Time.utc(1999,12,31, 23,59,59) - * (t + 0.123456789).floor(4) #=> 1999-12-31 23:59:59.1234 UTC + * floor(ndigits = 0) -> new_time + * + * Returns a new \Time object whose numerical value + * is less than or equal to +self+ with its seconds + * truncated to precision +ndigits+: + * + * t = Time.utc(2010, 3, 30, 5, 43, 25.123456789r) + * t # => 2010-03-30 05:43:25.123456789 UTC + * t.floor # => 2010-03-30 05:43:25 UTC + * t.floor(2) # => 2010-03-30 05:43:25.12 UTC + * t.floor(4) # => 2010-03-30 05:43:25.1234 UTC + * t.floor(6) # => 2010-03-30 05:43:25.123456 UTC + * t.floor(8) # => 2010-03-30 05:43:25.12345678 UTC + * t.floor(10) # => 2010-03-30 05:43:25.123456789 UTC + * + * t = Time.utc(1999, 12, 31, 23, 59, 59) + * t # => 1999-12-31 23:59:59 UTC + * (t + 0.4).floor # => 1999-12-31 23:59:59 UTC + * (t + 0.9).floor # => 1999-12-31 23:59:59 UTC + * (t + 1.4).floor # => 2000-01-01 00:00:00 UTC + * (t + 1.9).floor # => 2000-01-01 00:00:00 UTC + * + * Related: Time#ceil, Time#round. */ static VALUE @@ -4323,29 +4332,29 @@ time_floor(int argc, VALUE *argv, VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L4332 /* * call-seq: - * time.ceil([ndigits]) -> new_time - * - * Ceils subsecond to a given precision in decimal digits (0 digits by default). - * It returns a new Time object. - * +ndigits+ should be zero or a positive integer. - * - * t = Time.utc(2010,3,30, 5,43,25.0123456789r) - * t #=> 2010-03-30 05:43:25 123456789/10000000000 UTC - * t.ceil #=> 2010-03-30 05:43:26 UTC - * t.ceil(0) #=> 2010-03-30 05:43:26 UTC - * t.ceil(1) #=> 2010-03-30 05:43:25.1 UTC - * t.ceil(2) #=> 2010-03-30 05:43:25.02 UTC - * t.ceil(3) #=> 2010-03-30 05:43:25.013 UTC - * t.ceil(4) #=> 2010-03-30 05:43:25.0124 UTC - * - * t = Time.utc(1999,12,31, 23,59,59) - * (t + 0.4).ceil #=> 2000-01-01 00:00:00 UTC - * (t + 0.9).ceil #=> 2000-01-01 00:00:00 UTC - * (t + 1.4).ceil #=> 2000-01-01 00:00:01 UTC - * (t + 1.9).ceil #=> 2000-01-01 00:00:01 UTC - * - * t = Time.utc(1999,12,31, 23,59,59) - * (t + 0.123456789).ceil(4) #=> 1999-12-31 23:59:59.1235 UTC + * ceil(ndigits = 0) -> new_time + * + * Returns a new \Time object whose numerical value + * is greater than or equal to +self+ with its seconds + * truncated to precision +ndigits+: + * + * t = Time.utc(2010, 3, 30, 5, 43, 25.123456789r) + * t # => 2010-03-30 05:43:25.123456789 UTC + * t.ceil # => 2010-03-30 05:43:26 UTC + * t.ceil(2) # => 2010-03-30 05:43:25.13 UTC + * t.ceil(4) # => 2010-03-30 05:43:25.1235 UTC + * t.ceil(6) # => 2010-03-30 05:43:25.123457 UTC + * t.ceil(8) # => 2010-03-30 05:43:25.12345679 UTC + * t.ceil(10) # => 2010-03-30 05:43:25.123456789 UTC + * + * t = Time.utc(1999, 12, 31, 23, 59, 59) + * t # => 1999-12-31 23:59:59 UTC + * (t + 0.4).ceil # => 2000-01-01 00:00:00 UTC + * (t + 0.9).ceil # => 2000-01-01 00:00:00 UTC + * (t + 1.4).ceil # => 2000-01-01 00:00:01 UTC + * (t + 1.9).ceil # => 2000-01-01 00:00:01 UTC + * + * Related: Time#floor, Time#round. */ static VALUE @@ -4371,16 +4380,19 @@ time_ceil(int argc, VALUE *argv, VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L4380 /* * call-seq: - * time.sec -> integer + * sec -> integer * - * Returns the second of the minute (0..60) for _time_. + * Returns the integer second of the minute for +self+, + * in range (0..60): * - * *Note:* Seconds range from zero to 60 to allow the system to inject - * leap seconds. See https://en.wikipedia.org/wiki/Leap_second for further - * details. + * t = Time.new(2000, 1, 2, 3, 4, 5, 6) + * # => 2000-01-02 03:04:05 +000006 + * t (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/