segment_tree 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in segment_tree.gemspec
+gemspec
+
+gem "simplecov", "~> 0.6.4"

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Alexei Mikhailov
+
+MIT License
+
+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,94 @@
+# SegmentTree
+
+Ruby implementation of [segment tree](http://en.wikipedia.org/wiki/Segment_tree) data structure.
+Segment tree is a tree data structure for storing intervals, or segments. It allows querying which of the stored segments contain a given point. It is, in principle, a static structure; that is, its content cannot be modified once the structure is built.
+
+Segment tree storage has the complexity of <tt>O(n log n)</tt>.
+Segment tree querying has the complexity of <tt>O(log n + k)</tt> where <tt>k</tt> is the number of reported intervals.
+
+It's pretty fast on querying trees with ~ 10 millions segments, though building of such big tree will take long.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'segment_tree'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install segment_tree
+
+## Usage
+
+Segment tree consists of segments (in Ruby it's <tt>Range</tt> objects) and corresponding values. The easiest way to build a segment tree is to create it from hash where segments are keys:
+```ruby
+tree = SegmentTree.new(1..10 => "a", 11..20 => "b", 21..30 => "c") # => #<SegmentTree:0xa47eadc @root=#<SegmentTree::Container:0x523f3b6 @range=1..30>>
+```
+
+After that you can query the tree of which segments contain a given point:
+```ruby
+tree.find(5) # => [#<SegmentTree::Segment:0xa47ea8c @range=1..10, @value="a">]
+```
+
+Or fetch only one segment:
+```ruby
+segment = tree.find_first(5) # => #<SegmentTree::Segment:0xa47ea8c @range=1..10, @value="a">
+segment.value # => "a"
+```
+
+## Real world example
+
+Segment tree can be used in applications where IP-address geocoding is needed.
+
+```ruby
+data = [
+  [IPAddr.new('87.224.241.0/24').to_range, {:city => "YEKT"}],
+  [IPAddr.new('195.58.18.0/24').to_range, {:city => "MSK"}]
+  # and so on
+]
+ip_tree = SegmentTree.new(data)
+
+client_ip = IPAddr.new("87.224.241.66")
+ip_tree.find_first(client_ip).value # => {:city=>"YEKT"}
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## TODO
+1. Fix README typos and grammatical errors (english speaking contributors are welcomed)
+2. Implement C binding for MRI.
+3. Test on different versions of Ruby.
+
+## LICENSE
+Copyright (c) 2012 Alexei Mikhailov
+
+MIT License
+
+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/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/benchmark/benchmark.rb

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+require "bundler/setup"
+require "benchmark"
+require "segment_tree"
+
+# generate a tree with +n+ number of intervals
+def tree(n)
+  SegmentTree.new list(n)
+end
+def list(n)
+  (0..n).map { |num| [(num * 10)..(num + 1) * 10 - 1, num] }
+end
+
+puts "Pregenerating data..."
+tests = [100, 1000, 10_000, 100_000, 1_000_000]
+
+lists = Hash[tests.map { |n| [n, list(n)] }]
+trees = Hash[tests.map { |n| [n, tree(n)] }]
+
+puts "Done"
+puts
+
+puts "Building a tree of N intervals"
+Benchmark.bmbm do |x|
+  tests.each do |n|
+    x.report(n.to_s) { tree(n) }
+  end
+end
+
+puts "Finding matching interval in tree of N intervals"
+Benchmark.bmbm do |x|
+  tests.each do |n|
+    t = trees[n]
+
+    x.report(n.to_s) { t.find_first(rand(n)) }
+  end
+end
+
+puts
+puts "Finding matching interval in list of N intervals"
+Benchmark.bmbm do |x|
+  tests.each do |n|
+    data = lists[n]
+
+    x.report(n.to_s) { data.find { |range, _| range.cover?(rand(n)) } }
+  end
+end

data/lib/segment_tree.rb

@@ -0,0 +1,104 @@
+require "forwardable"
+require "segment_tree/version"
+
+class SegmentTree
+  # An abstract tree node
+  class Node #:nodoc:all:
+    extend Forwardable
+    def_delegators :@range, :cover?, :begin, :end
+  end
+
+  # An elementary intervals or nodes container
+  class Container < Node #:nodoc:all:
+    extend Forwardable
+
+    attr_reader :left, :right
+
+    # Node constructor, accepts both +Node+ and +Segment+
+    def initialize(left, right)
+      @left, @right = left, right
+
+      @range = left.begin..(right || left).end
+    end
+
+    # Find all intervals containing point +x+ within node's children. Returns array
+    def find(x)
+      [@left, @right].compact.
+                      select { |node| node.cover?(x) }.
+                      map    { |node| node.find(x) }.
+                      flatten
+    end
+
+    # Find first interval containing point +x+ within node's children
+    def find_first(x)
+      subset = [@left, @right].compact.find { |node| node.cover?(x) }
+      subset && subset.find_first(x)
+    end
+
+    # Do not expose left and right, otherwise output shall be too long on large trees
+    def inspect
+      "#<#{self.class.name}:0x#{object_id.to_s(16)} @range=#{@range.inspect}>"
+    end
+  end
+
+  # An elementary interval
+  class Segment < Node #:nodoc:all:
+    attr_reader :value
+
+    def initialize(range, value)
+      raise ArgumentError, 'Range expected, %s given' % range.class.name unless range.is_a?(Range)
+
+      @range, @value = range, value
+    end
+
+    def find(x)
+      [find_first(x)].compact
+    end
+
+    def find_first(x)
+      cover?(x) ? self : nil
+    end
+  end
+
+  # Build a segment tree from +data+.
+  #
+  # Data can be one of the following:
+  # 1. Hash - a hash, where ranges are keys,
+  #    i.e. <code>{(0..3) => some_value1, (4..6) => some_value2, ...}<code>
+  # 2. 2-dimensional array - an array of arrays where first element of
+  #    each element is range, and second is value:
+  #    <code>[[(0..3), some_value1], [(4..6), some_value2] ...]<code>
+  def initialize(data)
+    # build elementary segments
+    nodes = case data
+      when Hash, Array, Enumerable then
+        data.collect { |range, value| Segment.new(range, value) }
+      else raise ArgumentError, '2-dim Array or Hash expected'
+    end.sort! do |x, y|
+      # intervals are sorted from left to right, from shortest to longest
+      x.begin == y.begin ?
+          x.end <=> y.end :
+          x.begin <=> y.begin
+    end
+
+    # now build binary tree
+    while nodes.length > 1
+      nodes = nodes.each_slice(2).collect { |left, right| Container.new(left, right) }
+    end
+
+    # root node is first node or nil when tree is empty
+    @root = nodes.first
+  end
+
+  # Find all intervals containing point +x+
+  # @return [Array]
+  def find(x)
+    @root ? @root.find(x) : []
+  end
+
+  # Find first interval containing point +x+.
+  # @return [Segment|NilClass]
+  def find_first(x)
+    @root && @root.find_first(x)
+  end
+end

data/lib/segment_tree/version.rb

@@ -0,0 +1,3 @@
+class SegmentTree
+  VERSION = "0.0.1"
+end

data/segment_tree.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/segment_tree/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.author        = "Alexei Mikhailov"
+  gem.email         = "amikhailov83@gmail.com"
+  gem.description   = %q{Tree data structure for storing segments. It allows querying which of the stored segments contain a given point.}
+  gem.summary       = %q{Tree data structure for storing segments. It allows querying which of the stored segments contain a given point.}
+  gem.homepage      = "https://github.com/take-five/segment_tree"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "segment_tree"
+  gem.require_paths = %W(lib)
+  gem.version       = SegmentTree::VERSION
+
+  gem.add_development_dependency "bundler", ">= 1.0"
+  gem.add_development_dependency "rspec", ">= 2.11"
+end

data/spec/segment_tree_spec.rb

@@ -0,0 +1,169 @@
+require "spec_helper"
+require "segment_tree"
+
+describe SegmentTree do
+  # some fixtures
+  # [[0..9, "a"], [10..19, "b"], ..., [90..99, "j"]] - spanned intervals
+  let(:sample_spanned) { (0..9).zip("a".."j").map { |num, letter| [(num * 10)..(num + 1) * 10 - 1, letter] } }
+  # [[0..12, "a"], [10..22, "b"], ..., [90..102, "j"]] - partially overlapping intervals
+  let(:sample_overlapping) { (0..9).zip("a".."j").map { |num, letter| [(num * 10)..(num + 1) * 10 + 2, letter] } }
+  # [[0..5, "a"], [10..15, "b"], ..., [90..95, "j"]] - sparsed intervals
+  let(:sample_sparsed) { (0..9).zip("a".."j").map { |num, letter| [(num * 10)..(num + 1) * 10 - 5, letter] } }
+
+  describe ".new" do
+    context "given a hash with ranges as keys" do
+      let :data do
+        {0..3 => "a",
+         4..6 => "b",
+         7..9 => "c",
+         10..12 => "d"}
+      end
+
+      subject(:tree) { SegmentTree.new(data) }
+
+      it { should be_a SegmentTree }
+
+      it "should have a root" do
+        root = tree.instance_variable_get :@root
+        root.should be_a SegmentTree::Container
+      end
+    end
+
+    context "given an array of arrays" do
+      let :data do
+        [[0..3, "a"],
+         [4..6, "b"],
+         [7..9, "c"],
+         [10..12, "d"]]
+      end
+
+      subject(:tree) { SegmentTree.new(data) }
+
+      it { should be_a SegmentTree }
+
+      it "should have a root" do
+        root = tree.instance_variable_get :@root
+        root.should be_a SegmentTree::Container
+      end
+    end
+
+    context "given nor hash neither array" do
+      it { expect{ SegmentTree.new(Object.new) }.to raise_error(ArgumentError) }
+    end
+
+    context "given 1-dimensional array" do
+      let :data do
+        [0..3, "a",
+         4..6, "b",
+         7..9, "c",
+         10..12, "d"]
+      end
+
+      it { expect{ SegmentTree.new(data) }.to raise_error(ArgumentError) }
+    end
+  end
+
+  describe "#find" do
+    context "given spanned intervals" do
+      let(:tree) { SegmentTree.new(sample_spanned) }
+
+      context "and looking up for existent point" do
+        subject { tree.find 12 }
+
+        it { should be_a Array }
+        it { should have_exactly(1).item }
+        its(:first) { should be_a SegmentTree::Segment }
+        its('first.value') { should eq 'b' }
+      end
+
+      context "and looking up for non-existent point" do
+        subject { tree.find 101 }
+
+        it { should be_a Array }
+        it { should be_empty }
+      end
+    end
+
+    context "given partially overlapping intervals" do
+      let(:tree) { SegmentTree.new(sample_overlapping) }
+
+      context "and looking up for existent point" do
+        subject { tree.find 11 }
+
+        it { should be_a Array }
+        it { should have_exactly(2).item }
+        its(:first) { should be_a SegmentTree::Segment }
+        its('first.value') { should eq 'a' }
+        its(:last) { should be_a SegmentTree::Segment }
+        its('last.value') { should eq 'b' }
+      end
+    end
+
+    context "given sparsed intervals" do
+      let(:tree) { SegmentTree.new(sample_sparsed) }
+
+      context "and looking up for existent point" do
+        subject { tree.find 12 }
+
+        it { should be_a Array }
+        it { should have_exactly(1).item }
+        its(:first) { should be_a SegmentTree::Segment }
+        its('first.value') { should eq 'b' }
+      end
+
+      context "and looking up for non-existent point" do
+        subject { tree.find 8 }
+
+        it { should be_a Array }
+        it { should be_empty }
+      end
+    end
+  end
+
+  describe "#find_first" do
+    context "given spanned intervals" do
+      let(:tree) { SegmentTree.new(sample_spanned) }
+
+      context "and looking up for existent point" do
+        subject { tree.find_first 12 }
+
+        it { should be_a SegmentTree::Segment }
+        its(:value) { should eq 'b' }
+      end
+
+      context "and looking up for non-existent point" do
+        subject { tree.find_first 101 }
+
+        it { should be_nil }
+      end
+    end
+
+    context "given partially overlapping intervals" do
+      let(:tree) { SegmentTree.new(sample_overlapping) }
+
+      context "and looking up for existent point" do
+        subject { tree.find_first 11 }
+
+        it { should be_a SegmentTree::Segment }
+        its(:value) { should eq 'a' }
+      end
+    end
+
+    context "given sparsed intervals" do
+      let(:tree) { SegmentTree.new(sample_sparsed) }
+
+      context "and looking up for existent point" do
+        subject { tree.find_first 12 }
+
+        it { should be_a SegmentTree::Segment }
+        its(:value) { should eq 'b' }
+      end
+
+      context "and looking up for non-existent point" do
+        subject { tree.find_first 8 }
+
+        it { should be_nil }
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+require "bundler/setup"
+require "simplecov"
+
+RSpec.configure do |config|
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end
+
+SimpleCov.start

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: segment_tree
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Alexei Mikhailov
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-08-01 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: &84177160 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: *84177160
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &84176910 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2.11'
+  type: :development
+  prerelease: false
+  version_requirements: *84176910
+description: Tree data structure for storing segments. It allows querying which of
+  the stored segments contain a given point.
+email: amikhailov83@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- benchmark/benchmark.rb
+- lib/segment_tree.rb
+- lib/segment_tree/version.rb
+- segment_tree.gemspec
+- spec/segment_tree_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/take-five/segment_tree
+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.17
+signing_key: 
+specification_version: 3
+summary: Tree data structure for storing segments. It allows querying which of the
+  stored segments contain a given point.
+test_files:
+- spec/segment_tree_spec.rb
+- spec/spec_helper.rb