bin_search 0.1

data/.gitignore

@@ -0,0 +1,3 @@
+doc/**
+Gemfile.lock
+.yardoc

data/AUTHORS

@@ -0,0 +1 @@
+Stefan Plantikow <stefanp@moviepilot.com>

data/Gemfile

@@ -0,0 +1,2 @@
+source "http://rubygems.org"
+gemspec

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Stefan Plantikow
+
+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.md

@@ -0,0 +1,81 @@
+# bin_search
+
+This gem implements binary search for arrays and array-like data
+structures. Binary search is a very fast method for looking up elements in pre-sorted arrays that is missing from the Ruby standard library.  For large
+enough arrays, it will always be more efficient than using regular `assoc` and `index` calls.
+
+## API
+
+bin_search adds six methods to Ruby's Array class:
+
+* `bin_index` - find and return index of given element using `<=>` or the provided comparator block to compare elements
+* `bin_search` - find and return given element using `<=>` or the provided comparator block to compare elements
+* `bin_assoc` - find given element and return an assoc pair [index, elem] using `<=>` or the provided comparator block to compare elements
+* `bin_index_by` - same as `bin_index` but compares elements using `<=>` after mapping them with the provided block
+* `bin_search_by` - same as `bin_search` but compares elements using `<=>` after mapping them with the provided block
+* `bin_assoc_by` - same as `bin_assoc` but compares elements using `<=>` after mapping them with the provided block
+
+Each of these methods needs to be called with the searched element, and a mode as second argument. Available modes are:
+
+* `:asc` - array has been sorted in ascending order, find first element
+that is greater than or equal to the given element (default mode)
+* `:desc` - array has been sorted descending ascending order, find first element that is less than or equal to the given element
+* `:asc_eq` - same as `:asc` but only retuns the found element if it is equal
+* `:desc_eq` - same as `:desc` but only retuns the found element if it is equal
+
+If the sorting requirements of a mode are not met by the used array, the behavior of the bin_search methods is unspecified (i.e. arbitrary weird things may happpen).
+
+Example
+
+    arr = [1, 2, 2, 3, 8, 9]
+    arr.bin_index(0, :asc) => 0
+    arr.bin_index(1, :asc) => 0
+    arr.bin_index(2, :asc) => 1
+    arr.bin_index(2, :asc_eq) => 1
+    arr.bin_index(2.5, :asc_eq) => -1
+    arr.bin_index(9, :asc) => 5
+    arr.bin_index(10, :asc) => -1
+
+## Use as Mixin
+
+    class MyArrayClass
+      include ::BinSearch::Methods
+
+      def sort!
+        # ...
+      end
+    end
+
+    arr = MyArrayClass.new
+    arr.sort!
+    arr.bin_search(some_elem, :asc)
+
+## Implementation Notes
+
+bin_search is a pure ruby implementation of binary search.
+
+For arrays with less than `1 << ::BinSearch::LIN_BITS` elements, all methods
+switch to linear search as that is slightly more efficient on moden CPUs
+(due to processor caching and branch prediction effects).
+
+## Requirements
+
+Ruby 1.9
+
+## Installation
+
+    gem install bin_search
+
+## Online Docs
+
+Docs for the latest released gems are to be found in:
+
+http://rubydoc.info/gems/bin_search
+
+## Development
+
+Development happens on the devel branch, cf. boggle/bin_search/tree/devel, too.
+
+## Status
+
+Fairly fresh but tested.

data/Rakefile

@@ -0,0 +1,34 @@
+require 'bundler/gem_tasks'
+
+require 'rspec'
+require 'rspec/core/rake_task'
+
+require 'yard'
+require 'yard/rake/yardoc_task'
+
+desc 'Run all rspecs'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.fail_on_error = true
+  spec.verbose       = false
+#  spec.rspec_opts    = ['--backtrace']
+end
+
+desc 'Run yardoc over project sources'
+YARD::Rake::YardocTask.new(:ydoc) do |t|
+  t.options = ['--verbose']
+  t.files   = ['lib/**/*.rb', '-', 'README.md', 'AUTHORS', 'LICENSE.txt']
+end
+
+desc 'Run irb in project environment'
+task :console do
+  require 'irb'
+  ARGV.clear
+  IRB.conf[:USE_READLINE] = false if ENV['JRUBY_OPTS'] =~ /--ng/
+  IRB.start
+end
+
+task :doc => :ydoc
+task :docs => :ydoc
+task :test => :spec
+task :tests => :spec
+task :irb => :console

data/bin_search.gemspec

@@ -0,0 +1,36 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require 'bin_search/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'bin_search'
+  s.version     = ::BinSearch::VERSION
+  s.summary     = 'Binary search in sorted arrays'
+  s.description = 'Pure ruby implementation of binary search for Ruby arrays and similiar data ' +
+                  'structures.  Supports ascending and descending sort order, searching ' +
+                  'for exact and nearest matches, and has a versatile API.  Uses linear search ' +
+                  'for small arrays to make use of the internal cache of moden CPUs.'
+  s.author      = 'Stefan Plantikow'
+  s.email       = 'stefan.plantikow@googlemail.com'
+  s.homepage    = 'https://github.com/boggle/bin_search'
+  s.rubyforge_project = 'bin_search'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.bindir      = 'script'
+  s.executables = `git ls-files -- script/*`.split("\n").map{ |f| File.basename(f) }
+  s.licenses = ['PUBLIC DOMAIN WITHOUT ANY WARRANTY']
+
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'yard'
+
+  case RUBY_ENGINE.to_sym
+    when :jruby then s.add_development_dependency 'maruku'
+    else s.add_development_dependency 'redcarpet'
+  end
+end

data/lib/bin_search.rb

@@ -0,0 +1,24 @@
+require 'rubygems'
+
+require 'bin_search/version'
+
+module BinSearch
+
+  def self.files
+    f = []
+    f << 'bin_search/bin_search'
+    f
+  end
+
+  def self.load_relative(f)
+    path = "#{File.join(File.dirname(caller[0]), f)}.rb"
+    load path
+  end
+
+  def self.reload!
+    files.each { |f| load_relative f }
+  end
+
+end
+
+BinSearch.files.each { |f| require f }

data/lib/bin_search/bin_search.rb

@@ -0,0 +1,289 @@
+module BinSearch
+
+  # BinSearch switches to linear search if the numer of elements to sorted
+  # is less than 1 << LIN_BITS (i.e. 2^LIN_BITS - 1)
+  LIN_BITS = 6
+
+  MODES         = [ :asc, :desc, :asc_geq, :desc_leq, :asc_eq, :desc_eq ]
+  MODE_IS_ASC   = [ :asc, :asc_eq, :asc_geq ]
+  MODE_IS_DESC  = [ :desc, :desc_eq, :desc_leq ]
+  MODE_CHECK_EQ = [ :asc_eq, :desc_eq ]
+
+  module Methods
+
+    # Binary search for the first elem in this array matching according to mode in the range
+    # (low..high-1)
+    #
+    # By default, <=> is used to compare elements.  Alternatively, a comparator
+    # may be specified as block parameter
+    #
+    # The supported modes are
+    # * :asc - array is expected to be sorted in ascending order, first geq elem is matched
+    # * :asc_eq - array expected to be sorted in ascending order, first eq elem is matched
+    # * :desc - array is expected to be sorted in descending order, first leq elem is matched
+    # * :desc_eq - array is expected to be sorted in descending order, first eq elem is matched
+    #
+    # @param [Object] elem elem to search for
+    # @param [Fixnum] low lower bound (inclusive)
+    # @param [Fixnum] high upper bound (inclusive, -1 for last element)
+    # @param [:asc, :desc, :asc_eq, :desc_eq] mode matching mode
+    # @return [Fixnum] index of first matching elem in self, or -1 if not found
+    #
+    def bin_index(elem, mode, low = 0, high = -1)
+      dir      = if ::BinSearch::MODE_IS_ASC.include?(mode) then +1 else -1 end
+      check_eq = ::BinSearch::MODE_CHECK_EQ.include?(mode)
+      high     = size - 1 if high < 0
+      if block_given?
+        then _bin_index(elem, low, high, dir, check_eq) { |b| yield elem, b }
+        else _bin_index(elem, low, high, dir, check_eq) { |b| elem <=> b } end
+    end
+
+    # Binary search for the first elem in this array matching according to mode in the range
+    # (low..high-1)
+    #
+    # Elements are compared using <=> after mapping them using the provided block
+    #
+    # The supported modes are
+    # * :asc - array is expected to be sorted in ascending order, first geq elem is matched
+    # * :asc_eq - array expected to be sorted in ascending order, first eq elem is matched
+    # * :desc - array is expected to be sorted in descending order, first leq elem is matched
+    # * :desc_eq - array is expected to be sorted in descending order, first eq elem is matched
+    #
+    # @param [Object] elem elem to search for
+    # @param [Fixnum] low lower bound (inclusive)
+    # @param [Fixnum] high upper bound (inclusive, -1 for last element)
+    # @param [:asc, :desc, :asc_eq, :desc_eq] mode matching mode
+    # @return [Fixnum] index of first matching elem in self, or -1 if not found
+    #
+    def bin_index_by(elem, mode, low = 0, high = -1)
+      dir      = if ::BinSearch::MODE_IS_ASC.include?(mode) then +1 else -1 end
+      check_eq = ::BinSearch::MODE_CHECK_EQ.include?(mode)
+      high     = size - 1 if high < 0
+      e        = yield elem
+      _bin_index(elem, low, high, dir, check_eq) { |b| e <=> (yield b) }
+    end
+
+    # Binary search for the first elem in this array matching according to mode in the range
+    # (low..high-1)
+    #
+    # By default, <=> is used to compare elements.  Alternatively, a comparator
+    # may be specified as block parameter
+    #
+    # The supported modes are
+    # * :asc - array is expected to be sorted in ascending order, first geq elem is matched
+    # * :asc_eq - array expected to be sorted in ascending order, first eq elem is matched
+    # * :desc - array is expected to be sorted in descending order, first leq elem is matched
+    # * :desc_eq - array is expected to be sorted in descending order, first eq elem is matched
+    #
+    # @param [Object] elem elem to search for
+    # @param [Fixnum] low lower bound (inclusive)
+    # @param [Fixnum] high upper bound (inclusive, nil for last element)
+    # @param [:asc, :desc, :asc_eq, :desc_eq] mode matching mode
+    # @return [Object] first matching elem in self, or nil if not found
+    #
+    def bin_search(elem, mode, low = 0, high = -1)
+      dir      = if ::BinSearch::MODE_IS_ASC.include?(mode) then +1 else -1 end
+      check_eq = ::BinSearch::MODE_CHECK_EQ.include?(mode)
+      high     = size - 1 if high < 0
+      if block_given?
+        then _bin_search(elem, low, high, dir, check_eq) { |b| yield elem, b }
+        else _bin_search(elem, low, high, dir, check_eq) { |b| elem <=> b } end
+    end
+
+    # Binary search for the first elem in this array matching according to mode in the range
+    # (low..high-1)
+    #
+    # Elements are compared using <=> after mapping them using the provided block
+    #
+    # The supported modes are
+    # * :asc - array is expected to be sorted in ascending order, first geq elem is matched
+    # * :asc_eq - array expected to be sorted in ascending order, first eq elem is matched
+    # * :desc - array is expected to be sorted in descending order, first leq elem is matched
+    # * :desc_eq - array is expected to be sorted in descending order, first eq elem is matched
+    #
+    # @param [Object] elem elem to search for
+    # @param [Fixnum] low lower bound (inclusive)
+    # @param [Fixnum] high upper bound (inclusive, nil for last element)
+    # @param [:asc, :desc, :asc_eq, :desc_eq] mode matching mode
+    # @return [Object] first matching elem in self, or nil if not found
+    #
+    def bin_search_by(elem, mode, low = 0, high = -1)
+      dir      = if ::BinSearch::MODE_IS_ASC.include?(mode) then +1 else -1 end
+      check_eq = ::BinSearch::MODE_CHECK_EQ.include?(mode)
+      high     = size - 1 if high < 0
+      e        = yield elem
+      _bin_search(elem, low, high, dir, check_eq) { |b| e <=> (yield b) }
+    end
+
+    # Binary search for the first elem in this array matching according to mode in the range
+    # (low..high-1)
+    #
+    # By default, <=> is used to compare elements.  Alternatively, a comparator
+    # may be specified as block parameter
+    #
+    # The supported modes are
+    # * :asc - array is expected to be sorted in ascending order, first geq elem is matched
+    # * :asc_eq - array expected to be sorted in ascending order, first eq elem is matched
+    # * :desc - array is expected to be sorted in descending order, first leq elem is matched
+    # * :desc_eq - array is expected to be sorted in descending order, first eq elem is matched
+    #
+    # @param [Object] elem elem to search for
+    # @param [Fixnum] low lower bound (inclusive)
+    # @param [Fixnum] high upper bound (inclusive, nil for last element)
+    # @param [:asc, :desc, :asc_eq, :desc_eq] mode matching mode
+    # @return [Array] [index, first matching elem] in self, or nil if not found
+    #
+    def bin_assoc(elem, mode, low = 0, high = -1)
+      dir      = if ::BinSearch::MODE_IS_ASC.include?(mode) then +1 else -1 end
+      check_eq = ::BinSearch::MODE_CHECK_EQ.include?(mode)
+      high     = size - 1 if high < 0
+      if block_given?
+        then _bin_assoc(elem, low, high, dir, check_eq) { |b| yield elem, b }
+        else _bin_assoc(elem, low, high, dir, check_eq) { |b| elem <=> b } end
+    end
+
+    # Binary search for the first elem in this array matching according to mode in the range
+    # (low..high-1)
+    #
+    # Elements are compared using <=> after mapping them using the provided block
+    #
+    # The supported modes are
+    # * :asc - array is expected to be sorted in ascending order, first geq elem is matched
+    # * :asc_eq - array expected to be sorted in ascending order, first eq elem is matched
+    # * :desc - array is expected to be sorted in descending order, first leq elem is matched
+    # * :desc_eq - array is expected to be sorted in descending order, first eq elem is matched
+    #
+    # @param [Object] elem elem to search for
+    # @param [Fixnum] low lower bound (inclusive)
+    # @param [Fixnum] high upper bound (inclusive, nil for last element)
+    # @param [:asc, :desc, :asc_eq, :desc_eq] mode matching mode
+    # @return [Array] [index, first matching elem] in self, or nil if not found
+    #
+    def bin_assoc_by(elem, mode, low = 0, high = -1)
+      dir      = if ::BinSearch::MODE_IS_ASC.include?(mode) then +1 else -1 end
+      check_eq = ::BinSearch::MODE_CHECK_EQ.include?(mode)
+      high     = size - 1 if high < 0
+      e        = yield elem
+      _bin_assoc(elem, low, high, dir, check_eq) { |b| e <=> (yield b) }
+    end
+
+    private
+
+    def _bin_index(elem, low, high, dir, check_eq)
+      sz   = high - low
+      if (sz >> LIN_BITS).zero?
+        # On 2012 cpus, linear search is slightly faster than binary search
+        # if the number of searched elements is in the range of 50-100 elts
+        cur_index = low
+        while cur_index <= high
+          cur = self[cur_index]
+          cmp = yield cur
+          if cmp == dir
+            then cur_index += 1
+            else return (if (check_eq && cmp.nonzero?) then -1 else cur_index end) end
+        end
+        return -1
+      else
+        # Classic binary search
+        cmp_ = 0
+        last = -1
+        while low <= high
+          mid_index = low + (sz >> 1)
+          mid = self[mid_index]
+          cmp = yield mid
+          if cmp == dir
+            low  = mid_index + 1
+          else
+            cmp_ = cmp
+            last = mid_index
+            high = mid_index - 1
+          end
+          sz -= 1
+        end
+        return (if (check_eq && cmp_.nonzero?) then -1 else last end)
+      end
+    end
+
+    def _bin_search(elem, low, high, dir, check_eq)
+      sz   = high - low
+      cur  = nil
+      if (sz >> LIN_BITS).zero?
+        # On 2012 cpus, linear search is slightly faster than binary search
+        # if the number of searched elements is in the range of 50-100 elts
+        cur_index = low
+        while cur_index <= high
+          cur = self[cur_index]
+          cmp = yield cur
+          if cmp == dir
+            then cur_index += 1
+            else return (if (check_eq && cmp.nonzero?) then nil else cur end) end
+        end
+        return nil
+      else
+        # Classic binary search
+        cmp_ = 0
+        last = -1
+        while low <= high
+          mid_index = low + (sz >> 1)
+          mid = self[mid_index]
+          cmp = yield mid
+          if cmp == dir
+            low  = mid_index + 1
+          else
+            cmp_ = cmp
+            cur  = mid
+            last = mid_index
+            high = mid_index - 1
+          end
+          sz -= 1
+        end
+        return (if (check_eq && cmp_.nonzero?) then nil else cur end)
+      end
+    end
+
+    def _bin_assoc(elem, low, high, dir, check_eq)
+      sz   = high - low
+      cur  = nil
+      if (sz >> LIN_BITS).zero?
+        # On 2012 cpus, linear search is slightly faster than binary search
+        # if the number of searched elements is in the range of 50-100 elts
+        cur_index = low
+        while cur_index <= high
+          cur = self[cur_index]
+          cmp = yield cur
+          if cmp == dir
+            cur_index += 1
+          else
+            return (if (!cur || (check_eq && cmp.nonzero?)) then nil else [cur_index, cur] end)
+          end
+        end
+        return nil
+      else
+        # Classic binary search
+        cmp_ = 0
+        last = -1
+        while low <= high
+          mid_index = low + (sz >> 1)
+          mid = self[mid_index]
+          cmp = yield mid
+          if cmp == dir
+            low  = mid_index + 1
+          else
+            cmp_ = cmp
+            cur  = mid
+            last = mid_index
+            high = mid_index - 1
+          end
+          sz -= 1
+        end
+        return (if (!cur || (check_eq && cmp_.nonzero?)) then nil else [last, cur] end)
+      end
+    end
+
+  end # module Methods
+
+end # module BinSeach
+
+class ::Array
+  include ::BinSearch::Methods
+end

data/lib/bin_search/version.rb

@@ -0,0 +1,3 @@
+module BinSearch
+  VERSION = '0.1'
+end

data/spec/lib/bin_search/bin_search_spec.rb

@@ -0,0 +1,151 @@
+require 'bin_search'
+
+describe ::BinSearch do
+
+  context "Small arrays (:asc, :asc_eq)" do
+
+    it "should find the first element" do
+      [1, 2, 2, 3, 5].bin_index(1, :asc).should be_==(0)
+    end
+
+    it "should find the first element when queried using a smaller element" do
+      [1, 2, 2, 3, 5].bin_index(0, :asc).should be_==(0)
+    end
+
+    it "should find a middle element" do
+      [1, 2, 2, 3, 5].bin_index(2, :asc).should be_==(1)
+    end
+
+    it "should find the last element" do
+      [1, 2, 2, 3, 5].bin_index(5, :asc).should be_==(4)
+    end
+
+    it "should not find a missing element" do
+      [1, 2, 2, 3, 5].bin_index(6, :asc).should be_==(-1)
+    end
+
+    it "should not find an element that is not eq if called with equality checking turned on" do
+      [1, 2, 2, 3, 5].bin_index(2.5, :asc_eq).should be_==(-1)
+    end
+
+  end
+
+  context "Large arrays (:asc, :asc_eq)" do
+
+    it "should find the first element" do
+      Range.new(1, 10000).to_a.bin_index(1, :asc).should be_==(0)
+    end
+
+    it "should find the first element when queried using a smaller element" do
+      Range.new(1, 10000).to_a.bin_index(0, :asc).should be_==(0)
+    end
+
+    it "should find a middle element" do
+      Range.new(1, 10000).to_a.bin_index(5000, :asc).should be_==(4999)
+    end
+
+    it "should find the last element" do
+      Range.new(1, 10000).to_a.bin_index(10000, :asc).should be_==(9999)
+    end
+
+    it "should not find a missing element" do
+      Range.new(1, 10000).to_a.bin_index(10001, :asc).should be_==(-1)
+    end
+
+    it "should not find an element that is not eq if called with equality checking turned on" do
+      Range.new(1, 10000).to_a.bin_index(5000.5, :asc_eq).should be_==(-1)
+    end
+
+  end
+
+  context "Small arrays (:desc, :desc_eq)" do
+
+    it "should find the first element" do
+      [1, 2, 2, 3, 5].reverse.bin_index(5, :desc).should be_==(0)
+    end
+
+    it "should find the first element when queried using a larger element" do
+      [1, 2, 2, 3, 5].bin_index(6, :desc).should be_==(0)
+    end
+
+    it "should find a middle element" do
+      [1, 2, 2, 3, 5].reverse.bin_index(2, :desc).should be_==(2)
+    end
+
+    it "should find the last element" do
+      [1, 2, 2, 3, 5].reverse.bin_index(1, :desc).should be_==(4)
+    end
+
+    it "should not find a missing element" do
+      [1, 2, 2, 3, 5].reverse.bin_index(0, :desc).should be_==(-1)
+    end
+
+    it "should not find an element that is not eq if called with equality checking turned on" do
+      [1, 2, 2, 3, 5].reverse.bin_index(2.5, :desc_eq).should be_==(-1)
+    end
+
+  end
+
+  context "Large arrays (:desc, :desc_eq)" do
+
+    it "should find the first element" do
+      Range.new(1, 10000).to_a.reverse.bin_index(10000, :desc).should be_==(0)
+    end
+
+    it "should find the first element when queried using a larger element" do
+      Range.new(1, 10000).to_a.reverse.bin_index(10001, :desc).should be_==(0)
+    end
+
+    it "should find a middle element" do
+      Range.new(1, 10000).to_a.reverse.bin_index(5000, :desc).should be_==(5000)
+    end
+
+    it "should find the last element" do
+      Range.new(1, 10000).to_a.reverse.bin_index(1, :desc).should be_==(9999)
+    end
+
+    it "should not find a missing element" do
+      Range.new(1, 10000).to_a.reverse.bin_index(0, :desc).should be_==(-1)
+    end
+
+    it "should not find an element that is not eq if called with equality checking turned on" do
+      Range.new(1, 10000).to_a.reverse.bin_index(5000.5, :desc_eq).should be_==(-1)
+    end
+
+  end
+
+  context "API" do
+
+    it "should return the found element when called via bin_search" do
+      [1, 2, 2, 3, 5].bin_search(2, :asc).should be_==(2)
+    end
+
+    it "should return nil when called via bin_search with a missing element" do
+      [1, 2, 2, 3, 5].bin_search(10, :asc).should be_==(nil)
+    end
+
+    it "should return the found element's assoc pair when called via bin_assoc" do
+      [1, 2, 2, 3, 5].bin_assoc(2, :asc).should be_==([1, 2])
+    end
+
+    it "should return nil when called via bin_assoc with a missing element" do
+      [1, 2, 2, 3, 5].bin_assoc(10, :asc).should be_==(nil)
+    end
+
+  end
+
+  context "Comparator wrapping" do
+
+    it 'should use a provided comparator with bin_index' do
+      idx = [1, 2, 2, 3, 5].reverse.bin_index(2, :asc) { |a, b| b <=> a }
+      idx.should be_==(2)
+    end
+
+    it 'should use a provided mapper with bin_index_by' do
+      idx = [1, 2, 2, 3, 5].reverse.bin_index_by(2, :asc) { |a| -a }
+      idx.should be_==(2)
+    end
+
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler.require

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: bin_search
+version: !ruby/object:Gem::Version
+  version: '0.1'
+  prerelease: 
+platform: ruby
+authors:
+- Stefan Plantikow
+autorequire: 
+bindir: script
+cert_chain: []
+date: 2012-05-28 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70278990982880 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70278990982880
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: &70278990982460 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70278990982460
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70278973891460 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70278973891460
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &70278973891040 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70278973891040
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: &70278973890620 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70278973890620
+description: Pure ruby implementation of binary search for Ruby arrays and similiar
+  data structures.  Supports ascending and descending sort order, searching for exact
+  and nearest matches, and has a versatile API.  Uses linear search for small arrays
+  to make use of the internal cache of moden CPUs.
+email: stefan.plantikow@googlemail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- AUTHORS
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin_search.gemspec
+- lib/bin_search.rb
+- lib/bin_search/bin_search.rb
+- lib/bin_search/version.rb
+- spec/lib/bin_search/bin_search_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/boggle/bin_search
+licenses:
+- PUBLIC DOMAIN WITHOUT ANY WARRANTY
+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: bin_search
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Binary search in sorted arrays
+test_files:
+- spec/lib/bin_search/bin_search_spec.rb
+- spec/spec_helper.rb
+has_rdoc: