Class: Timezone::Zone

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

Defined Under Namespace

Classes: RuleSet

Constant Summary collapse

SOURCE_BIT = 
0
NAME_BIT = 
1
DST_BIT = 
2
OFFSET_BIT = 
3

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ Zone

Create a new Timezone object.

Timezone.new(options)

:zone - The actual name of the zone. For example, Australia/Sydney or Americas/Los_Angeles. :lat, :lon - The latitude and longitude of the location. :latlon - The array of latitude and longitude of the location.

If a latitude and longitude is passed in, the Timezone object will do a lookup for the actual zone name and then use that as a reference. It will then load the appropriate json timezone information for that zone, and compile a list of the timezone rules.

Raises:



31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/timezone/zone.rb', line 31

def initialize options
  if options.has_key?(:lat) && options.has_key?(:lon)
    options[:zone] = timezone_id options[:lat], options[:lon]
  elsif options.has_key?(:latlon)
    options[:zone] = timezone_id(*options[:latlon])
  end

  raise Timezone::Error::NilZone, 'No zone was found. Please specify a zone.' if options[:zone].nil?

  @zone = options[:zone]
  @rules = Timezone::Loader.load(@zone)
end

Instance Attribute Details

#rules ⇒ Object (readonly)

Returns the value of attribute rules.



13
14
15
 
# File 'lib/timezone/zone.rb', line 13

def rules
  @rules
end

#zone ⇒ Object (readonly)

Returns the value of attribute zone.



13
14
15
 
# File 'lib/timezone/zone.rb', line 13

def zone
  @zone
end

Class Method Details

.list(*args) ⇒ Object

Get a list of specified timezones and the basic information accompanying that zone

zones = Timezone::Zone.list(*zones)

zones - An array of timezone names. (i.e. Timezone::Zones.list(“America/Chicago”, “Australia/Sydney”))

The result is a Hash of timezones with their title, offset in seconds, UTC offset, and if it uses DST.



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/timezone/zone.rb', line 132

def list(*args)
  args = nil if args.empty? # set to nil if no args are provided
  zones = args || Configure.default_for_list || self.names # get default list
  list = self.names.select { |name| zones.include? name } # only select zones if they exist

  @zones = []
  now = Time.now
  list.each do |zone|
    item = Zone.new(zone: zone)
    @zones << {
      :zone => item.zone,
      :title => Configure.replacements[item.zone] || item.zone,
      :offset => item.utc_offset,
      :utc_offset => (item.utc_offset/(60*60)),
      :dst => item.dst?(now)
    }
  end
  @zones.sort_by! { |zone| zone[Configure.order_list_by] }
end

.names ⇒ Object

Instantly grab all possible time zone names.



120
121
122
 
# File 'lib/timezone/zone.rb', line 120

def names
  Timezone::Loader.names
end

Instance Method Details

#<=>(zone) ⇒ Object

:nodoc:



114
115
116
 
# File 'lib/timezone/zone.rb', line 114

def <=>(zone) #:nodoc:
  utc_offset <=> zone.utc_offset
end

#active_support_time_zone ⇒ Object 



44
45
46
 
# File 'lib/timezone/zone.rb', line 44

def active_support_time_zone
  @active_support_time_zone ||= Timezone::ActiveSupport.format(@zone)
end

#dst?(reference) ⇒ Boolean

Whether or not the time in the timezone is in DST.

Returns:

  • (Boolean) 


99
100
101
102
103
 
# File 'lib/timezone/zone.rb', line 99

def dst?(reference)
  reference = sanitize(reference)

  rule_for_utc(reference)[DST_BIT]
end

#local_to_utc(time) ⇒ Object

Determine the UTC time for a given time in the timezone.

timezone.local_to_utc(time)

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 separate UTC times (during a fall back). All of these cases are ignored here and the best (first) guess is used instead.



73
74
75
76
77
 
# File 'lib/timezone/zone.rb', line 73

def local_to_utc(time)
  time = sanitize(time)

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

#time(reference) ⇒ Object Also known as: utc_to_local

Determine the time in the timezone.

timezone.time(reference)

reference - The Time you want to convert.

The reference is converted to a UTC equivalent. That UTC equivalent is then used to lookup the appropriate offset in the timezone rules. Once the offset has been found that offset is added to the reference UTC time to calculate the reference time in the timezone.



57
58
59
60
61
 
# File 'lib/timezone/zone.rb', line 57

def time(reference)
  reference = sanitize(reference)

  reference.utc + utc_offset(reference)
end

#time_with_offset(reference) ⇒ Object

Determine the time in the timezone w/ the appropriate offset.

timezone.time_with_offset(reference)

reference - the ‘Time` you want to convert.

The reference is converted to a UTC equivalent. That UTC equivalent is then used to lookup the appropriate offset in the timezone rules. Once the offset has been found, that offset is added to the reference UTC time to calculate the reference time in the timezone. The offset is then appended to put the time object into the proper offset.



90
91
92
93
94
95
96
 
# File 'lib/timezone/zone.rb', line 90

def time_with_offset(reference)
  reference = sanitize(reference)

  utc = time(reference)
  offset = utc_offset(reference)
  Time.new(utc.year, utc.month, utc.day, utc.hour, utc.min, utc.sec, offset)
end

#utc_offset(reference = Time.now) ⇒ Object

Get the current UTC offset in seconds for this timezone.

timezone.utc_offset(reference)



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

def utc_offset(reference=Time.now)
  reference = sanitize(reference)

  rule_for_utc(reference)[OFFSET_BIT]
end