area 0.8.0 → 0.9.0

data/lib/area.rb

@@ -31,6 +31,8 @@ module Area
     @zip_codes
   end
 
+  @regions = ["REGION", "NJ", "DC", "CT", "MB", "AL", "WA", "ME", "ID", "CA", "TX", "NY", "PA", "OH", "IL", "MN", "IN", "LA", "ON", "MS", "GA", "MI", "FL", "MD", "BAHAMAS", "BARBADOS", "BC", "NC", "WI", "ANGUILLA", "ANTIGUA AND BARBUDA", "KY", "VA", "BRITISH VIRGIN ISLANDS", "DE", "CO", "WV", "SK", "WY", "NE", "MO", "KS", "IA", "MA", "USVI", "CAYMAN ISLANDS", "RI", "AB", "OK", "MT", "QC", "TN", "UT", "BERMUDA", "RESERVED", "GRENADA", "AR", "AZ", "OR", "NM", "NB", "NH", "SD", "TURKS & CAICOS ISLANDS", "MONTSERRAT", "MP", "GU", "AS", "ND", "NV", "NL", "US GOVERNMENT", "ST. LUCIA", "DOMINICA", "ST. VINCENT & GRENADINES", "PR", "TOLL FREE", "VT", "SC", "HI", "DOMINICAN REPUBLIC", "YT", "TRINIDAD & TOBAGO", "ST. KITTS & NEVIS", "JAMAICA", "TOLL CALLS", "NS", "AK"]
+
   def self.code?(code)
     if code.to_s.length == 3
       return code
@@ -47,4 +49,29 @@ module Area
     end
   end
 
+  def self.zip?(code)
+    if code.to_s.length == 5
+      return code
+    else
+      raise ArgumentError, "You must provide zip code", caller
+    end
+  end
+
+  def self.state_or_territory?(state)
+    if @regions.include?(state.upcase)
+      return state
+    else
+      raise ArgumentError, "You must provide a valid US state abbreviation or territory name", caller
+    end
+  end
+
+  def self.zip_or_territory?(state)
+    if @regions.include?(state.upcase) or Area.zip?(state)
+      return state
+    else
+      raise ArgumentError, "You must provide a valid US state abbreviation or zipcode.", caller
+    end
+  end
+
+
 end

data/lib/area/array.rb

@@ -1,5 +1,18 @@
 class Array
 
+  # Public: Convert an lat/lon pair as an Array to a region.
+  #
+  # options - An optional hash indicating if you would like just the city or just the state.
+  #
+  # Examples
+  #
+  #   ['40.71209', '-73.95427'].to_region
+  #   # => "Brooklyn, NY"
+  #
+  #   ['40.71209', '-73.95427'].to_region(:state => true)
+  #   # => "NY"
+  #
+  # Returns a String representation of the lat/lon pair.
   def to_region(options = {})
     if row = Area.zip_codes.find {|row| row[3] == self[0].to_s and row[4] == self[1].to_s }
       if options[:city]
@@ -12,6 +25,14 @@ class Array
     end
   end
 
+  # Public: Convert a lat/lon pair to a zip code.
+  #
+  # Examples
+  #
+  #   [40.71209, -73.95427].to_zip
+  #   #=> "11211"
+  #
+  # Returns a String of converted places.
   def to_zip
     Area.zip_codes.find do |row|
       if row[3] and row[4]
@@ -28,6 +49,14 @@ class Array
     end
   end
 
+  # Public: Convert a lat/lon pair to its GMT offset.
+  #
+  # Examples
+  #
+  #   [40.71209, -73.95427].to_gmt_offset
+  #   #=> "-5"
+  #
+  # Returns a String representation of the GMT offset.
   def to_gmt_offset
     row = Area.zip_codes.find {|row| row[3] == self[0].to_s and row[4] == self[1].to_s }
     row[5] if row

data/lib/area/integer.rb

@@ -1,5 +1,14 @@
 class Integer
 
+
+  # Public: Convert an area code or to a US state or region.
+  #
+  # Examples
+  #
+  #   646.to_region
+  #   #=> NY
+  #
+  # Returns a String representation of the converted area code.
   def to_region(options = {})
     if Area.code?(self) # presume an area code
       row = Area.area_codes.find{|row| row.first == self.to_s }
@@ -7,29 +16,69 @@ class Integer
     end
   end
 
+
+  # Public: Convert an area code or zipcode to its latitude and longitude.
+  #
+  # Examples
+  #
+  #   11211.to_latlon
+  #   #=> "40.71209, -73.95427"
+  #
+  # Returns a String representation of the lat/lon pair.
   def to_latlon
-    if Area.code_or_zip?(self)
+    if Area.zip?(self)
+      warn "[DEPRECATION] using `to_latlon` with an integer representation of a zipcode is deprecated and will be removed in future versions. Please use a string instead."
       row = Area.zip_codes.find {|row| row.first == self.to_s }
       row[3] + ', ' + row[4] if row
     end
   end
 
+
+  # Public: Convert a zipcode to its latitude.
+  #
+  # Examples
+  #
+  #   11211.to_lat
+  #   #=> "40.71209"
+  #
+  # Returns a String representation of the latitude.
   def to_lat
-    if Area.code_or_zip?(self)
+    if Area.zip?(self)
+      warn "[DEPRECATION] using `to_lat` with an integer representation of a zipcode is deprecated and will be removed in future versions. Please use a string instead."
       row = Area.zip_codes.find {|row| row.first == self.to_s }
       row[3] if row
     end
   end
 
+
+  # Public: Convert a zipcode to its longitude.
+  #
+  # Examples
+  #
+  #   11211.to_lon
+  #   #=> "40.71209"
+  #
+  # Returns a String representation of the longitude.
   def to_lon
-    if Area.code_or_zip?(self)
+    if Area.zip?(self)
+      warn "[DEPRECATION] using `to_lon` with an integer representaion of a zipcode is deprecated and will be removed in future versions. Please use a string instead."
       row = Area.zip_codes.find {|row| row.first == self.to_s }
       row[4] if row
     end
   end
 
+
+  # Public: Convert a zipcode to its GMT offset.
+  #
+  # Examples
+  #
+  #   11211.to_gmt_offset
+  #   #=> "-5"
+  #
+  # Returns a String representation of the GMT offset.
   def to_gmt_offset
-    if Area.code_or_zip?(self)
+    if Area.zip?(self)
+      warn "[DEPRECATION] using `to_gmt` with an integer representaion of a zipcode is deprecated and will be removed in future versions. Please use a string instead."
       row = Area.zip_codes.find {|row| row.first == self.to_s }
       row[5] if row
     end

data/lib/area/string.rb

@@ -1,12 +1,33 @@
 class String
 
+  # Public: Convert a string to an area code.
+  #
+  # Examples
+  #
+  #   "CT".to_area
+  #   # => ["203", "860"]
+  #
+  # Returns an Array of converted area codes.
   def to_area
-    @area_codes = Area.area_codes.find_all {|row| row[1].upcase == self }.map {|a| a.first }
-    @area_codes.length == 1 ? @area_codes.first : @area_codes
+    if Area.state_or_territory?(self)
+      @area_codes = Area.area_codes.find_all {|row| row[1].upcase == self }.map {|a| a.first }
+    end
   end
 
+
+  # Public: Convert an area code or zipcode to a US state or region.
+  #
+  # Examples
+  #
+  #   "646".to_region
+  #   #=> NY
+  #
+  #   "11211".to_region
+  #   #=> "Brooklyn, NY",
+  #
+  # Returns a String of converted area codes or zipcodes.
   def to_region(options = {})
-    if self.to_s.length == 3 # an area code
+    if self.to_s.length == 3  # an area code
       row = Area.area_codes.find {|row| row.first == self.to_s }
       return row.last if row
     elsif self.to_s.length == 5
@@ -26,21 +47,90 @@ class String
     end
   end
 
+
+  # Public: Convert a place to a zip code.
+  #
+  # Examples
+  #
+  #   "long island city, ny".to_zip
+  #   #=> ["11101", "11109", "11120"]
+  #
+  #   "hastings on hudson".to_zip
+  #   #=> ["10706"]
+  #
+  # Returns an Array of converted places.
   def to_zip
     if self.match(',')
-      @area = self.split(',')
-      @area.collect! { |a| a.strip }
-
-      @zip_codes = Area.zip_codes.find_all {|row| row[1] && row[1].downcase == @area[0].downcase and row[2].downcase == @area[1].downcase }.map {|a| a.first }
+      area = self.split(',')
+      area.collect! { |a| a.strip }
+      @zip_codes = Area.zip_codes.find_all {|row| row[1] && row[1].downcase == area[0].downcase and row[2].downcase == area[1].downcase }.map {|a| a.first }
     else
       @zip_codes = Area.zip_codes.find_all {|row| row[1] != nil and row[1].downcase == self.downcase }.map {|a| a.first }
     end
-    @zip_codes.length == 1 ? @zip_codes.first : @zip_codes
   end
 
+
+  # Public: Convert a zipcode to its GMT offset.
+  #
+  # Examples
+  #
+  #   "11211".to_gmt_offset
+  #   #=> "-5"
+  #
+  # Returns a String representation of the GMT offset.
   def to_gmt_offset
-    row = Area.zip_codes.find {|row| row[2] != nil and (row[2].upcase == self.to_s.upcase or row[0] == self.to_s) }
-    row[5] if row
+    if Area.zip_or_territory?(self.to_s)
+      row = Area.zip_codes.find {|row| row[2] != nil and (row[2].upcase == self.to_s.upcase or row[0] == self.to_s) }
+      row[5] if row
+    end
+  end
+
+
+  # Public: Convert a zipcode to its latitude and longitude.
+  #
+  # Examples
+  #
+  #   "11211".to_latlon
+  #   #=> "40.71209, -73.95427"
+  #
+  # Returns a String representation of the lat/lon pair.
+  def to_latlon
+    if Area.zip?(self)
+      row = Area.zip_codes.find {|row| row.first == self.to_s }
+      row[3] + ', ' + row[4] if row
+    end
+  end
+
+
+  # Public: Convert a zipcode to its latitude.
+  #
+  # Examples
+  #
+  #   "11211".to_lat
+  #   #=> "40.71209"
+  #
+  # Returns a String representation of the latitude.
+  def to_lat
+    if Area.zip?(self)
+      row = Area.zip_codes.find {|row| row.first == self.to_s }
+      row[3] if row
+    end
+  end
+
+
+  # Public: Convert a zipcode to its longitude.
+  #
+  # Examples
+  #
+  #   "11211".to_lon
+  #   #=> "40.71209"
+  #
+  # Returns a String representation of the longitude.
+  def to_lon
+    if Area.zip?(self)
+      row = Area.zip_codes.find {|row| row.first == self.to_s }
+      row[4] if row
+    end
   end
 
 end

data/lib/area/version.rb

@@ -1,3 +1,3 @@
 module Area
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

data/readme.md

@@ -31,14 +31,14 @@ In your gemfile: `gem 'area'`
 
 #### Convert a state to an area code
 ```` ruby
-"AK".to_area #=> "907"
+"AK".to_area #=> ["907"]
 "CT".to_area #=> ["203", "860"]
 ```
 
 #### Convert a place to a zip code
 ```` ruby
 "long island city, ny".to_zip #=> ["11101", "11109", "11120"]
-"hastings on hudson".to_zip #=> "10706"
+"hastings on hudson".to_zip #=> ["10706"]
 ```
 
 #### Convert a zip code to a place

data/test/unit/area_test.rb

@@ -23,10 +23,6 @@ class TestInteger < MiniTest::Unit::TestCase
     assert_equal "-5", 11211.to_gmt_offset
   end
 
-  def test_that_it_converts_zip_code_string_to_gmt_offset
-    assert_equal "-5", "11211".to_gmt_offset
-  end
-
   def test_that_it_handles_bad_area_codes
     assert_raises(ArgumentError) { 1234.to_region }
     assert_raises(ArgumentError) { 1234.to_latlon }
@@ -53,12 +49,12 @@ class TestString < MiniTest::Unit::TestCase
   end
 
   def test_that_it_converts_to_area_code
-    assert_equal "907", "AK".to_area
+    assert_equal ["907"], "AK".to_area
     assert_equal ["203", "860"], "CT".to_area
   end
 
   def test_that_it_converts_to_zip_code
-    assert_equal "10706", "hastings on hudson".to_zip
+    assert_equal ["10706"], "hastings on hudson".to_zip
     assert_equal ["11101", "11109", "11120"], "long Island city".to_zip
   end
 
@@ -73,10 +69,27 @@ class TestString < MiniTest::Unit::TestCase
   def test_that_it_handles_incorrect_zips
     assert_equal [], "9888".to_zip
     assert_raises(ArgumentError) { "9888".to_region }
-    assert_equal [], "9888".to_area
-    assert_nil "9888".to_gmt_offset
+    assert_raises(ArgumentError) { "9888".to_area }
+    assert_raises(ArgumentError) { "9888".to_gmt_offset }
+  end
+
+  def test_that_it_converts_zip_code_to_latlon
+    assert_equal "40.71209, -73.95427", "11211".to_latlon
+  end
+
+  def test_that_it_converts_zip_code_to_lat
+    assert_equal "40.71209", "11211".to_lat
+  end
+
+  def test_that_it_converts_zip_code_to_lon
+    assert_equal "-73.95427", "11211".to_lon
   end
 
+  def test_that_it_converts_zip_code_to_gmt_offset
+    assert_equal "-5", "11211".to_gmt_offset
+  end
+
+
 end
 
 class TestArray < MiniTest::Unit::TestCase

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: area
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-28 00:00:00.000000000 Z
+date: 2013-02-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fastercsv