union_find 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3d86fb59ebdb3b6b5f55e175db95bd7dccf0126b
+  data.tar.gz: 8dfbcfdff8f2a1f20e808df6404312bbd2793967
+SHA512:
+  metadata.gz: fee3e76ee13f5c64e8b8f278e8c42ac0ebb979603bc3b1e19b4e76980ba8128c9c1fd594c31d04006f61149afbf86b364cd71d0f59a2206aa7140d3350f13096
+  data.tar.gz: 280542a0d35dc79eb7343f3efd350e8ea8629a47377cb9b04ae58076b9e3da45f983ffa5ce522518515bbef974746a097b16dfd8b87db09f8b93bbb1928b98b5

data/.gitignore

@@ -0,0 +1,24 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.ruby-gemset
+.ruby-version

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in union_find.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Michael Imstepf
+
+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,72 @@
+# Weighted quick-union algorithm with path compression
+
+Union Find is an algorithm that uses a disjoint-set data structure. It allows us to efficiently connect any items of a given list and to efficiently check whether two items of this list are connected (any degree of separation) or not.
+
+Possible applications where we might want to find out whether two items are connected to each other are:
+* Social networks
+* Computers in a network
+* Web pages on the Internet
+* Transistors in a computer chip
+* Pixels in a digital photo
+* Metallic sites in a composite system
+
+Click [here](https://www.cs.princeton.edu/~rs/AlgsDS07/01UnionFind.pdf) for more information.
+
+The running time of this algorithm is linear.
+
+This a Ruby implementation of [Robert Sedgewick](http://www.cs.princeton.edu/~rs/)'s and [Kevin Wayne](http://www.cs.princeton.edu/~wayne/contact/)'s [weighted quick-union algorithm with path compression](http://algs4.cs.princeton.edu/15uf/UF.java.html). Credit goes to these two authors of the book [Algorithms](http://www.amazon.com/gp/product/032157351X/ref=as_li_qf_sp_asin_il_tl?ie=UTF8&tag=algs4-20&linkCode=as2&camp=1789&creative=9325&creativeASIN=032157351X) and to the many computer scientists that have contributed to this algorithm in the past decades.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'union_find'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install union_find
+
+## Usage
+
+Create a new instance of `UnionFind` and pass in an array of items:
+
+```ruby
+union_find = UnionFind::UnionFind.new(['Grandfather', 'Father', 'Daughter', 'Single Person'])
+```
+
+Connect items (in any order):
+
+```ruby
+union_find.union('Grandfather', 'Father')
+union_find.union('Father', 'Daughter')
+```
+
+Check whether two items are connected (in any order):
+
+```ruby
+union_find.connected?('Grandfather', 'Daughter')
+=> true
+union_find.connected?('Daughter', 'Father')
+=> true
+union_find.connected?('Grandfather', 'Single Person')
+=> false
+```
+
+Check how many isolated items there are. In this example, there are 2, namely the family the family tree (Grandfather - Father - Daugther) and the Single Person:
+
+```ruby
+union_find.count_isolated_components
+=> 2
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/union_find/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/lib/union_find/version.rb

@@ -0,0 +1,3 @@
+module UnionFind
+  VERSION = "0.0.1"
+end

data/lib/union_find.rb

@@ -0,0 +1,106 @@
+require 'union_find/version'
+
+module UnionFind
+
+# The UnionFind class represents a union-find data type
+# (also known as the disjoint-sets data type).
+# It supports the union and find operations,
+# along with a connected operation for determinig whether
+# two sites in the same component are connected and a count operation that
+# returns the total number of components.
+
+# This implementation uses weighted quick union by rank with path compression
+# by halving.
+
+# Initializing a data structure with number_of_components sites takes linear time.
+# Afterwards, the union, find, and connected 
+# operations take logarithmic time (in the worst case) and the
+# count operation takes constant time.
+
+# @author Robert Sedgewick
+# @author Kevin Wayne
+# @author Michael Imstepf
+# @see http://algs4.cs.princeton.edu/15uf/UF.java.html
+# @see http://algs4.cs.princeton.edu/15uf/
+class UnionFind
+
+  # Initializes an empty union-find data structure with
+  # n isolated components 0 through n-1.
+  # @param components [Array] components
+  # @raise [ArgumentError] if components.length < 1 or if components is not an Array
+  def initialize(components)
+    raise ArgumentError, 'input is not an Array' unless components.class == Array   
+
+    components = components.uniq # remove duplicates
+    @number_of_isolated_components = components.length
+    
+    raise ArgumentError, 'number of components is < 1' if @number_of_isolated_components < 1         
+
+    @parent = {} # parent of i
+    @tree_size = {} # size of tree rooted at i (cannot be more than 31)
+    components.each do |component|
+      @parent[component] = component
+      @tree_size[component] = 1
+    end
+  end
+
+  # Returns the number of isolated components.
+  # @return [Interger] the number of components
+  def count_isolated_components
+    @number_of_isolated_components
+  end
+
+  # Returns the root of a component.
+  # @param component_id [Integer] the integer representing one component
+  # @return [Component] the root of the component
+  # @raise [IndexError] unless component exists
+  def find_root(component)
+    raise IndexError, 'component does not exist' unless @parent[component]
+    
+    while component != @parent[component] # stop at the top node where component id == parent id
+      @parent[component] = @parent[@parent[component]] # path compression by halving
+      component = @parent[component]
+    end
+
+    return component
+  end
+
+  # Connect root of component 1 with root of component 2
+  # by attaching smaller subtree root node with larger tree.
+  # If both trees have the same size, the root of the second
+  # component becomes a child of the root of the first component.
+  # @param component_1_id [Integer] the integer representing one component
+  # @param component_2_id [Integer] the integer representing the other component
+  # @return [Component, NilClass] the root of the larger tree or the root of the first component if both have the same tree size or nil if no connection has been made
+  def union(component_1, component_2)
+    root_component_1 = find_root(component_1)
+    root_component_2 = find_root(component_2)
+
+    return nil if root_component_1 == root_component_2
+
+    # make smaller root point to larger one
+    if @tree_size[root_component_1] < @tree_size[root_component_2]
+      @parent[root_component_1] = root_component_2
+      root = root_component_2
+      @tree_size[root_component_2] += @tree_size[root_component_1]
+    else
+      @parent[root_component_2] = root_component_1
+      root = root_component_1
+      @tree_size[root_component_1] += @tree_size[root_component_2]
+    end
+    
+    @number_of_isolated_components -= 1
+
+    root
+  end  
+
+  # Do two components share the same root?
+  # @param component_1 [Integer] the integer representing one component
+  # @param component_2 [Integer] the integer representing the other component     
+  # @return [Boolean]
+  def connected?(component_1, component_2)
+    find_root(component_1) == find_root(component_2)
+  end
+end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,23 @@
+require 'union_find'
+require 'pry' # to use binding.pry
+
+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'
+  
+  # when a focus tag is present in RSpec, only run tests with focus tag: http://railscasts.com/episodes/285-spork
+  config.filter_run focus: true
+  config.run_all_when_everything_filtered = true  
+end
+
+def create_family_tree(union_find)
+  union_find.union('Grandfather', 'Father')
+  union_find.union('Grandfather', 'Mother')
+  union_find.union('Mother', 'Son')
+  union_find.union('Father', 'Daughter')
+
+  union_find
+end

data/spec/union_find_spec.rb

@@ -0,0 +1,119 @@
+require 'spec_helper'
+random = Random.new
+
+describe UnionFind::UnionFind do
+  # 1 family and 1 single person
+  people = ['Grandfather', 'Father', 'Mother', 'Son', 'Daughter', 'Single']
+
+  describe '#initialize' do    
+    context 'when no components are provided' do
+      it 'raises an exception' do
+        expect {UnionFind::UnionFind.new()}.to raise_exception(ArgumentError)
+      end            
+    end
+
+    context 'when components in form other than Array are provided' do
+      it 'raises an exception' do
+        expect {UnionFind::UnionFind.new('Some Person')}.to raise_exception(ArgumentError)
+      end            
+    end         
+  end
+
+  describe '#find_root' do
+    union_find = UnionFind::UnionFind.new(people)
+
+    context 'when component does not exist' do
+      it 'raises an exception' do
+        expect {union_find.find_root('Some Person')}.to raise_exception(IndexError)
+      end  
+    end
+
+    context 'when component exists' do
+      context 'when component has no parent' do
+        it 'returns same component' do
+          expect(union_find.find_root('Single')).to eq 'Single'
+        end        
+      end
+
+      context 'when component has parent' do
+        create_family_tree(union_find)
+        
+        it 'returns parent' do
+          expect(union_find.find_root('Daughter')).to eq 'Grandfather'
+        end        
+      end
+    end
+  end  
+
+  describe '#union' do
+    context 'when one component gets connected to itself' do
+      union_find = UnionFind::UnionFind.new(people)      
+      
+      it 'returns the component' do
+        expect(union_find.union('Grandfather', 'Grandfather')).to be_nil
+      end
+    end
+
+    context 'when one unconnected component gets connected to another unconnected component' do
+      union_find = UnionFind::UnionFind.new(people)            
+      
+      it 'returns the first component' do
+        expect(union_find.union('Grandfather', 'Father')).to eq 'Grandfather'
+      end
+    end
+
+    context 'when one unconnected component gets connected to a connected component' do
+      union_find = UnionFind::UnionFind.new(people)                  
+      create_family_tree(union_find)
+      
+      it 'connects and returns the root of the larger tree' do
+        expect(union_find.union('Single', 'Father')).to eq 'Grandfather'
+        expect(union_find.connected?('Father', 'Single')).to be_truthy
+        expect(union_find.find_root('Father')).to eq 'Grandfather'
+        expect(union_find.find_root('Single')).to eq 'Grandfather'                
+      end
+    end         
+  end
+
+  describe '#connected?' do
+    union_find = UnionFind::UnionFind.new(people)
+    create_family_tree(union_find)
+
+    context 'when two components are not connected' do
+      it 'returns false' do
+        expect(union_find.connected?('Father', 'Single')).to be_falsey
+      end
+    end
+
+    context 'when two components are the same' do
+      it 'returns false' do
+        expect(union_find.connected?('Father', 'Father')).to be_truthy
+      end
+    end
+
+    context 'when two components are connected' do
+      it 'returns false' do
+        expect(union_find.connected?('Grandfather', 'Daughter')).to be_truthy
+      end
+    end         
+  end
+
+  describe '#count_isolated_components' do
+    context 'when no connections have been made' do
+      union_find = UnionFind::UnionFind.new(people)
+
+      it 'returns number of components' do
+        expect(union_find.count_isolated_components).to eq people.size        
+      end 
+    end
+
+    context 'when connections have been made' do
+      union_find = UnionFind::UnionFind.new(people)
+      create_family_tree(union_find)
+
+      it 'returns number of components' do
+        expect(union_find.count_isolated_components).to eq 2        
+      end
+    end
+  end   
+end  

data/union_find.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'union_find/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "union_find"
+  spec.version       = UnionFind::VERSION
+  spec.authors       = ["Michael Imstepf"]
+  spec.email         = ["michael.imstepf@gmail.com"]
+  spec.summary       = %q{Weighted quick-union algorithm with path compression.}
+  spec.description   = %q{Union Find is an algorithm that uses a disjoint-set data structure. It allows us to efficiently connect any items of a given list and to efficiently check whether two items of this list are connected (any degree of separation) or not.}
+  spec.homepage      = "https://github.com/michaelimstepf/union-find"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "pry"  
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: union_find
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Michael Imstepf
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-06-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Union Find is an algorithm that uses a disjoint-set data structure. It
+  allows us to efficiently connect any items of a given list and to efficiently check
+  whether two items of this list are connected (any degree of separation) or not.
+email:
+- michael.imstepf@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/union_find.rb
+- lib/union_find/version.rb
+- spec/spec_helper.rb
+- spec/union_find_spec.rb
+- union_find.gemspec
+homepage: https://github.com/michaelimstepf/union-find
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Weighted quick-union algorithm with path compression.
+test_files:
+- spec/spec_helper.rb
+- spec/union_find_spec.rb