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



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

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



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

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



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

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

  utc_offset <=> other.utc_offset
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



131
132
133
134
135
 
# File 'lib/timezone/zone.rb', line 131

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



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

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



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

def local_to_utc(time)
  time = sanitize(time)

  time.utc - rule_for_local(time).rules.first[OFFSET_BIT]
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



118
119
120
121
122
123
124
 
# File 'lib/timezone/zone.rb', line 118

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, 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



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

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



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

def utc_to_local(time)
  time = sanitize(time)

  time.utc + utc_offset(time)
end

#valid? ⇒ true

If this is a valid timezone.

Returns:

  • (true) —

    if this is a valid timezone



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

def valid?
  true
end