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



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

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



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

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`.



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

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



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

def valid?
  true
end