geokit 1.6.0 → 1.6.5

data/lib/geokit/mappable.rb

@@ -1,15 +1,15 @@
 #require 'forwardable'
 
-module Geokit     
+module Geokit
   # Contains class and instance methods providing distance calcuation services.  This
   # module is meant to be mixed into classes containing lat and lng attributes where
-  # distance calculation is desired.  
-  # 
+  # distance calculation is desired.
+  #
   # At present, two forms of distance calculations are provided:
-  # 
+  #
   # * Pythagorean Theory (flat Earth) - which assumes the world is flat and loses accuracy over long distances.
   # * Haversine (sphere) - which is fairly accurate, but at a performance cost.
-  # 
+  #
   # Distance units supported are :miles, :kms, and :nms.
   module Mappable
     PI_DIV_RAD = 0.0174
@@ -21,13 +21,13 @@ module Geokit
     MILES_PER_LATITUDE_DEGREE = 69.1
     KMS_PER_LATITUDE_DEGREE = MILES_PER_LATITUDE_DEGREE * KMS_PER_MILE
     NMS_PER_LATITUDE_DEGREE = MILES_PER_LATITUDE_DEGREE * NMS_PER_MILE
-    LATITUDE_DEGREES = EARTH_RADIUS_IN_MILES / MILES_PER_LATITUDE_DEGREE  
-    
+    LATITUDE_DEGREES = EARTH_RADIUS_IN_MILES / MILES_PER_LATITUDE_DEGREE
+
     # Mix below class methods into the includer.
     def self.included(receiver) # :nodoc:
       receiver.extend ClassMethods
-    end   
-    
+    end
+
     module ClassMethods #:nodoc:
       # Returns the distance between two points.  The from and to parameters are
       # required to have lat and lng attributes.  Valid options are:
@@ -42,21 +42,21 @@ module Geokit
         case formula
         when :sphere
           begin
-            units_sphere_multiplier(units) * 
-                Math.acos( Math.sin(deg2rad(from.lat)) * Math.sin(deg2rad(to.lat)) + 
-                Math.cos(deg2rad(from.lat)) * Math.cos(deg2rad(to.lat)) * 
+            units_sphere_multiplier(units) *
+                Math.acos( Math.sin(deg2rad(from.lat)) * Math.sin(deg2rad(to.lat)) +
+                Math.cos(deg2rad(from.lat)) * Math.cos(deg2rad(to.lat)) *
                 Math.cos(deg2rad(to.lng) - deg2rad(from.lng)))
           rescue Errno::EDOM
             0.0
           end
         when :flat
-          Math.sqrt((units_per_latitude_degree(units)*(from.lat-to.lat))**2 + 
+          Math.sqrt((units_per_latitude_degree(units)*(from.lat-to.lat))**2 +
               (units_per_longitude_degree(from.lat, units)*(from.lng-to.lng))**2)
         end
       end
 
       # Returns heading in degrees (0 is north, 90 is east, 180 is south, etc)
-      # from the first point to the second point. Typicaly, the instance methods will be used 
+      # from the first point to the second point. Typicaly, the instance methods will be used
       # instead of this method.
       def heading_between(from,to)
         from=Geokit::LatLng.normalize(from)
@@ -64,12 +64,12 @@ module Geokit
 
         d_lng=deg2rad(to.lng-from.lng)
         from_lat=deg2rad(from.lat)
-        to_lat=deg2rad(to.lat) 
+        to_lat=deg2rad(to.lat)
         y=Math.sin(d_lng) * Math.cos(to_lat)
         x=Math.cos(from_lat)*Math.sin(to_lat)-Math.sin(from_lat)*Math.cos(to_lat)*Math.cos(d_lng)
         heading=to_heading(Math.atan2(y,x))
       end
-  
+
       # Given a start point, distance, and heading (in degrees), provides
       # an endpoint. Returns a LatLng instance. Typically, the instance method
       # will be used instead of this method.
@@ -80,12 +80,12 @@ module Geokit
           when :nms; EARTH_RADIUS_IN_NMS
           else EARTH_RADIUS_IN_MILES
         end
-        start=Geokit::LatLng.normalize(start)        
+        start=Geokit::LatLng.normalize(start)
         lat=deg2rad(start.lat)
         lng=deg2rad(start.lng)
         heading=deg2rad(heading)
         distance=distance.to_f
-        
+
         end_lat=Math.asin(Math.sin(lat)*Math.cos(distance/radius) +
                           Math.cos(lat)*Math.sin(distance/radius)*Math.cos(heading))
 
@@ -95,7 +95,7 @@ module Geokit
         LatLng.new(rad2deg(end_lat),rad2deg(end_lng))
       end
 
-      # Returns the midpoint, given two points. Returns a LatLng. 
+      # Returns the midpoint, given two points. Returns a LatLng.
       # Typically, the instance method will be used instead of this method.
       # Valid option:
       #   :units - valid values are :miles, :kms, or :nms (:miles is the default)
@@ -103,29 +103,29 @@ module Geokit
         from=Geokit::LatLng.normalize(from)
 
         units = options[:units] || Geokit::default_units
-        
+
         heading=from.heading_to(to)
         distance=from.distance_to(to,options)
         midpoint=from.endpoint(heading,distance/2,options)
       end
-  
+
       # Geocodes a location using the multi geocoder.
       def geocode(location, options = {})
         res = Geocoders::MultiGeocoder.geocode(location, options)
         return res if res.success?
-        raise Geokit::Geocoders::GeocodeError      
+        raise Geokit::Geocoders::GeocodeError
       end
-    
+
       protected
-    
+
       def deg2rad(degrees)
         degrees.to_f / 180.0 * Math::PI
       end
-      
+
       def rad2deg(rad)
-        rad.to_f * 180.0 / Math::PI 
+        rad.to_f * 180.0 / Math::PI
       end
-      
+
       def to_heading(rad)
         (rad2deg(rad)+360)%360
       end
@@ -147,7 +147,7 @@ module Geokit
           else MILES_PER_LATITUDE_DEGREE
         end
       end
-    
+
       # Returns the number units per longitude degree.
       def units_per_longitude_degree(lat, units)
         miles_per_longitude_degree = (LATITUDE_DEGREES * Math.cos(lat * PI_DIV_RAD)).abs
@@ -156,13 +156,13 @@ module Geokit
           when :nms; miles_per_longitude_degree * NMS_PER_MILE
           else miles_per_longitude_degree
         end
-      end  
+      end
     end
-  
+
     # -----------------------------------------------------------------------------------------------
     # Instance methods below here
     # -----------------------------------------------------------------------------------------------
-  
+
     # Extracts a LatLng instance. Use with models that are acts_as_mappable
     def to_lat_lng
       return self if instance_of?(Geokit::LatLng) || instance_of?(Geokit::GeoLoc)
@@ -176,38 +176,38 @@ module Geokit
     # :formula - valid values are :flat or :sphere (:sphere is the default)
     def distance_to(other, options={})
       self.class.distance_between(self, other, options)
-    end  
+    end
     alias distance_from distance_to
 
     # Returns heading in degrees (0 is north, 90 is east, 180 is south, etc)
-    # to the given point. The given point can be a LatLng or a string to be Geocoded 
+    # to the given point. The given point can be a LatLng or a string to be Geocoded
     def heading_to(other)
       self.class.heading_between(self,other)
     end
 
     # Returns heading in degrees (0 is north, 90 is east, 180 is south, etc)
-    # FROM the given point. The given point can be a LatLng or a string to be Geocoded 
+    # FROM the given point. The given point can be a LatLng or a string to be Geocoded
     def heading_from(other)
       self.class.heading_between(other,self)
     end
- 
-    # Returns the endpoint, given a heading (in degrees) and distance.  
+
+    # Returns the endpoint, given a heading (in degrees) and distance.
     # Valid option:
     # :units - valid values are :miles, :kms, or :nms (:miles is the default)
     def endpoint(heading,distance,options={})
-      self.class.endpoint(self,heading,distance,options)  
+      self.class.endpoint(self,heading,distance,options)
     end
 
-    # Returns the midpoint, given another point on the map.  
+    # Returns the midpoint, given another point on the map.
     # Valid option:
-    # :units - valid values are :miles, :kms, or :nms (:miles is the default)    
+    # :units - valid values are :miles, :kms, or :nms (:miles is the default)
     def midpoint_to(other, options={})
       self.class.midpoint_between(self,other,options)
     end
-    
+
   end
 
-  class LatLng 
+  class LatLng
     include Mappable
 
     attr_accessor :lat, :lng
@@ -219,7 +219,7 @@ module Geokit
       lng = lng.to_f if lng && !lng.is_a?(Numeric)
       @lat = lat
       @lng = lng
-    end 
+    end
 
     # Latitude attribute setter; stored as a float.
     def lat=(lat)
@@ -229,18 +229,18 @@ module Geokit
     # Longitude attribute setter; stored as a float;
     def lng=(lng)
       @lng=lng.to_f if lng
-    end  
+    end
 
     # Returns the lat and lng attributes as a comma-separated string.
     def ll
       "#{lat},#{lng}"
     end
-    
+
     #returns a string with comma-separated lat,lng values
     def to_s
       ll
     end
-  
+
     #returns a two-element array
     def to_a
       [lat,lng]
@@ -250,15 +250,20 @@ module Geokit
     def ==(other)
       other.is_a?(LatLng) ? self.lat == other.lat && self.lng == other.lng : false
     end
-    
+
     def hash
       lat.hash + lng.hash
     end
-    
+
     def eql?(other)
       self == other
     end
-    
+
+    # Returns true if both lat and lng attributes are defined
+    def valid?
+      self.lat and self.lng
+    end
+
     # A *class* method to take anything which can be inferred as a point and generate
     # a LatLng from it. You should use this anything you're not sure what the input is,
     # and want to deal with it as a LatLng if at all possible. Can take:
@@ -271,7 +276,7 @@ module Geokit
     def self.normalize(thing,other=nil)
       # if an 'other' thing is supplied, normalize the input by creating an array of two elements
       thing=[thing,other] if other
-      
+
       if thing.is_a?(String)
         thing.strip!
         if match=thing.match(/(\-?\d+\.?\d*)[, ] ?(\-?\d+\.?\d*)$/)
@@ -279,7 +284,7 @@ module Geokit
         else
           res = Geokit::Geocoders::MultiGeocoder.geocode(thing)
           return res if res.success?
-          raise Geokit::Geocoders::GeocodeError  
+          raise Geokit::Geocoders::GeocodeError
         end
       elsif thing.is_a?(Array) && thing.size==2
         return Geokit::LatLng.new(thing[0],thing[1])
@@ -290,16 +295,16 @@ module Geokit
       elsif thing.respond_to? :to_lat_lng
         return thing.to_lat_lng
       end
-      
+
       raise ArgumentError.new("#{thing} (#{thing.class}) cannot be normalized to a LatLng. We tried interpreting it as an array, string, Mappable, etc., but no dice.")
     end
-    
+
     # Reverse geocodes a LatLng object using the MultiGeocoder (default), or optionally
     # using a geocoder of your choosing. Returns a new Geokit::GeoLoc object
-    # 
+    #
     # ==== Options
     # * :using  - Specifies the geocoder to use for reverse geocoding. Defaults to
-    #             MultiGeocoder. Can be either the geocoder class (or any class that 
+    #             MultiGeocoder. Can be either the geocoder class (or any class that
     #             implements do_reverse_geocode for that matter), or the name of
     #             the class without the "Geocoder" part (e.g. :google)
     #
@@ -315,19 +320,19 @@ module Geokit
       else
         raise ArgumentError.new("#{options[:using]} is not a valid geocoder.")
       end
-      
+
       provider.send(:reverse_geocode, self)
     end
   end
 
   # This class encapsulates the result of a geocoding call.
   # It's primary purpose is to homogenize the results of multiple
-  # geocoding providers. It also provides some additional functionality, such as 
-  # the "full address" method for geocoders that do not provide a 
+  # geocoding providers. It also provides some additional functionality, such as
+  # the "full address" method for geocoders that do not provide a
   # full address in their results (for example, Yahoo), and the "is_us" method.
   #
   # Some geocoders can return multple results. Geoloc can capture multiple results through
-  # its "all" method. 
+  # its "all" method.
   #
   # For the geocoder setting the results, it would look something like this:
   #     geo=GeoLoc.new(first_result)
@@ -345,28 +350,30 @@ module Geokit
     # Location attributes.  Full address is a concatenation of all values.  For example:
     # 100 Spear St, San Francisco, CA, 94101, US
     # Street number and street name are extracted from the street address attribute if they don't exist
-    attr_accessor :street_number,:street_name,:street_address, :city, :state, :zip, :country_code, :country, :full_address, :all, :district, :province
+    attr_accessor :street_number, :street_name, :street_address, :city, :state, :zip, :country_code, :country
+    attr_accessor :full_address, :all, :district, :province, :sub_premise
     # Attributes set upon return from geocoding.  Success will be true for successful
     # geocode lookups.  The provider will be set to the name of the providing geocoder.
     # Finally, precision is an indicator of the accuracy of the geocoding.
     attr_accessor :success, :provider, :precision, :suggested_bounds
-    # accuracy is set for Yahoo and Google geocoders, it is a numeric value of the 
+    # accuracy is set for Yahoo and Google geocoders, it is a numeric value of the
     # precision. see http://code.google.com/apis/maps/documentation/geocoding/#GeocodingAccuracy
     attr_accessor :accuracy
     # FCC Attributes
     attr_accessor :district_fips, :state_fips, :block_fips
-    
+
 
     # Constructor expects a hash of symbols to correspond with attributes.
     def initialize(h={})
       @all = [self]
-      
-      @street_address=h[:street_address] 
+
+      @street_address=h[:street_address]
+      @sub_premise=nil
       @street_number=nil
       @street_name=nil
-      @city=h[:city] 
-      @state=h[:state] 
-      @zip=h[:zip] 
+      @city=h[:city]
+      @state=h[:state]
+      @zip=h[:zip]
       @country_code=h[:country_code]
       @province = h[:province]
       @success=false
@@ -379,7 +386,7 @@ module Geokit
     def is_us?
       country_code == 'US'
     end
-    
+
     def success?
       success == true
     end
@@ -406,7 +413,9 @@ module Geokit
     # gives you all the important fields as key-value pairs
     def hash
       res={}
-      [:success,:lat,:lng,:country_code,:city,:state,:zip,:street_address,:province,:district,:provider,:full_address,:is_us?,:ll,:precision,:district_fips,:state_fips,:block_fips].each { |s| res[s] = self.send(s.to_s) }
+      [:success, :lat, :lng, :country_code, :city, :state, :zip, :street_address, :province,
+       :district, :provider, :full_address, :is_us?, :ll, :precision, :district_fips, :state_fips,
+       :block_fips, :sub_premise].each { |s| res[s] = self.send(s.to_s) }
       res
     end
     alias to_hash hash
@@ -419,20 +428,20 @@ module Geokit
     # Sets the street address after capitalizing each word within the street address.
     def street_address=(address)
       if address and not ['google','google3'].include?(self.provider)
-        @street_address = Geokit::Inflector::titleize(address) 
+        @street_address = Geokit::Inflector::titleize(address)
       else
         @street_address = address
       end
-    end  
-    
+    end
+
     # Returns a comma-delimited string consisting of the street address, city, state,
     # zip, and country code.  Only includes those attributes that are non-blank.
     def to_geocodeable_s
       a=[street_address, district, city, province, state, zip, country_code].compact
       a.delete_if { |e| !e || e == '' }
-      a.join(', ')      
+      a.join(', ')
     end
-    
+
     def to_yaml_properties
       (instance_variables - ['@all']).sort
     end
@@ -442,33 +451,33 @@ module Geokit
       "Provider: #{provider}\nStreet: #{street_address}\nCity: #{city}\nState: #{state}\nZip: #{zip}\nLatitude: #{lat}\nLongitude: #{lng}\nCountry: #{country_code}\nSuccess: #{success}"
     end
   end
-  
+
   # Bounds represents a rectangular bounds, defined by the SW and NE corners
   class Bounds
     # sw and ne are LatLng objects
     attr_accessor :sw, :ne
-    
+
     # provide sw and ne to instantiate a new Bounds instance
     def initialize(sw,ne)
       raise ArgumentError if !(sw.is_a?(Geokit::LatLng) && ne.is_a?(Geokit::LatLng))
       @sw,@ne=sw,ne
     end
-    
+
     #returns the a single point which is the center of the rectangular bounds
     def center
       @sw.midpoint_to(@ne)
     end
-  
+
     # a simple string representation:sw,ne
     def to_s
-      "#{@sw.to_s},#{@ne.to_s}"   
+      "#{@sw.to_s},#{@ne.to_s}"
     end
-    
+
     # a two-element array of two-element arrays: sw,ne
     def to_a
       [@sw.to_a, @ne.to_a]
     end
-    
+
     # Returns true if the bounds contain the passed point.
     # allows for bounds which cross the meridian
     def contains?(point)
@@ -481,10 +490,10 @@ module Geokit
       end
       res
     end
-    
+
     # returns true if the bounds crosses the international dateline
     def crosses_meridian?
-      @sw.lng > @ne.lng 
+      @sw.lng > @ne.lng
     end
 
     # Returns true if the candidate object is logically equal.  Logical equivalence
@@ -492,7 +501,7 @@ module Geokit
     def ==(other)
       other.is_a?(Bounds) ? self.sw == other.sw && self.ne == other.ne : false
     end
-    
+
     # Equivalent to Google Maps API's .toSpan() method on GLatLng's.
     #
     # Returns a LatLng object, whose coordinates represent the size of a rectangle
@@ -502,9 +511,9 @@ module Geokit
       lng_span = (crosses_meridian? ? 360 + @ne.lng - @sw.lng : @ne.lng - @sw.lng).abs
       Geokit::LatLng.new(lat_span, lng_span)
     end
-    
+
     class <<self
-      
+
       # returns an instance of bounds which completely encompases the given circle
       def from_point_and_radius(point,radius,options={})
         point=LatLng.normalize(point)
@@ -516,18 +525,18 @@ module Geokit
         ne=Geokit::LatLng.new(p0.lat,p90.lng)
         Geokit::Bounds.new(sw,ne)
       end
-      
+
       # Takes two main combinations of arguments to create a bounds:
       # point,point   (this is the only one which takes two arguments
       # [point,point]
       # . . . where a point is anything LatLng#normalize can handle (which is quite a lot)
       #
       # NOTE: everything combination is assumed to pass points in the order sw, ne
-      def normalize (thing,other=nil)   
+      def normalize (thing,other=nil)
         # maybe this will be simple -- an actual bounds object is passed, and we can all go home
         return thing if thing.is_a? Bounds
-        
-        # no? OK, if there's no "other," the thing better be a two-element array        
+
+        # no? OK, if there's no "other," the thing better be a two-element array
         thing,other=thing if !other && thing.is_a?(Array) && thing.size==2
 
         # Now that we're set with a thing and another thing, let LatLng do the heavy lifting.