Class: Timezone::Zone

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/timezone/zone.rb

Overview

This object represents a real-world timezone. Each instance provides methods for converting UTC times to the local timezone and local times to UTC for any historical, present or future times.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name) ⇒ Timezone::Zone

Create a new timezone object using the timezone name.

Parameters:

  • name (String) —

    the timezone name



48
49
50
 
# File 'lib/timezone/zone.rb', line 48

def initialize(name)
  @name = name
end

Instance Attribute Details

#name ⇒ String (readonly) Also known as: to_s

Returns the timezone name.

Returns:

  • (String) —

    the timezone name



19
20
21
 
# File 'lib/timezone/zone.rb', line 19

def name
  @name
end

Instance Method Details

#<=>(other) ⇒ -1, ...

Compare one timezone with another based on current UTC offset.

Parameters:

Returns:

  • (-1, 0, 1, nil) —

    comparison based on current ‘utc_offset`.



174
175
176
177
178
 
# File 'lib/timezone/zone.rb', line 174

def <=>(other)
  return nil unless other.respond_to?(:utc_offset)

  utc_offset <=> other.utc_offset
end

#abbr(time) ⇒ String

The timezone abbreviation, at the given time.

Parameters:

  • time (#to_time) —

    the source time

Returns:

  • (String) —

    the timezone abbreviation, at the given time



141
142
143
144
145
 
# File 'lib/timezone/zone.rb', line 141

def abbr(time)
  time = sanitize(time)

  rule_for_utc(time)[NAME_BIT]
end

#dst?(time) ⇒ Boolean

If, at the given time, the timezone was observing Daylight Savings.

Parameters:

  • time (#to_time) —

    the source time

Returns:

  • (Boolean) —

    whether the timezone, at the given time, was observing Daylight Savings Time



152
153
154
155
156
 
# File 'lib/timezone/zone.rb', line 152

def dst?(time)
  time = sanitize(time)

  rule_for_utc(time)[DST_BIT]
end

#inspect ⇒ String

Returns a developer friendly representation of the object.

Returns:

  • (String) —

    a developer friendly representation of the object



24
25
26
 
# File 'lib/timezone/zone.rb', line 24

def inspect
  "#<Timezone::Zone name: \"#{name}\">"
end

#local_to_utc(time) ⇒ Time

Note:

The UTC equivalent is a “best guess”. There are cases where local times do not map to UTC at all (during a time skip forward). There are also cases where local times map to two distinct UTC times (during a fall back). All of these cases are approximated in this method and the first possible result is used instead.

Note:

A note about the handling of time arguments.

Because the UTC offset of a ‘Time` object in Ruby is not equivalent to a single timezone, the `time` argument in this method is first converted to a UTC equivalent before being used as a local time.

This prevents confusion between historical UTC offsets and the UTC offset that the ‘Time` object provides. For instance, if I pass a “local” time with offset `+8` but the timezone actually had an offset of `+9` at the given historical time, there is an inconsistency that must be resolved.

Did the user make a mistake; or is the offset intentional?

One approach to solving this problem would be to raise an error, but this means that the user then needs to calculate the appropriate local offset and append that to a UTC time to satisfy the function. This is impractical because the offset can already be calculated by this library. The user should only need to provide a time without an offset!

To resolve this inconsistency, the solution I chose was to scrub the offset. In the case where an offset is provided, the time is just converted to the UTC equivalent (without an offset). The resulting time is used as the local reference time.

For example, if the time ‘08:00 +2` is passed to this function, the local time is assumed to be `06:00`.

Converts the given local time to the UTC equivalent.

Parameters:

  • time (#to_time) —

    the local time

Returns:

  • (Time) —

    the time in UTC



109
110
111
112
113
 
# File 'lib/timezone/zone.rb', line 109

def local_to_utc(time)
  time = sanitize(time)

  (time - rule_for_local(time).rules.first[OFFSET_BIT]).utc
end

#time_with_offset(time) ⇒ Time

Converts the given time to the local timezone and includes the UTC offset in the result.

Parameters:

  • time (#to_time) —

    the source time

Returns:

  • (Time) —

    the time in the local timezone with the UTC offset



120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/timezone/zone.rb', line 120

def time_with_offset(time)
  time = sanitize(time)

  utc = utc_to_local(time)
  offset = utc_offset(time)

  Time.new(
    utc.year,
    utc.month,
    utc.day,
    utc.hour,
    utc.min,
    utc.sec + utc.subsec,
    offset
  )
end

#utc_offset(time = nil) ⇒ Integer

Return the UTC offset (in seconds) for the given time.

Parameters:

  • time (#to_time) (defaults to: nil) —

    (Time.now) the source time

Returns:

  • (Integer) —

    the UTC offset (in seconds) in the local timezone



162
163
164
165
166
167
 
# File 'lib/timezone/zone.rb', line 162

def utc_offset(time = nil)
  time ||= Time.now
  time = sanitize(time)

  rule_for_utc(time)[OFFSET_BIT]
end

#utc_to_local(time) ⇒ Time Also known as: time

Note:

The resulting time is always a UTC time. If you would like a time with the appropriate offset, use ‘#time_with_offset` instead.

Converts the given time to the local timezone and does not include a UTC offset in the result.

Parameters:

  • time (#to_time) —

    the source time

Returns:

  • (Time) —

    the time in the local timezone



61
62
63
64
65
 
# File 'lib/timezone/zone.rb', line 61

def utc_to_local(time)
  time = sanitize(time)

  (time + utc_offset(time)).utc
end

#valid? ⇒ true

If this is a valid timezone.

Returns:

  • (true) —

    if this is a valid timezone



31
32
33
 
# File 'lib/timezone/zone.rb', line 31

def valid?
  true
end