union_find 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3d86fb59ebdb3b6b5f55e175db95bd7dccf0126b
-  data.tar.gz: 8dfbcfdff8f2a1f20e808df6404312bbd2793967
+  metadata.gz: 92740adf9b4c5f2dc335cbdfdc6bf7b2d938f89b
+  data.tar.gz: b7b1940afc61cc57b3145f0305086e72f53061b7
 SHA512:
-  metadata.gz: fee3e76ee13f5c64e8b8f278e8c42ac0ebb979603bc3b1e19b4e76980ba8128c9c1fd594c31d04006f61149afbf86b364cd71d0f59a2206aa7140d3350f13096
-  data.tar.gz: 280542a0d35dc79eb7343f3efd350e8ea8629a47377cb9b04ae58076b9e3da45f983ffa5ce522518515bbef974746a097b16dfd8b87db09f8b93bbb1928b98b5
+  metadata.gz: 258902dec4177b88a4299b89111e01bb7187d629fb590536451854ef7d6293ed757260a43a0772ba67e2a0b2330b44cb26adbc5f0f28d41fd20e618385924e71
+  data.tar.gz: 0c464da3df237b751c43dd9c26d4e1d9ebf5687a9b1d0d9877c94f91cfd58f6162f083e4681c2a8d7d4d361c8b29b23343baeb8133f81164947d1f26a784598f

data/README.md

@@ -12,9 +12,7 @@ Possible applications where we might want to find out whether two items are conn
 
 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.
+This a Ruby implementation of a modified version 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
 
@@ -32,15 +30,32 @@ Or install it yourself as:
 
 ## Usage
 
-Create a new instance of `UnionFind` and pass in an array of items:
+Create a new instance of `UnionFind` and pass in a `Set` of items:
 
 ```ruby
-union_find = UnionFind::UnionFind.new(['Grandfather', 'Father', 'Daughter', 'Single Person'])
+require 'set'
+people = Set.new ['Grandfather', 'Father', 'Daughter', 'Single Person']
+union_find = UnionFind::UnionFind.new(people)
+```
+
+A `Set` is used instead of an `Array` because `Sets` filter out duplicate entries without having to call an expensive `#uniq!` method. If your data comes in form of an `Array`, you can convert it to a `Set` like so:
+
+```ruby
+require 'set'
+array = ['Grandfather', 'Father', 'Daughter', 'Single Person']
+set = array.to_set
+```
+
+Add more items on the fly:
+
+```ruby
+union_find.add('Grandmother')
 ```
 
 Connect items (in any order):
 
 ```ruby
+union_find.union('Grandfather', 'Grandmother')
 union_find.union('Grandfather', 'Father')
 union_find.union('Father', 'Daughter')
 ```
@@ -56,13 +71,21 @@ 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:
+Check how many isolated items there are. In this example, there are 2, namely the family (Grandfather - Grandmother - Father - Daugther) and the Single Person:
 
 ```ruby
 union_find.count_isolated_components
 => 2
 ```
 
+## Performance
+
+Initializing a data structure takes constant time: θ(1).
+
+Afterwards, the `union()` and `connected?()` operations take logarithmic time in the worst case: O(log n).
+
+The `count_isolated_components()` operation takes constant time: θ(1).
+
 ## Contributing
 
 1. Fork it ( https://github.com/[my-github-username]/union_find/fork )

data/lib/union_find.rb

@@ -12,7 +12,7 @@ module UnionFind
 # 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.
+# Initializing a data structure takes linear time.
 # Afterwards, the union, find, and connected 
 # operations take logarithmic time (in the worst case) and the
 # count operation takes constant time.
@@ -24,23 +24,36 @@ module UnionFind
 # @see http://algs4.cs.princeton.edu/15uf/
 class UnionFind
 
+  attr_accessor :components
+
   # 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   
+    # Unexpected behaviour,
+    # for Sets the @components does not copy the content of components
+    # rather it points to the components variable and any changes to the components
+    # variables are reflected in @components.
+    # Force copy instead.
+    @components = components.dup
+
+    raise ArgumentError, 'input is not a Set' unless @components.is_a? Set   
+
+    @number_of_isolated_components = @components.length
 
-    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
+    @parent = {} # parent of component
+    @tree_size = {} # size of tree rooted at component (cannot be more than 31)
+  end
+
+  # Dynamically adds component.
+  # @return [Component] component
+  def add(component)
+    if @components.add?(component)
+      # if component does not already exist
+      @number_of_isolated_components += 1
     end
   end
 
@@ -50,32 +63,18 @@ class UnionFind
     @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
+  # @param component_1 [Component] component
+  # @param component_2 [Component] 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)
 
+    # exit if already connected
     return nil if root_component_1 == root_component_2
 
     # make smaller root point to larger one
@@ -95,12 +94,42 @@ class UnionFind
   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     
+  # @param component_1 [Component] component
+  # @param component_2 [Component] component  
   # @return [Boolean]
   def connected?(component_1, component_2)
     find_root(component_1) == find_root(component_2)
   end
+
+  private
+
+  # Returns the root of a component.
+  # @param component [Component] component
+  # @return [Component] the root of the component
+  # @raise [IndexError] unless component exists
+  def find_root(component)
+    raise IndexError, 'component does not exist' unless @components.include? component
+    
+    set_parent_and_tree_size(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
+
+  # Sets parent and tree size for each component.
+  # To prevent initialize method from taking linear time,
+  # this method is used to do this assignment on demand.
+  # @param component [Component] component
+  # @return [Component] component
+  def set_parent_and_tree_size(component)    
+    @parent[component] ||= component
+    @tree_size[component] ||= 1
+    component
+  end  
 end
 
 end

data/lib/union_find/version.rb

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

data/spec/spec_helper.rb

@@ -1,5 +1,4 @@
 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
@@ -9,7 +8,7 @@ RSpec.configure do |config|
   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.filter_run :focus
   config.run_all_when_everything_filtered = true  
 end
 

data/spec/union_find_spec.rb

@@ -1,9 +1,8 @@
 require 'spec_helper'
-random = Random.new
 
 describe UnionFind::UnionFind do
   # 1 family and 1 single person
-  people = ['Grandfather', 'Father', 'Mother', 'Son', 'Daughter', 'Single']
+  people = Set.new ['Grandfather', 'Father', 'Mother', 'Son', 'Daughter', 'Single']
 
   describe '#initialize' do    
     context 'when no components are provided' do
@@ -19,31 +18,17 @@ describe UnionFind::UnionFind do
     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        
+  describe '#add' do
+    union_find = UnionFind::UnionFind.new(people)          
+    
+    context 'when component does not yet exist' do      
+      it 'adds component' do
+        union_find.add('Other Single')        
+        expect(union_find.connected?('Grandfather', 'Other Single')).to be_falsey
+        expect(union_find.count_isolated_components).to eq people.length + 1
       end
-    end
-  end  
+    end    
+  end   
 
   describe '#union' do
     context 'when one component gets connected to itself' do
@@ -68,9 +53,7 @@ describe UnionFind::UnionFind do
       
       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'                
+        expect(union_find.connected?('Father', 'Single')).to be_truthy                
       end
     end         
   end
@@ -115,5 +98,14 @@ describe UnionFind::UnionFind do
         expect(union_find.count_isolated_components).to eq 2        
       end
     end
+
+    context 'when same connections have been made multiple times' do
+      union_find = UnionFind::UnionFind.new(people)
+      2.times { 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

@@ -21,5 +21,4 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.6"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec"
-  spec.add_development_dependency "pry"  
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: union_find
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Michael Imstepf
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-29 00:00:00.000000000 Z
+date: 2014-07-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,20 +52,6 @@ dependencies:
     - - ">="
       - !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.