ruby-changes:73021
From: Burdette <ko1@a...>
Date: Tue, 23 Aug 2022 01:22:02 +0900 (JST)
Subject: [ruby-changes:73021] b8d142e733 (master): [DOC] Enhanced RDoc for Time (#6267)
https://git.ruby-lang.org/ruby.git/commit/?id=b8d142e733 From b8d142e733b5fc8810f53a45a7107414e6ae567c Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Mon, 22 Aug 2022 11:21:36 -0500 Subject: [DOC] Enhanced RDoc for Time (#6267) Treats: #utc #getlocal #getutc #ctime #to_s #inspect --- doc/timezone_specifiers.rdoc | 1 + time.c | 124 ++++++++++++++++++++++--------------------- 2 files changed, 64 insertions(+), 61 deletions(-) diff --git a/doc/timezone_specifiers.rdoc b/doc/timezone_specifiers.rdoc index f1c23372b1..a6d57a1b21 100644 --- a/doc/timezone_specifiers.rdoc +++ b/doc/timezone_specifiers.rdoc @@ -5,6 +5,7 @@ Certain methods in class Time accept arguments that specify timezones: https://github.com/ruby/ruby/blob/trunk/doc/timezone_specifiers.rdoc#L5 - Time.at: keyword argument +in:+. - Time.new: positional argument +zone+ or keyword argument +in:+. - Time.now: keyword argument +in:+. +- Time#getlocal: positional argument +zone+. - Time#localtime: positional argument +zone+. The value given with any of these must be one of the following: diff --git a/time.c b/time.c index 01c402e7f9..dba8f1f620 100644 --- a/time.c +++ b/time.c @@ -3814,20 +3814,18 @@ time_localtime_m(int argc, VALUE *argv, VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3814 /* * call-seq: - * time.gmtime -> time - * time.utc -> time + * utc -> self * - * Converts _time_ to UTC (GMT), modifying the receiver. + * Returns +self+, converted to the UTC timezone: * - * t = Time.now #=> 2007-11-19 08:18:31 -0600 - * t.gmt? #=> false - * t.gmtime #=> 2007-11-19 14:18:31 UTC - * t.gmt? #=> true + * t = Time.new(2000) # => 2000-01-01 00:00:00 -0600 + * t.utc? # => false + * t.utc # => 2000-01-01 06:00:00 UTC + * t.utc? # => true * - * t = Time.now #=> 2007-11-19 08:18:51 -0600 - * t.utc? #=> false - * t.utc #=> 2007-11-19 14:18:51 UTC - * t.utc? #=> true + * Time#gmtime is an alias for Time#utc. + * + * Related: Time#getutc (returns a new converted \Time object). */ static VALUE @@ -3889,31 +3887,19 @@ time_fixoff(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3887 /* * call-seq: - * time.getlocal -> new_time - * time.getlocal(utc_offset) -> new_time - * time.getlocal(timezone) -> new_time - * - * Returns a new Time object representing _time_ in - * local time (using the local time zone in effect for this process). + * getlocal(zone = nil) -> new_time * - * If +utc_offset+ is given, it is used instead of the local time. - * +utc_offset+ can be given as a human-readable string (eg. <code>"+09:00"</code>) - * or as a number of seconds (eg. <code>32400</code>). + * Returns a new \Time object representing the value of +self+ + * converted to a given timezone; + * if +zone+ is +nil+, the local timezone is used: * - * t = Time.utc(2000,1,1,20,15,1) #=> 2000-01-01 20:15:01 UTC - * t.utc? #=> true - * - * l = t.getlocal #=> 2000-01-01 14:15:01 -0600 - * l.utc? #=> false - * t == l #=> true + * t = Time.utc(2000) # => 2000-01-01 00:00:00 UTC + * t.getlocal # => 1999-12-31 18:00:00 -0600 + * t.getlocal('+12:00') # => 2000-01-01 12:00:00 +1200 * - * j = t.getlocal("+09:00") #=> 2000-01-02 05:15:01 +0900 - * j.utc? #=> false - * t == j #=> true + * For forms of argument +zone+, see + * {Timezone Specifiers}[rdoc-ref:doc/timezone_specifiers.rdoc]. * - * k = t.getlocal(9*60*60) #=> 2000-01-02 05:15:01 +0900 - * k.utc? #=> false - * t == k #=> true */ static VALUE @@ -3950,16 +3936,18 @@ time_getlocaltime(int argc, VALUE *argv, VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3936 /* * call-seq: - * time.getgm -> new_time - * time.getutc -> new_time + * getutc -> new_time + * + * Returns a new \Time object representing the value of +self+ + * converted to the UTC timezone: * - * Returns a new Time object representing _time_ in UTC. + * local = Time.local(2000) # => 2000-01-01 00:00:00 -0600 + * local.utc? # => false + * utc = local.getutc # => 2000-01-01 06:00:00 UTC + * utc.utc? # => true + * utc == local # => true * - * t = Time.local(2000,1,1,20,15,1) #=> 2000-01-01 20:15:01 -0600 - * t.gmt? #=> false - * y = t.getgm #=> 2000-01-02 02:15:01 UTC - * y.gmt? #=> true - * t == y #=> true + * Time#getgm is an alias for Time#getutc. */ static VALUE @@ -3981,13 +3969,25 @@ static VALUE strftime_cstr(const char *fmt, size_t len, VALUE time, rb_encoding https://github.com/ruby/ruby/blob/trunk/time.c#L3969 /* * call-seq: - * time.asctime -> string - * time.ctime -> string + * ctime -> string + * + * Returns a string representation of +self+, + * formatted by <tt>strftime('%a %b %e %T %Y')</tt> + * or its shorthand version <tt>strftime('%c')</tt>; + * see {Formats for Dates and Times}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html]: * - * Returns a canonical string representation of _time_. + * t = Time.new(2000, 12, 31, 23, 59, 59, 0.5) + * t.ctime # => "Sun Dec 31 23:59:59 2000" + * t.strftime('%a %b %e %T %Y') # => "Sun Dec 31 23:59:59 2000" + * t.strftime('%c') # => "Sun Dec 31 23:59:59 2000" + * + * Time#asctime is an alias for Time#ctime. + * + * Related: Time#to_s, Time#inspect: + * + * t.inspect # => "2000-12-31 23:59:59.5 +000001" + * t.to_s # => "2000-12-31 23:59:59 +0000" * - * Time.now.asctime #=> "Wed Apr 9 08:56:03 2003" - * Time.now.ctime #=> "Wed Apr 9 08:56:03 2003" */ static VALUE @@ -3998,17 +3998,18 @@ time_asctime(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3998 /* * call-seq: - * time.to_s -> string + * to_s -> string + * + * Returns a string representation of +self+, without subseconds: * - * Returns a string representing _time_. Equivalent to calling - * #strftime with the appropriate format string. + * t = Time.new(2000, 12, 31, 23, 59, 59, 0.5) + * t.to_s # => "2000-12-31 23:59:59 +0000" * - * t = Time.now - * t.to_s #=> "2012-11-10 18:16:12 +0100" - * t.strftime "%Y-%m-%d %H:%M:%S %z" #=> "2012-11-10 18:16:12 +0100" + * Related: Time#ctime, Time#inspect: + * + * t.ctime # => "Sun Dec 31 23:59:59 2000" + * t.inspect # => "2000-12-31 23:59:59.5 +000001" * - * t.utc.to_s #=> "2012-11-10 17:16:12 UTC" - * t.strftime "%Y-%m-%d %H:%M:%S UTC" #=> "2012-11-10 17:16:12 UTC" */ static VALUE @@ -4025,17 +4026,18 @@ time_to_s(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L4026 /* * call-seq: - * time.inspect -> string + * inspect -> string + * + * Returns a string representation of +self+ with subseconds: + * + * t = Time.new(2000, 12, 31, 23, 59, 59, 0.5) + * t.inspect # => "2000-12-31 23:59:59.5 +000001" * - * Returns a detailed string representing _time_. Unlike to_s, - * preserves subsecond in the representation for easier debugging. + * Related: Time#ctime, Time#to_s: * - * t = Time.now - * t.inspect #=> "2012-11-10 18:16:12.261257655 +0100" - * t.strftime "%Y-%m-%d %H:%M:%S.%N %z" #=> "2012-11-10 18:16:12.261257655 +0100" + * t.ctime # => "Sun Dec 31 23:59:59 2000" + * t.to_s # => "2000-12-31 23:59:59 +0000" * - * t.utc.inspect #=> "2012-11-10 17:16:12.261257655 UTC" - * t.strftime "%Y-%m-%d %H:%M:%S.%N UTC" #=> "2012-11-10 17:16:12.261257655 UTC" */ static VALUE -- cgit v1.2.1 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/