ruby-changes:73006
From: Burdette <ko1@a...>
Date: Mon, 22 Aug 2022 01:36:52 +0900 (JST)
Subject: [ruby-changes:73006] 936327a519 (master): [DOC] Enhanced RDoc for Time (#6255)
https://git.ruby-lang.org/ruby.git/commit/?id=936327a519 From 936327a51915d6a39086f65ea1b8e5c5c4ade78f Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Sun, 21 Aug 2022 11:36:36 -0500 Subject: [DOC] Enhanced RDoc for Time (#6255) Treats: #utc #hash #localtime --- doc/time/in.rdoc | 11 +++----- doc/time/zone_and_in.rdoc | 13 ++++------ doc/timezone_specifiers.rdoc | 45 +++++++++++++++++++++++++++++++++ time.c | 60 +++++++++++++++++++++++--------------------- timev.rb | 4 +-- 5 files changed, 87 insertions(+), 46 deletions(-) create mode 100644 doc/timezone_specifiers.rdoc diff --git a/doc/time/in.rdoc b/doc/time/in.rdoc index 870982b0c2..33178c514a 100644 --- a/doc/time/in.rdoc +++ b/doc/time/in.rdoc @@ -1,7 +1,4 @@ https://github.com/ruby/ruby/blob/trunk/doc/time/in.rdoc#L1 -- <tt>in: zone</tt>: a timezone _zone_, which may be: - - A string offset from UTC. - - A single letter offset from UTC, in the range <tt>'A'..'Z'</tt>, - <tt>'J'</tt> excluded (the so-called military timezone). - - An integer number of seconds. - - A timezone object; - see {Timezone Argument}[#class-Time-label-Timezone+Argument] for details. +- <tt>in: zone</tt>: a timezone +zone+. + +For forms of argument +zone+, see +{Timezone Specifiers}[rdoc-ref:doc/timezone_specifiers.rdoc]. diff --git a/doc/time/zone_and_in.rdoc b/doc/time/zone_and_in.rdoc index 5bdfaacd4c..2cf6564c01 100644 --- a/doc/time/zone_and_in.rdoc +++ b/doc/time/zone_and_in.rdoc @@ -1,8 +1,5 @@ https://github.com/ruby/ruby/blob/trunk/doc/time/zone_and_in.rdoc#L1 -- +zone+: a timezone, which may be: - - A string offset from UTC. - - A single letter offset from UTC, in the range <tt>'A'..'Z'</tt>, - <tt>'J'</tt> excluded (the so-called military timezone). - - An integer number of seconds. - - A timezone object; - see {Timezone Argument}[#class-Time-label-Timezone+Argument] for details. -- <tt>in: zone</tt>: a timezone _zone_, which may be as above. +- +zone+: a timezone +zone+. +- <tt>in: zone</tt>: a timezone +zone+. + +For forms of +zone+, see +{Timezone Specifiers}[rdoc-ref:doc/timezone_specifiers.rdoc]. diff --git a/doc/timezone_specifiers.rdoc b/doc/timezone_specifiers.rdoc new file mode 100644 index 0000000000..f1c23372b1 --- /dev/null +++ b/doc/timezone_specifiers.rdoc @@ -0,0 +1,45 @@ https://github.com/ruby/ruby/blob/trunk/doc/timezone_specifiers.rdoc#L1 +=== Timezone Specifiers + +Certain methods in class Time accept arguments that specify timezones: + +- Time.at: keyword argument +in:+. +- Time.new: positional argument +zone+ or keyword argument +in:+. +- Time.now: keyword argument +in:+. +- Time#localtime: positional argument +zone+. + +The value given with any of these must be one of the following: + +- A string offset from UTC in the form <tt>'+HH:MM'</tt> or <tt>-HH:MM</tt>, + where: + + - +HH+ is the 2-digit hour in the range <tt>0..23</tt>. + - +MM+ is the 2-digit minute in the range <tt>0..59</tt>. + + Examples: + + t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC + Time.at(t, in: '-23:59') # => 1999-12-31 20:16:01 -2359 + Time.at(t, in: '+23:59') # => 2000-01-02 20:14:01 +2359 + +- A letter in the range <tt>'A'..'I'</tt> or <tt>'K'..'Z'</tt>; + see {List of military time zones}[https://en.wikipedia.org/wiki/List_of_military_time_zones]: + + t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC + Time.at(t, in: 'A') # => 2000-01-01 21:15:01 +0100 + Time.at(t, in: 'I') # => 2000-01-02 05:15:01 +0900 + Time.at(t, in: 'K') # => 2000-01-02 06:15:01 +1000 + Time.at(t, in: 'Y') # => 2000-01-01 08:15:01 -1200 + Time.at(t, in: 'Z') # => 2000-01-01 20:15:01 UTC + +- An integer number of seconds in the range <tt>-86399..86399</tt>: + + t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC + Time.at(t, in: -86399) # => 1999-12-31 20:15:02 -235959 + Time.at(t, in: 86399) # => 2000-01-02 20:15:00 +235959 + +-- +TODO: Pull in and revise the text at the link, +then add the example class TZ from the tests. +++ +- A timezone object; + see {Timezone Argument}[rdoc-ref:Time@Timezone+Argument] for details. diff --git a/time.c b/time.c index a7a4c5dc1a..e0cb7537ec 100644 --- a/time.c +++ b/time.c @@ -3486,7 +3486,7 @@ time_to_f(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3486 /* * call-seq: - * time.to_r -> rational + * to_r -> rational * * Returns the value of +self+ as a Rational number of seconds * since the Epoch, which is exact: @@ -3540,7 +3540,7 @@ time_usec(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3540 /* * call-seq: - * time.nsec -> integer + * nsec -> integer * * Returns the number of nanoseconds in the subseconds part of +self+ * in the range (0..999_999_999); @@ -3659,20 +3659,20 @@ time_eql(VALUE time1, VALUE time2) https://github.com/ruby/ruby/blob/trunk/time.c#L3659 /* * call-seq: - * time.utc? -> true or false - * time.gmt? -> true or false + * utc? -> true or false * - * Returns +true+ if _time_ represents a time in UTC (GMT). + * Returns +true+ if +self+ represents a time in UTC (GMT): * - * t = Time.now #=> 2007-11-19 08:15:23 -0600 - * t.utc? #=> false - * t = Time.gm(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 UTC - * t.utc? #=> true + * now = Time.now + * # => 2022-08-18 10:24:13.5398485 -0500 + * now.utc? # => false + * utc = Time.utc(2000, 1, 1, 20, 15, 1) + * # => 2000-01-01 20:15:01 UTC + * utc.utc? # => true * - * t = Time.now #=> 2007-11-19 08:16:03 -0600 - * t.gmt? #=> false - * t = Time.gm(2000,1,1,20,15,1) #=> 2000-01-01 20:15:01 UTC - * t.gmt? #=> true + * Time#gmt? is an alias for Time#utc?. + * + * Related: Time.utc. */ static VALUE @@ -3686,11 +3686,11 @@ time_utc_p(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3686 /* * call-seq: - * time.hash -> integer + * hash -> integer * - * Returns a hash code for this Time object. + * Returns the integer hash code for +self+. * - * See also Object#hash. + * Related: Object#hash. */ static VALUE @@ -3777,25 +3777,27 @@ time_zonelocal(VALUE time, VALUE off) https://github.com/ruby/ruby/blob/trunk/time.c#L3777 /* * call-seq: - * time.localtime -> time - * time.localtime(utc_offset) -> time + * localtime -> self or new_time + * localtime(zone) -> new_time * - * Converts _time_ to local time (using the local time zone in - * effect at the creation time of _time_) modifying the receiver. + * With no argument given: * - * If +utc_offset+ is given, it is used instead of the local time. + * - Returns +self+ if +self+ is a local time. + * - Otherwise returns a new \Time in the user's local timezone: + * + * t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC + * t.localtime # => 2000-01-01 14:15:01 -0600 * - * t = Time.utc(2000, "jan", 1, 20, 15, 1) #=> 2000-01-01 20:15:01 UTC - * t.utc? #=> true + * With argument +zone+ given, + * returns the new \Time object created by converting + * +self+ to the given time zone: * - * t.localtime #=> 2000-01-01 14:15:01 -0600 - * t.utc? #=> false + * t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC + * t.localtime("-09:00") # => 2000-01-01 11:15:01 -0900 * - * t.localtime("+09:00") #=> 2000-01-02 05:15:01 +0900 - * t.utc? #=> false + * For forms of argument +zone+, see + * {Timezone Specifiers}[rdoc-ref:doc/timezone_specifiers.rdoc]. * - * If +utc_offset+ is not given and _time_ is local time, just returns - * the receiver. */ static VALUE diff --git a/timev.rb b/timev.rb index a7e70b290f..1fd8295d0f 100644 --- a/timev.rb +++ b/timev.rb @@ -217,8 +217,8 @@ class Time https://github.com/ruby/ruby/blob/trunk/timev.rb#L217 # Time.now # => 2009-06-24 12:39:54 +0900 # Time.now(in: '+04:00') # => 2009-06-24 07:39:54 +0400 # - # Parameter: - # :include: doc/time/in.rdoc + # For forms of argument +zone+, see + # {Timezone Specifiers}[rdoc-ref:doc/timezone_specifiers.rdoc]. def self.now(in: nil) Primitive.time_s_now(Primitive.arg!(:in)) end -- cgit v1.2.1 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/