diff options
author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2022-08-21 11:36:36 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-08-21 11:36:36 -0500 |
commit | 936327a51915d6a39086f65ea1b8e5c5c4ade78f (patch) | |
tree | 85a95347dd61199f02578ecdc448a775a0f1e048 /doc | |
parent | b043dd9c5dd7b5c46580e49ad38b49d5cb5beaf1 (diff) | |
download | ruby-936327a51915d6a39086f65ea1b8e5c5c4ade78f.tar.gz |
[DOC] Enhanced RDoc for Time (#6255)
Treats:
#utc
#hash
#localtime
Diffstat (limited to 'doc')
-rw-r--r-- | doc/time/in.rdoc | 11 | ||||
-rw-r--r-- | doc/time/zone_and_in.rdoc | 13 | ||||
-rw-r--r-- | doc/timezone_specifiers.rdoc | 45 |
3 files changed, 54 insertions, 15 deletions
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 @@ -- <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 @@ -- +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 @@ +=== 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. |