proxihash 0.0.1

data/.gitignore

@@ -0,0 +1,2 @@
+/*.gem
+/Gemfile.lock

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+bundler_args: --without dev
+script: testrb test
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - jruby-19mode
+  - rbx-19mode
+  - ruby-head

data/CHANGELOG

@@ -0,0 +1,3 @@
+== 0.0.1 2013-08-16
+
+ * Hi.

data/Gemfile

@@ -0,0 +1,6 @@
+source :rubygems
+gemspec
+
+group :dev do
+  gem 'debugger'
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) George Ogata
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,109 @@
+## Proxihash
+
+A [GeoHash][geohash] implementation geared toward indexing data for performing
+proximity searches at different radii.
+
+The algorithm underlying Proxihash is the GeoHash algorithm, however the hashes
+are returned offer the bit string as a numeric value, rather than a base-32
+representation. This allows bit-precision, rather than 5-bit precision, which
+comes in handy for variable-distance proximity searches.
+
+Proxihash computes for you the tileset required for a given radius search from a
+given point, within the specified bit precision range. This range lets you limit
+your index to certain precisions, which reflects the search distances you need
+to support.
+
+[geohash]: http://en.wikipedia.org/wiki/Geohash
+
+### Usage
+
+Create a proxihash with 31 bits of precision:
+
+    proxihash = Proxihash.encode(42.6, -5.6, 31)
+
+Get the numeric value, for storage:
+
+    proxihash.value     # 939008154
+    proxihash.num_bits  # 31
+
+Compute the tile (bounding box) represented by the proxihash:
+
+    proxihash.tile    # [42.5994873046875, 42.60498046875, -5.60302734375, -5.5975341796875]
+
+Find neighbors at the same precision:
+
+    proxihash.neighbor(-1,  1)  # tile to the south-east
+    proxihash.neighbor( 1, -1)  # tile to the north-west
+
+    # Alternatively:
+    proxihash.north  # same as proxihash.neighbor( 1,  0)
+    proxihash.east   # same as proxihash.neighbor( 0,  1)
+    proxihash.west   # same as proxihash.neighbor( 0, -1)
+    proxihash.south  # same as proxihash.neighbor(-1,  0)
+
+Find the midpoint of the tile:
+
+    proxihash.decode  # [42.60223388671875, -5.60028076171875]
+
+Note that roundtripping through `encode` then `decode` may not give you the same
+initial point, as decoding gives you the *center* of the tile. It will give you
+a nearby point, however. Roundtripping through `decode` then `encode` will give
+you back the same tile.
+
+## Indexing
+
+The idea is to index your data with proxihashes at the precisions you care
+about. These precisions depend on the search distances you need to support.
+
+Consider that the radius of the earth is about 40,036 km, (24,873 miles). This
+means 16 bits of longitude (16 + 15 = 31 bit proxihash) will give you
+sub-kilometer precision. Sub-mile precision requires 29 bits. These fit nicely
+into a 32-bit integer.
+
+## Searching
+
+Once you've indexed all your data by their proxihash at the precisions you care
+about, you probably want to answer a query like "find all users within 25 miles
+of `(lat,lng)`". To do this, you have to find the tiles to search for:
+
+    Proxihash.radius = :earth_in_miles
+    Proxihash.search_tiles(lat, lng, 25, min_bits: 11, max_bits: 31)
+
+The first line sets the units to use (default is kilometers).
+
+The second returns up to 4 tiles (proxihashes): the tile that `(lat,lng)` falls
+on, plus the 3 neighbors that need to be searched. The 3 neighbors depend on
+which quadrant of the center tile `(lat,lng)` falls on. The tile size is the
+smallest that will cover the 25 mile search circle.
+
+The precision of the tiles (proxihashes) computed depends on two things: the
+distance, and the latitude.
+
+Larger tiles (shorter proxihashes) are required for larger distances and
+latitudes nearer the poles; smaller tiles (longer proxihashes) for shorter
+distances and latitudes nearer the equator. The latitude makes a difference
+because tiles nearer the poles are smaller, and so a circle of a given radius
+can cover more tiles of the same angular size near the poles than near the
+equator.
+
+There is one caveat that arises from this: Finding neighboring tiles degenerates
+toward the poles. If the search circle overlaps a pole, or finding a neighboring
+tile requires crossing a pole, a `PoleWrapException` is raised.
+
+The `:max_bits` option prevents you from computing an arbitrarily precise
+proxihash if you take the distance from user input. It will simply cap the
+precision of the proxihashes returned. The `:min_bits` option makes
+`search_tiles` return nil if a larger tile is required. `search_tiles` currently
+does not return more than 4 tiles to accomodate a smaller tileset.
+
+## Contributing
+
+ * [Bug reports](https://github.com/howaboutwe/proxihash/issues)
+ * [Source](https://github.com/howaboutwe/proxihash)
+ * Patches: Fork on Github, send pull request.
+   * Include tests where practical.
+   * Leave the version alone, or bump it in a separate commit.
+
+## Copyright
+
+Copyright (c) George Ogata. See LICENSE for details.

data/Rakefile

@@ -0,0 +1 @@
+require 'ritual'

data/lib/proxihash.rb

@@ -0,0 +1,232 @@
+class Proxihash
+  autoload :VERSION, 'proxihash/version'
+
+  def initialize(value, num_bits)
+    @value = value
+    @num_bits = num_bits
+    num_bits.odd? or
+      raise ArgumentError, "bitlength must be odd"
+    value < 1 << num_bits or
+      raise ArgumentError, "value too large for #{num_bits} bits"
+  end
+
+  attr_reader :value, :num_bits
+
+  def id
+    value | 1 << num_bits
+  end
+
+  class << self
+    def radius=(radius)
+      @radius =
+        case radius
+        when :earth_in_miles
+          3958.761
+        when :earth_in_kilometers
+          6371.009
+        when :earth_in_meters
+          6371009
+        else
+          radius
+        end
+    end
+
+    def angular_units=(units)
+      case units
+      when :radians
+        @min_lat = -Math::PI/2
+        @max_lat =  Math::PI/2
+        @min_lng = -Math::PI
+        @max_lng =  Math::PI
+      when :degrees
+        @min_lat = -90
+        @max_lat =  90
+        @min_lng = -180
+        @max_lng =  180
+      else
+        raise ArgumentError "angular units must be :radians or :degrees (#{units.inspect} given)"
+      end
+      @angular_units = units
+    end
+
+    attr_reader :radius, :angular_units
+    attr_reader :min_lat, :max_lat, :min_lng, :max_lng
+
+    def encode(lat, lng, num_bits=31)
+      lat = lat.to_f
+      lng = lng.to_f
+
+      value = 0
+
+      lat0 = min_lat
+      lat1 = max_lat
+      lng0 = min_lng
+      lng1 = max_lng
+
+      (num_bits - 1).downto(0) do |i|
+        if i.odd?
+          mid = 0.5 * (lat0 + lat1)
+          if lat > mid
+            value |= (1 << i)
+            lat0 = mid
+          else
+            lat1 = mid
+          end
+        else
+          mid = 0.5 * (lng0 + lng1)
+          if lng > mid
+            value |= (1 << i)
+            lng0 = mid
+          else
+            lng1 = mid
+          end
+        end
+      end
+
+      new(value, num_bits)
+    end
+
+    def search_tiles(lat, lng, distance, options={})
+      lat = lat.to_f
+      lng = lng.to_f
+      bits = 2*lng_bits(lat, distance.to_f) - 1
+
+      if (min_bits = options[:min_bits]) && bits < min_bits
+        return nil
+      elsif (max_bits = options[:max_bits]) && bits > max_bits
+        # TODO: avoid unnecessary neighboring tiles
+        bits = max_bits
+      end
+
+      # TODO: can use the next 2 bits to determine quadrant instead
+      center = encode(lat, lng, bits)
+      tile_lat, tile_lng = center.decode
+      dlat = lat < tile_lat ? -1 : 1
+      dlng = lng < tile_lng ? -1 : 1
+      [
+        center,
+        center.neighbor(0   , dlng),
+        center.neighbor(dlat, dlng),
+        center.neighbor(dlat,    0),
+      ]
+    rescue PoleWrapException
+      nil
+    end
+
+    private
+
+    def lng_bits(lat, distance)
+      lat = Math::PI / 180.0 * lat if angular_units == :degrees
+      distance >= Float::EPSILON or
+        raise ArgumentError, "distance too small"
+      distance <= Proxihash.radius*(0.5*Math::PI - lat.abs) or
+        raise PoleWrapException, "cannot search across pole"
+      dlng = Math.asin(Math.sin(0.5*distance/Proxihash.radius)/Math.cos(lat))
+      Math.log2(Math::PI/dlng.abs).ceil - 1
+    end
+  end
+
+  [:min_lat, :max_lat, :min_lng, :max_lng].each do |name|
+    class_eval "def #{name}; self.class.#{name}; end"
+  end
+
+  def decode
+    lat0, lat1, lng0, lng1 = tile
+    [0.5 * (lat0 + lat1), 0.5 * (lng0 + lng1)]
+  end
+
+  def tile
+    lat0 = min_lat
+    lat1 = max_lat
+    lng0 = min_lng
+    lng1 = max_lng
+
+    (num_bits - 1).downto(0) do |i|
+      if i.odd?
+        mid = 0.5 * (lat0 + lat1)
+        if value[i] == 1
+          lat0 = mid
+        else
+          lat1 = mid
+        end
+      else
+        mid = 0.5 * (lng0 + lng1)
+        if value[i] == 1
+          lng0 = mid
+        else
+          lng1 = mid
+        end
+      end
+    end
+
+    [lat0, lat1, lng0, lng1]
+  end
+
+  def neighbor(dlat, dlng)
+    value = self.value
+    value = bump(value, 1, dlat, false) unless dlat.zero?
+    value = bump(value, 0, dlng, true ) unless dlng.zero?
+    self.class.new(value, num_bits)
+  end
+
+  def north
+    neighbor(1, 0)
+  end
+
+  def south
+    neighbor(-1, 0)
+  end
+
+  def east
+    neighbor(0, 1)
+  end
+
+  def west
+    neighbor(0, -1)
+  end
+
+  def ==(other)
+    other.is_a?(Proxihash) && value == other.value && num_bits == other.num_bits
+  end
+
+  def hash
+    value.hash ^ num_bits
+  end
+  alias eql? ==
+
+  def inspect
+    "Proxihash[#{value.to_s(2).rjust(num_bits, '0')}]"
+  end
+
+  private
+
+  def bump(value, offset, direction, wrap)
+    bit = offset
+    if direction > 0
+      while bit < num_bits
+        if value[bit] == 0
+          return value | (1 << bit)
+        else
+          value &= ~(1 << bit)
+        end
+        bit += 2
+      end
+      return value if wrap
+    else
+      while bit < num_bits
+        if value[bit] == 0
+          value |= 1 << bit
+        else
+          return value & ~(1 << bit)
+        end
+        bit += 2
+      end
+      return value if wrap
+    end
+    raise PoleWrapException, "can't wrap around pole"
+  end
+
+  PoleWrapException = Class.new(ArgumentError)
+  self.radius = :earth_in_kilometers
+  self.angular_units = :degrees
+end

data/lib/proxihash/version.rb

@@ -0,0 +1,11 @@
+class Proxihash
+  VERSION = [0, 0, 1]
+
+  class << VERSION
+    include Comparable
+
+    def to_s
+      join('.')
+    end
+  end
+end

data/proxihash.gemspec

@@ -0,0 +1,18 @@
+# -*- encoding: utf-8 -*-
+$:.unshift File.expand_path('lib', File.dirname(__FILE__))
+require 'proxihash/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = 'proxihash'
+  gem.version       = Proxihash::VERSION
+  gem.authors       = ['George Ogata']
+  gem.email         = ['george.ogata@gmail.com']
+  gem.summary       = "Hashes for geospatial proximity searches."
+  gem.homepage      = 'http://github.com/howaboutwe/proxisearch'
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+
+  gem.add_development_dependency 'ritual', '~> 0.4.1'
+end

data/test/test_proxihash.rb

@@ -0,0 +1,377 @@
+$:.unshift File.expand_path('../lib', File.dirname(__FILE__))
+
+require 'minitest/spec'
+require 'set'
+require 'proxihash'
+
+describe Proxihash do
+  describe '.new' do
+    it "creates a Proxihash with the given value and number of bits" do
+      proxihash = Proxihash.new(0b011, 3)
+      proxihash.value.must_equal 0b011
+      proxihash.num_bits.must_equal 3
+    end
+
+    it "raises an ArgumentError if the value is too large for the number of bits" do
+      ->{ Proxihash.new(0b1000, 3) }.must_raise ArgumentError
+    end
+
+    it "raises an ArgumentError if the number of bits is even" do
+      ->{ Proxihash.new(0b100, 2) }.must_raise ArgumentError
+    end
+  end
+
+  describe '#id' do
+    it "returns the value prefixed with a 1-bit to uniquify it across precisions" do
+      proxihash = Proxihash.new(0b011, 3)
+      proxihash.id.must_equal 0b1011
+    end
+  end
+
+  describe '.encode' do
+    it "returns a proxihash for the given lat/lng at the given precision" do
+      Proxihash.encode(0, 0, 9).must_equal Proxihash.new(0b001111111, 9)
+    end
+
+    it "returns a sub-kilometer (31-bit) proxihash by default" do
+      Proxihash.encode(0, 0).must_equal Proxihash.new(0x1f_ff_ff_ff, 31)
+    end
+
+    it "computes the proxihash correctly" do
+      Proxihash.encode(-35.15625, 122.34375, 13).must_equal Proxihash.new(0b1_01_10_01_00_11_11, 13)
+    end
+  end
+
+  describe ".search_tiles" do
+    describe "when in the 1st quadrant of a tile" do
+      it "returns the center tile and the 3 neighbors to the top and right" do
+        center = Proxihash.new(0x6000, 15)
+        Proxihash.search_tiles(0.704, 0.704, 156).to_set.must_equal Set[
+          center, center.neighbor(1, 0), center.neighbor(1, 1), center.neighbor(0, 1)
+        ]
+      end
+    end
+
+    describe "when in the 2nd quadrant of a tile" do
+      it "returns the center tile and the 3 neighbors to the top and left" do
+        center = Proxihash.new(0x6000, 15)
+        Proxihash.search_tiles(0.704, 0.703, 156).to_set.must_equal Set[
+          center, center.neighbor(1, 0), center.neighbor(1, -1), center.neighbor(0, -1)
+        ]
+      end
+    end
+
+    describe "when in the 3rd quadrant of a tile" do
+      it "returns the center tile and the 3 neighbors to the bottom and left" do
+        center = Proxihash.new(0x6000, 15)
+        Proxihash.search_tiles(0.703, 0.703, 156).to_set.must_equal Set[
+          center, center.neighbor(0, -1), center.neighbor(-1, -1), center.neighbor(-1, 0)
+        ]
+      end
+    end
+
+    describe "when in the 4th quadrant of a tile" do
+      it "returns the center tile and the 3 neighbors to the bottom and right" do
+        center = Proxihash.new(0x6000, 15)
+        Proxihash.search_tiles(0.703, 0.704, 156).to_set.must_equal Set[
+          center, center.neighbor(-1, 0), center.neighbor(-1, 1), center.neighbor(0, 1)
+        ]
+      end
+    end
+
+    describe "larger-radius search" do
+      it "returns shorter proxihashes" do
+        center = Proxihash.new(0x1800, 13)
+        Proxihash.search_tiles(1.407, 1.407, 157).to_set.must_equal Set[
+          center, center.neighbor(1, 0), center.neighbor(1, 1), center.neighbor(0, 1)
+        ]
+      end
+    end
+
+    describe "lower-radius search" do
+      it "returns longer proxihashes" do
+        center = Proxihash.new(0x18000, 17)
+        Proxihash.search_tiles(0.352, 0.352, 78).to_set.must_equal Set[
+          center, center.neighbor(1, 0), center.neighbor(1, 1), center.neighbor(0, 1)
+        ]
+      end
+    end
+
+    describe "when :min_bits is given" do
+      it "returns nil if the hashes would be too short" do
+        Proxihash.search_tiles(0, 0, 20, min_bits: 21).must_be_nil
+      end
+
+      it "does not return nil if the hashes are ok" do
+        center = Proxihash.new(0x7ffff, 21)
+        Proxihash.search_tiles(0, 0, 19, max_bits: 21).to_set.must_equal Set[
+          center, center.neighbor(1, 0), center.neighbor(1, 1), center.neighbor(0, 1)
+        ]
+      end
+    end
+
+    describe "when :max_bits is given" do
+      it "caps the hash length if they would be too long" do
+        center = Proxihash.new(0x7ffff, 21)
+        Proxihash.search_tiles(0, 0, 0.01, max_bits: 21).to_set.must_equal Set[
+          center, center.neighbor(1, 0), center.neighbor(1, 1), center.neighbor(0, 1)
+        ]
+      end
+
+      it "does not cap the hash length if the hashes are ok" do
+        center = Proxihash.new(0x7ffff, 21)
+        Proxihash.search_tiles(0, 0, 19, max_bits: 21).to_set.must_equal Set[
+          center, center.neighbor(1, 0), center.neighbor(1, 1), center.neighbor(0, 1)
+        ]
+      end
+    end
+
+    describe "when the search circle overlaps a pole" do
+      it "returns nil" do
+        Proxihash.search_tiles(89.999, 0, 100).must_be_nil
+      end
+    end
+  end
+
+  describe '.lng_bits' do
+    Proxihash.singleton_class.send :public, :lng_bits
+
+    it "is higher toward the poles" do
+      Proxihash.lng_bits(  0, 78.18).must_equal 9
+      Proxihash.lng_bits( 60, 78.18).must_equal 8
+      Proxihash.lng_bits(-60, 78.18).must_equal 8
+    end
+
+    it "is lower for larger radii" do
+      Proxihash.lng_bits(0, 78.18).must_equal 9
+      Proxihash.lng_bits(0, 78.19).must_equal 8
+    end
+
+    it "raises a PoleWrapException if the search circle overlaps a pole" do
+      Proxihash.lng_bits( 60, 3335)
+      ->{ Proxihash.lng_bits( 60, 3336) }.must_raise Proxihash::PoleWrapException
+
+      Proxihash.lng_bits(-60, 3335)
+      ->{ Proxihash.lng_bits(-60, 3336) }.must_raise Proxihash::PoleWrapException
+    end
+
+    it "raises a PoleWrapException at either pole" do
+      ->{ Proxihash.lng_bits( 90, 0.1) }.must_raise Proxihash::PoleWrapException
+      ->{ Proxihash.lng_bits(-90, 0.1) }.must_raise Proxihash::PoleWrapException
+    end
+
+    it "raises an ArgumentError if the radius is zero" do
+      ->{ Proxihash.lng_bits(0, 0) }.must_raise ArgumentError
+    end
+  end
+
+  describe '#decode' do
+    it "returns the lat/lng for the center of the given proxihash's tile" do
+      Proxihash.new(0, 7).decode.must_equal [-78.75, -168.75]
+      Proxihash.new(0, 9).decode.must_equal [-84.375, -174.375]
+    end
+
+    it "computes the lat/lng correctly" do
+      Proxihash.new(0b0_01_10_01_00_11_11, 13).decode.must_equal [-35.15625, -57.65625]
+    end
+  end
+
+  describe "#tile" do
+    it "returns the lat/lng ranges of the given proxihash's tile" do
+      Proxihash.new(0b0_01_10_01_00_11_11, 13).tile.must_equal [-36.5625, -33.75, -59.0625, -56.25]
+    end
+  end
+
+  describe "#neighbor" do
+    describe "to the north" do
+      it "increments the latitude" do
+        Proxihash.new(0b0_00_00, 5).neighbor(1, 0).must_equal Proxihash.new(0b0_00_10, 5)
+      end
+
+      it "carries the 1 as necessary" do
+        Proxihash.new(0b0_00_00_10_10, 9).neighbor(1, 0).must_equal Proxihash.new(0b0_00_10_00_00, 9)
+      end
+
+      it "raises a PoleWrapException at the north pole" do
+        ->{ Proxihash.new(0b0_11_10_11_10, 9).neighbor(1, 0) }.must_raise Proxihash::PoleWrapException
+      end
+    end
+
+    describe "to the south" do
+      it "decrements the latitude" do
+        Proxihash.new(0b1_11_11, 5).neighbor(-1, 0).must_equal Proxihash.new(0b1_11_01, 5)
+      end
+
+      it "borrows a 1 as necessary" do
+        Proxihash.new(0b1_11_11_01_01, 9).neighbor(-1, 0).must_equal Proxihash.new(0b1_11_01_11_11, 9)
+      end
+
+      it "raises a PoleWrapException at the south pole" do
+        ->{ Proxihash.new(0b0_01_00_01_00, 9).neighbor(-1, 0) }.must_raise Proxihash::PoleWrapException
+      end
+    end
+
+    describe "to the east" do
+      it "increments the longitude" do
+        Proxihash.new(0b0_00_00, 5).neighbor(0, 1).must_equal Proxihash.new(0b00_01, 5)
+      end
+
+      it "carries the 1 as necessary" do
+        Proxihash.new(0b0_00_00_01_01, 9).neighbor(0, 1).must_equal Proxihash.new(0b00_01_00_00, 9)
+      end
+
+      it "wraps around at the prime meridian" do
+        Proxihash.new(0b1_11_01_11_01, 9).neighbor(0, 1).must_equal Proxihash.new(0b0_10_00_10_00, 9)
+      end
+    end
+
+    describe "to the west" do
+      it "decrements the longitude" do
+        Proxihash.new(0b0_11_11, 5).neighbor(0, -1).must_equal Proxihash.new(0b0_11_10, 5)
+      end
+
+      it "borrows a 1 as necessary" do
+        Proxihash.new(0b0_11_11_10_10, 9).neighbor(0, -1).must_equal Proxihash.new(0b0_11_10_11_11, 9)
+      end
+
+      it "wraps around at the prime meridian" do
+        Proxihash.new(0b0_10_00_10_00, 9).neighbor(0, -1).must_equal Proxihash.new(0b1_11_01_11_01, 9)
+      end
+    end
+
+    describe "to the north-east" do
+      it "increments both latitude and longitude" do
+        Proxihash.new(0b0_00_00, 5).neighbor(1, 1).must_equal Proxihash.new(0b0_00_11, 5)
+      end
+    end
+
+    describe "to the north-west" do
+      it "increments the latitude, decrements the longitude" do
+        Proxihash.new(0b0_00_01, 5).neighbor(1, -1).must_equal Proxihash.new(0b0_00_10, 5)
+      end
+    end
+
+    describe "to the south-east" do
+      it "decrements the latitude, increments the longitude" do
+        Proxihash.new(0b0_00_10, 5).neighbor(-1, 1).must_equal Proxihash.new(0b0_00_01, 5)
+      end
+    end
+
+    describe "to the south-west" do
+      it "decrements both latitude and longitude" do
+        Proxihash.new(0b0_11_11, 5).neighbor(-1, -1).must_equal Proxihash.new(0b0_11_00, 5)
+      end
+    end
+
+    describe "when both arguments are zero" do
+      it "returns itself" do
+        Proxihash.new(0b0_00_00, 5).neighbor(0, 0).must_equal Proxihash.new(0b0_00_00, 5)
+      end
+    end
+  end
+
+  describe "#north" do
+    it "returns the neighbor to the north" do
+      Proxihash.new(0b0_00_00, 5).north.must_equal Proxihash.new(0b0_00_10, 5)
+    end
+  end
+
+  describe "#south" do
+    it "returns the neighbor to the south" do
+      Proxihash.new(0b1_11_11, 5).south.must_equal Proxihash.new(0b1_11_01, 5)
+    end
+  end
+
+  describe "#east" do
+    it "returns the neighbor to the east" do
+      Proxihash.new(0b0_00_00, 5).east.must_equal Proxihash.new(0b00_01, 5)
+    end
+  end
+
+  describe "#west" do
+    it "returns the neighbor to the west" do
+      Proxihash.new(0b0_11_11, 5).west.must_equal Proxihash.new(0b0_11_10, 5)
+    end
+  end
+
+  describe "#inspect" do
+    it "shows the raw binary string to the correct precision" do
+      Proxihash.new(0b10011001100, 11).inspect.must_equal 'Proxihash[10011001100]'
+    end
+  end
+
+  describe "#hash and #eql?" do
+    it "allows proxihashes to be used as hash keys" do
+      hash = {}
+      hash[Proxihash.new(0b0001100, 7)] = 1
+      hash[Proxihash.new(0b0001100, 7)] = 2
+      hash[Proxihash.new(0b0001100, 7)].must_equal 2
+    end
+
+    it "does not treat Proxihashes with different precisions as the same hash key" do
+      hash = {}
+      hash[Proxihash.new(0b0001100, 7)] = 1
+      hash[Proxihash.new(0b0001100, 5)] = 2
+      hash[Proxihash.new(0b0001100, 7)].must_equal 1
+    end
+  end
+
+  describe "tile adjacency" do
+    it "returns tiles whose bounding boxes border the given tile" do
+      tile = Proxihash.new(0b1_10_00, 5)
+
+      tl = tile.neighbor( 1, -1).tile
+      tc = tile.neighbor( 1,  0).tile
+      tr = tile.neighbor( 1,  1).tile
+      ml = tile.neighbor( 0, -1).tile
+      mc = tile.neighbor( 0,  0).tile
+      mr = tile.neighbor( 0,  1).tile
+      bl = tile.neighbor(-1, -1).tile
+      bc = tile.neighbor(-1,  0).tile
+      br = tile.neighbor(-1,  1).tile
+
+      tl[0].must_be_close_to ml[1]
+      tc[0].must_be_close_to mc[1]
+      tr[0].must_be_close_to mr[1]
+
+      ml[0].must_be_close_to bl[1]
+      mc[0].must_be_close_to bc[1]
+      mr[0].must_be_close_to br[1]
+
+      tl[3].must_be_close_to tc[2]
+      ml[3].must_be_close_to mc[2]
+      bl[3].must_be_close_to bc[2]
+
+      tc[3].must_be_close_to tr[2]
+      mc[3].must_be_close_to mr[2]
+      bc[3].must_be_close_to br[2]
+
+      tl[0].must_be_close_to tc[0]
+      tl[1].must_be_close_to tc[1]
+      tl[0].must_be_close_to tr[0]
+      tl[1].must_be_close_to tr[1]
+
+      tl[2].must_be_close_to ml[2]
+      tl[3].must_be_close_to ml[3]
+      tl[2].must_be_close_to bl[2]
+      tl[3].must_be_close_to bl[3]
+
+      [tl,tc,tr,ml,mc,mr,bl,bc,br].each do |tile|
+        assert tile[0] < tile[1]
+        assert tile[2] < tile[3]
+      end
+    end
+  end
+
+  describe 'roundtripping' do
+    it "returns the original lat/lng if the lat/lng is in the center of a tile" do
+      proxihash = Proxihash.encode(-28.125, 61.875, 9)
+      proxihash.decode.must_equal [-28.125, 61.875]
+    end
+
+    it "returns the center of the tile of the given lat/lng" do
+      proxihash = Proxihash.encode(-28, 62, 9)
+      proxihash.decode.must_equal [-28.125, 61.875]
+    end
+  end
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: proxihash
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- George Ogata
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-08-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ritual
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+description: 
+email:
+- george.ogata@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .travis.yml
+- CHANGELOG
+- Gemfile
+- LICENSE
+- README.markdown
+- Rakefile
+- lib/proxihash.rb
+- lib/proxihash/version.rb
+- proxihash.gemspec
+- test/test_proxihash.rb
+homepage: http://github.com/howaboutwe/proxisearch
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Hashes for geospatial proximity searches.
+test_files:
+- test/test_proxihash.rb
+has_rdoc: