1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
|
== 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.
|
