ruby-changes:73347
From: Burdette <ko1@a...>
Date: Thu, 1 Sep 2022 06:36:41 +0900 (JST)
Subject: [ruby-changes:73347] d41be1ac37 (master): [DOC] Enhanced RDoc for Time (#6308)
https://git.ruby-lang.org/ruby.git/commit/?id=d41be1ac37 From d41be1ac37a91f901a0030bfd10979240621db4e Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Wed, 31 Aug 2022 16:36:22 -0500 Subject: [DOC] Enhanced RDoc for Time (#6308) More on timezones. --- doc/timezone_specifiers.rdoc | 46 ------------------ doc/timezones.rdoc | 108 +++++++++++++++++++++++++++++++++++++++++++ time.c | 4 +- timev.rb | 40 ++-------------- 4 files changed, 115 insertions(+), 83 deletions(-) delete mode 100644 doc/timezone_specifiers.rdoc create mode 100644 doc/timezones.rdoc diff --git a/doc/timezone_specifiers.rdoc b/doc/timezone_specifiers.rdoc deleted file mode 100644 index a6d57a1b21..0000000000 --- a/doc/timezone_specifiers.rdoc +++ /dev/null @@ -1,46 +0,0 @@ https://github.com/ruby/ruby/blob/trunk/#L0 -=== 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#getlocal: positional argument +zone+. -- 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/doc/timezones.rdoc b/doc/timezones.rdoc new file mode 100644 index 0000000000..c3aae88fde --- /dev/null +++ b/doc/timezones.rdoc @@ -0,0 +1,108 @@ https://github.com/ruby/ruby/blob/trunk/doc/timezones.rdoc#L1 +== Timezones + +=== Timezone Specifiers + +Certain \Time methods 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#getlocal: positional argument +zone+. +- Time#localtime: positional argument +zone+. + +The value given with any of these must be one of the following +(each detailed below): + +- {Hours/minutes offset}[rdoc-ref:timezones.rdoc@Hours-2FMinutes+Offsets]. +- {Single-letter offset}[rdoc-ref:timezones.rdoc@Single-Letter+Offsets]. +- {Integer offset}[rdoc-ref:timezones.rdoc@Integer+Offsets]. +- {Timezone object}[rdoc-ref:timezones.rdoc@Timezone+Objects]. + +==== Hours/Minutes Offsets + +The zone value may be 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 + +==== Single-Letter Offsets + +The zone value may be 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 + +==== \Integer Offsets + +The zone value may be 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 + +==== Timezone Objects + +In most cases, the zone value may be an object +responding to certain timezone methods. + +\Exceptions (timezone object not allowed): + +- Time.new with positional argument +zone+. +- Time.now with keyword argument +in:+. + +The timezone methods are: + +- +local_to_utc+: + + - Called when Time.new is invoked with +tz+ + as the value of positional argument +zone+ or keyword argument +in:+. + - Argument: a <tt>Time::tm</tt> object. + - Returns: a \Time-like object in the UTC timezone. + +- +utc_to_local+: + + - Called when Time.at or Time.now is invoked with +tz+ + as the value for keyword argument +in:+, + and when Time#getlocal or Time#localtime is called with +tz+ + as the value for positional argument +zone+. + - Argument: a <tt>Time::tm</tt> object. + - Returns: a \Time-like object in the local timezone. + +A custom timezone class may have these instance methods, +which will be called if defined: + +- +abbr+: + + - Called when Time#strftime is invoked with a format involving <tt>%Z</tt>. + - Argument: a <tt>Time::tm</tt> object. + - Returns: a string abbreviation for the timezone name. + +- +dst?+: + + - Called when Time.at or Time.now is invoked with +tz+ + as the value for keyword argument +in:+, + and when Time#getlocal or Time#localtime is called with +tz+ + as the value for positional argument +zone+. + - Argument: a <tt>Time::tm</tt> object. + - Returns: whether the time is daylight saving time. + +- +name+: + + - Called when <tt>Marshal.dump(t) is invoked + - Argument: none. + - Returns: the string name of the timezone. diff --git a/time.c b/time.c index 56ff35b34e..2b4323a536 100644 --- a/time.c +++ b/time.c @@ -3852,7 +3852,7 @@ time_zonelocal(VALUE time, VALUE off) https://github.com/ruby/ruby/blob/trunk/time.c#L3852 * t.localtime("-09:00") # => 2000-01-01 11:15:01 -0900 * * For forms of argument +zone+, see - * {Timezone Specifiers}[rdoc-ref:timezone_specifiers.rdoc]. + * {Timezone Specifiers}[rdoc-ref:timezones.rdoc]. * */ @@ -3954,7 +3954,7 @@ time_fixoff(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3954 * t.getlocal('+12:00') # => 2000-01-01 12:00:00 +1200 * * For forms of argument +zone+, see - * {Timezone Specifiers}[rdoc-ref:timezone_specifiers.rdoc]. + * {Timezone Specifiers}[rdoc-ref:timezones.rdoc]. * */ diff --git a/timev.rb b/timev.rb index 891142e0ef..a2a8bb3cb1 100644 --- a/timev.rb +++ b/timev.rb @@ -208,38 +208,8 @@ https://github.com/ruby/ruby/blob/trunk/timev.rb#L208 # - #ceil: Returns a new time with subseconds raised to a ceiling. # - #floor: Returns a new time with subseconds lowered to a floor. # -# == Timezone Argument -# -# A timezone argument must have +local_to_utc+ and +utc_to_local+ -# methods, and may have +name+, +abbr+, and +dst?+ methods. -# -# The +local_to_utc+ method should convert a Time-like object from -# the timezone to UTC, and +utc_to_local+ is the opposite. The -# result also should be a Time or Time-like object (not necessary to -# be the same class). The #zone of the result is just ignored. -# Time-like argument to these methods is similar to a Time object in -# UTC without subsecond; it has attribute readers for the parts, -# e.g. #year, #month, and so on, and epoch time readers, #to_i. The -# subsecond attributes are fixed as 0, and #utc_offset, #zone, -# #isdst, and their aliases are same as a Time object in UTC. -# Also #to_time, #+, and #- methods are defined. -# -# The +name+ method is used for marshaling. If this method is not -# defined on a timezone object, Time objects using that timezone -# object can not be dumped by Marshal. -# -# The +abbr+ method is used by '%Z' in #strftime. -# -# The +dst?+ method is called with a +Time+ value and should return whether -# the +Time+ value is in daylight savings time in the zone. -# -# === Auto Conversion to Timezone -# -# At loading marshaled data, a timezone name will be converted to a timezone -# object by +find_timezone+ class method, if the method is defined. -# -# Similarly, that class method will be called when a timezone argument does -# not have the necessary methods mentioned above. +# For the forms of argument +zone+, see +# {Timezone Specifiers}[rdoc-ref:timezones.rdoc]. class Time # Creates a new \Time object from the current system time. # This is the same as Time.new without arguments. @@ -248,7 +218,7 @@ class Time https://github.com/ruby/ruby/blob/trunk/timev.rb#L218 # Time.now(in: '+04:00') # => 2009-06-24 07:39:54 +0400 # # For forms of argument +zone+, see - # {Timezone Specifiers}[rdoc-ref:timezone_specifiers.rdoc]. + # {Timezone Specifiers}[rdoc-ref:timezones.rdoc]. def self.now(in: nil) Primitive.time_s_now(Primitive.arg!(:in)) end @@ -306,7 +276,7 @@ class Time (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/