timezone 0.6.0 → 0.99.0

data/lib/timezone/zone.rb

@@ -6,144 +6,267 @@ require 'timezone/loader'
 require 'timezone/error'
 require 'timezone/configure'
 require 'timezone/active_support'
+require 'timezone/loader'
+require 'timezone/deprecate'
 
 module Timezone
+  # 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.
   class Zone
     include Comparable
-    attr_reader :rules, :zone
+
+    # @return [String] the timezone name
+    attr_reader :name
+
+    alias to_s name
+
+    # @return [String] a developer friendly representation of the object
+    def inspect
+      "#<Timezone::Zone name: \"#{name}\">"
+    end
+
+    # If this is a valid timezone.
+    #
+    # @return [true] if this is a valid timezone
+    def valid?
+      true
+    end
 
     SOURCE_BIT = 0
+    private_constant :SOURCE_BIT
     NAME_BIT = 1
+    private_constant :NAME_BIT
     DST_BIT = 2
+    private_constant :DST_BIT
     OFFSET_BIT = 3
+    private_constant :OFFSET_BIT
 
-    # Create a new Timezone object.
-    #
-    #   Timezone.new(options)
+    # Create a new timezone object using the timezone name.
     #
-    # :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.
-    def initialize options
-      if options.has_key?(:lat) && options.has_key?(:lon)
+    # @param name [String] the timezone name
+    # @return [Timezone::Zone]
+    def initialize(name)
+      if name.is_a?(Hash)
+        legacy_initialize(name)
+      else
+        @name = name
+      end
+    end
+
+    # @deprecated This method will be replaced with `Zone#name` in
+    #   future versions of this gem.
+    def zone
+      Deprecate.call(
+        self.class,
+        :zone,
+        '[DEPRECATED] `Zone#zone` will not be available in ' \
+          'the next release of the `timezone` gem. Use `Zone#name` ' \
+          'instead.'.freeze
+      )
+
+      name
+    end
+
+    # @deprecated This method will be removed in the next release.
+    def rules
+      Deprecate.call(
+        self.class,
+        :rules,
+        '[DEPRECATED] `Zone#rules` will not be available in ' \
+          'the next release of the `timezone` gem.'.freeze
+      )
+
+      private_rules
+    end
+
+    # @deprecated This functionality only exists for migration purposes.
+    def legacy_initialize(options)
+      Deprecate.call(
+        self.class,
+        :initialize,
+        '[DEPRECATED] Creating Zone objects using an options hash ' \
+          'will be deprecated in the next release of the `timezone` ' \
+          'gem. Use `Timezone::[]`, `Timezone::fetch` or ' \
+          '`Timezone::lookup` instead.'.freeze
+      )
+
+      if options.key?(:lat) && options.key?(:lon)
         options[:zone] = timezone_id options[:lat], options[:lon]
-      elsif options.has_key?(:latlon)
+      elsif options.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?
+      if options[:zone].nil?
+        raise Timezone::Error::NilZone,
+          'No zone was found. Please specify a zone.'.freeze
+      end
 
-      @zone = options[:zone]
-      @rules = Timezone::Loader.load(@zone)
+      @name = options[:zone]
+      private_rules
     end
 
+    # @deprecated This functionality will be removed in the next release.
     def active_support_time_zone
-      @active_support_time_zone ||= Timezone::ActiveSupport.format(@zone)
+      Deprecate.call(
+        self.class,
+        :active_support_time_zone,
+        '[DEPRECATED] `Zone#active_support_time_zone` will be ' \
+          'deprecated in the next release of the `timezone` gem. There ' \
+          'will be no replacement.'.freeze
+      )
+
+      @active_support_time_zone ||=
+        Timezone::ActiveSupport.format(name, :internal)
     end
 
-    # Determine the time in the timezone.
-    #
-    #   timezone.time(reference)
+    # Converts the given time to the local timezone and does not include
+    # a UTC offset in the result.
     #
-    # reference - The Time you want to convert.
+    # @param time [#to_time] the source time
+    # @return [Time] the time in the local timezone
     #
-    # 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.
-    def time(reference)
-      reference = sanitize(reference)
+    # @note The resulting time is always a UTC time. If you would  like
+    #       a time with the appropriate offset, use `#time_with_offset`
+    #       instead.
+    def utc_to_local(time)
+      time = sanitize(time)
 
-      reference.utc + utc_offset(reference)
+      time.utc + utc_offset(time)
     end
 
-    alias utc_to_local time
+    alias time utc_to_local
 
-    # Determine the UTC time for a given time in the timezone.
+    # Converts the given local time to the UTC equivalent.
+    #
+    # @param time [#to_time] the local time
+    # @return [Time] the time in UTC
+    #
+    # @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.
     #
-    #     timezone.local_to_utc(time)
+    # @note A note about the handling of time arguments.
     #
-    # 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.
+    #   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`.
     def local_to_utc(time)
       time = sanitize(time)
 
       time.utc - rule_for_local(time).rules.first[OFFSET_BIT]
     end
 
-    # Determine the time in the timezone w/ the appropriate offset.
-    #
-    #     timezone.time_with_offset(reference)
+    # Converts the given time to the local timezone and includes the UTC
+    # offset in the result.
     #
-    # 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.
-    def time_with_offset(reference)
-      reference = sanitize(reference)
+    # @param time [#to_time] the source time
+    # @return [Time] the time in the local timezone with the UTC offset
+    def time_with_offset(time)
+      time = sanitize(time)
 
-      utc = time(reference)
-      offset = utc_offset(reference)
+      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
 
-    # Whether or not the time in the timezone is in DST.
-    def dst?(reference)
-      reference = sanitize(reference)
+    # If, at the given time, the timezone was observing Daylight Savings.
+    #
+    # @param time [#to_time] the source time
+    # @return [Boolean] whether the timezone, at the given time, was
+    #                   observing Daylight Savings Time
+    def dst?(time)
+      time = sanitize(time)
 
-      rule_for_utc(reference)[DST_BIT]
+      rule_for_utc(time)[DST_BIT]
     end
 
-    # Get the current UTC offset in seconds for this timezone.
+    # Return the UTC offset (in seconds) for the given time.
     #
-    #   timezone.utc_offset(reference)
-    def utc_offset(reference=Time.now)
-      reference = sanitize(reference)
+    # @param time [#to_time] (Time.now) the source time
+    # @return [Integer] the UTC offset (in seconds) in the local timezone
+    def utc_offset(time = nil)
+      time ||= Time.now
+      time = sanitize(time)
 
-      rule_for_utc(reference)[OFFSET_BIT]
+      rule_for_utc(time)[OFFSET_BIT]
     end
 
-    def <=>(zone) #:nodoc:
-      utc_offset <=> zone.utc_offset
+    # Compare one timezone with another based on current UTC offset.
+    #
+    # @param other [Timezone::Zone] the other timezone
+    #
+    # @return [-1, 0, 1, nil] comparison based on current `utc_offset`.
+    def <=>(other)
+      return nil unless other.respond_to?(:utc_offset)
+
+      utc_offset <=> other.utc_offset
     end
 
     class << self
-      # Instantly grab all possible time zone names.
+      # @deprecated This method will be replaced with `Timezone.names`
+      #   in future versions of this gem.
       def names
-        Timezone::Loader.names
+        Deprecate.call(
+          self,
+          :names,
+          '[DEPRECATED] `::Timezone::Zone.names` will be removed in ' \
+            'the next gem release. Use `::Timezone.names` instead.'.freeze
+        )
+
+        Loader.names
       end
 
-      # 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.
-      #
+      # @deprecated This functionality will be removed in the next release.
       def list(*args)
+        Deprecate.call(
+          self,
+          :list,
+          '[DEPRECATED] `Zone::list` will be deprecated in the ' \
+            'next release of the `timezone` gem. There will be no ' \
+            'replacement.'.freeze
+        )
+
         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 = args || Configure.default_for_list || names
+        list = names.select { |name| zones.include? name }
 
         @zones = []
         now = Time.now
-        list.each do |zone|
-          item = Zone.new(zone: zone)
+        list.each do |name|
+          item = new(name)
           @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)
+            zone: item.name,
+            title: Configure.replacements[item.name] || item.name,
+            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] }
@@ -152,8 +275,12 @@ module Timezone
 
     private
 
-    def sanitize(reference)
-      reference.to_time
+    def private_rules
+      @rules ||= Loader.load(name)
+    end
+
+    def sanitize(time)
+      time.to_time
     end
 
     # Does the given time (in seconds) match this rule?
@@ -165,6 +292,7 @@ module Timezone
     end
 
     RuleSet = Struct.new(:type, :rules)
+    private_constant :RuleSet
 
     def rule_for_local(local)
       local = local.utc if local.respond_to?(:utc)
@@ -172,17 +300,17 @@ module Timezone
 
       # For each rule, convert the local time into the UTC equivalent for
       # that rule offset, and then check if the UTC time matches the rule.
-      index = binary_search(local){ |t,r| match?(t-r[OFFSET_BIT], r) }
-      match = @rules[index]
+      index = binary_search(local) { |t, r| match?(t - r[OFFSET_BIT], r) }
+      match = private_rules[index]
 
-      utc = local-match[OFFSET_BIT]
+      utc = local - match[OFFSET_BIT]
 
       # If the UTC rule for the calculated UTC time does not map back to the
       # same rule, then we have a skip in time and there is no applicable rule.
       return RuleSet.new(:missing, [match]) if rule_for_utc(utc) != match
 
       # If the match is the last rule, then return it.
-      return RuleSet.new(:single, [match]) if index == @rules.length-1
+      return RuleSet.new(:single, [match]) if index == private_rules.length - 1
 
       # If the UTC equivalent time falls within the last hour(s) of the time
       # change which were replayed during a fall-back in time, then return
@@ -200,43 +328,46 @@ module Timezone
       #
       #     Since both rules provide valid mappings for the local time,
       #     we need to return both values.
-      if utc > match[SOURCE_BIT] - match[OFFSET_BIT] + @rules[index+1][OFFSET_BIT]
-        RuleSet.new(:double, @rules[index..(index+1)])
+      last_hour =
+        match[SOURCE_BIT] -
+        match[OFFSET_BIT] +
+        private_rules[index + 1][OFFSET_BIT]
+
+      if utc > last_hour
+        RuleSet.new(:double, private_rules[index..(index + 1)])
       else
         RuleSet.new(:single, [match])
       end
     end
 
-    def rule_for_utc(time) #:nodoc:
+    def rule_for_utc(time)
       time = time.utc if time.respond_to?(:utc)
       time = time.to_i
 
-      return @rules[binary_search(time){ |t,r| match?(t,r) }]
+      private_rules[binary_search(time) { |t, r| match?(t, r) }]
     end
 
     # Find the first rule that matches using binary search.
-    def binary_search(time, from=0, to=nil, &block)
-      to = @rules.length-1 if to.nil?
+    def binary_search(time, from = 0, to = nil, &block)
+      to = private_rules.length - 1 if to.nil?
 
       return from if from == to
 
       mid = (from + to) / 2
 
-      if block.call(time, @rules[mid])
+      if yield(time, private_rules[mid])
         return mid if mid == 0
 
-        if !block.call(time, @rules[mid-1])
-          return mid
-        else
-          return binary_search(time, from, mid-1, &block)
-        end
+        return mid unless yield(time, private_rules[mid - 1])
+
+        binary_search(time, from, mid - 1, &block)
       else
         return binary_search(time, mid + 1, to, &block)
       end
     end
 
-    def timezone_id(lat, lon) #:nodoc:
-      Timezone::Configure.lookup.lookup(lat,lon)
+    def timezone_id(lat, lon)
+      Timezone::Configure.lookup.lookup(lat, lon)
     end
   end
 end

data/lib/timezone.rb

@@ -1,3 +1,77 @@
 require 'timezone/zone'
+require 'timezone/nil_zone'
+require 'timezone/lookup'
+require 'timezone/loader'
 
-module Timezone; end
+# Main entry point for all timezone related functionality.
+module Timezone
+  # A list of all timezone names.
+  #
+  # @return [Array<String>] all the timezone names
+  def self.names
+    Loader.names
+  end
+
+  # Retrieve a timezone by name.
+  #
+  # @param name [String] the timezone name
+  #
+  # @return [Timezone::Zone] if the timezone is found
+  # @return [Timezone::NilZone] if the timezone is not found
+  def self.[](name)
+    fetch(name) { ::Timezone::NilZone.new }
+  end
+
+  # Fetch a timezone by name.
+  #
+  # @param name [String] the timezone name
+  # @param default an object to return if timezone is
+  #   not found
+  # @yield the block to run if the timezone is not found
+  # @yieldparam name [String] the timezone name if the timezone is not
+  #   found
+  #
+  # @return [Timezone::Zone] if the timezone is found
+  # @return [Object] if the timezone is not found and a default
+  #   value or block has been provided
+  #
+  # @raise [Timezone::Error::InvalidZone] if the timezone is not found
+  #   and a default value and block have not been provided
+  def self.fetch(name, default = :__block, &block)
+    return ::Timezone::Zone.new(name) if Loader.valid?(name)
+
+    if block_given? && default != :__block
+      warn('warning: block supersedes default value argument'.freeze)
+    end
+
+    return block.call(name) if block_given?
+    return default unless default == :__block
+
+    raise ::Timezone::Error::InvalidZone
+  end
+
+  # Lookup a timezone name by (lat, long) and then fetch the
+  # timezone object.
+  #
+  # @param lat [Double] the latitude coordinate
+  # @param long [Double] the longitude coordinate
+  # @param default an optional object to return if the remote lookup
+  #   succeeds but the timezone is not found
+  # @yield the block to run if the remote lookup succeeds and the
+  #   timezone is not found
+  # @yieldparam name [String] the timezone name if the remote lookup
+  #   succeeds and the timezone is not found
+  #
+  # @return [Timezone::Zone] if the remote lookup succeeds and the
+  #   timezone is found
+  # @return [Object] if the remote lookup succeeds, the timezone is
+  #   not found, and a default value or block has been provided
+  #
+  # @raise [Timezone::Error::InvalidZone] if the remote lookup
+  #   succeeds but the resulting timezone is not found and a default
+  #   value or block has not been provided
+  # @raise [Timezone::Error::Lookup] if the remote lookup fails
+  def self.lookup(lat, long, default = :__block, &block)
+    fetch(::Timezone::Lookup.lookup.lookup(lat, long), default, &block)
+  end
+end

data/test/basic_lookup_test.rb

@@ -12,12 +12,12 @@ class BasicLookupTest < ::Minitest::Unit::TestCase
 
   def test_missing_protocol
     config.protocol = nil
-    assert_raises(::Timezone::Error::InvalidConfig){ lookup }
+    assert_raises(::Timezone::Error::InvalidConfig) { lookup }
   end
 
   def test_missing_url
     config.url = nil
-    assert_raises(::Timezone::Error::InvalidConfig){ lookup }
+    assert_raises(::Timezone::Error::InvalidConfig) { lookup }
   end
 
   def test_initialization

data/test/geonames_lookup_test.rb

@@ -17,24 +17,31 @@ class GeonamesLookupTest < ::Minitest::Unit::TestCase
   end
 
   def lookup
-    ::Timezone::Lookup::Geonames.new(Timezone::Configure)
+    ::Timezone::Configure.lookup
+  end
+
+  def clear
+    Timezone::Configure.instance_variable_set(:@lookup, nil)
+    Timezone::Configure.instance_variable_set(:@google_lookup, nil)
+    Timezone::Configure.instance_variable_set(:@geonames_lookup, nil)
   end
 
   def test_missing_username
-    Timezone::Configure.begin{ |c| c.username = nil }
-    assert_raises(::Timezone::Error::InvalidConfig){ lookup }
+    clear
+    Timezone::Configure.begin { |c| c.username = nil }
+    assert_raises(::Timezone::Error::InvalidConfig) { lookup }
   ensure
-    Timezone::Configure.begin{ |c| c.username = 'timezone' }
+    Timezone::Configure.begin { |c| c.username = 'timezone' }
   end
 
   def test_lookup
-    HTTPTestClient.body = File.open(mock_path + '/lat_lon_coords.txt').read
+    lookup.client.body = File.open(mock_path + '/lat_lon_coords.txt').read
 
     assert_equal 'Australia/Adelaide', lookup.lookup(*coordinates)
   end
 
   def test_api_limit
-    HTTPTestClient.body = File.open(mock_path + '/api_limit_reached.txt').read
+    lookup.client.body = File.open(mock_path + '/api_limit_reached.txt').read
 
     assert_raises Timezone::Error::GeoNames, 'api limit reached' do
       lookup.lookup(*coordinates)