basic_queue 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2bbb375a040698d29cb448e7733d70b1a849f858
+  data.tar.gz: d82ba51369fd8ca3a93ec5b1bb2c280e85b3bec0
+SHA512:
+  metadata.gz: a3607fa5bea797d761120f4ed61aac6d0f5df4870ff9bf8136573d80341799298ce258484f64ac5bcb0e2c91f60ba0d5e2ed60477786e11c0801b5003ca06ae5
+  data.tar.gz: 7ac1ea3cbc36d07a1a5f3f9a5a24f25131caf1de09ff547a4343fb0e244ca53495b81fe0f8d796ea6d7a9fb2f359e3d13435e20facc06dfe7c8e59d8cd0502bf

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-version
+.ruby-gemset

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in basic_queue.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,70 @@
+# BasicQueue
+
+A basic first-in-first-out (FIFO) queue data structure.
+
+It supports the usual enqueue and dequeue operations, along with methods for peeking at the first item, testing if the queue is empty, clearing the queue and counting the number of items in the queue.
+
+This implementation uses a singly-linked list with a non-static nested class for linked-list nodes. As a result, this data structure is more performant than implementing a queue with an array (see notes below).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'basic_queue'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install basic_queue
+
+## Usage
+
+Create a new instance of `Queue`:
+
+```ruby
+queue = BasicQueue::Queue.new
+```
+
+Add items to the queue:
+```ruby
+queue.enq 'Michael'
+queue << 'Peter' # << is an alias method for enq(), you can use either method
+```
+
+Check which item is next in the queue:
+```ruby
+queue.peek
+=> "Michael"
+```
+
+Remove item from the queue:
+```ruby
+queue.deq
+=> "Michael"
+```
+
+Check number of items left in the queue:
+```ruby
+queue.length # size() is an alias method for length, you can use either method
+=> 1
+```
+
+Clear queue:
+```ruby
+queue.clear
+```
+
+## Performance
+
+All methods take constant time (Θ(1)). Hence, using this data structure is more performant than using an Array since Array#unshift takes linear time (Θ(n)).
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/basic_queue/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/basic_queue.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'basic_queue/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "basic_queue"
+  spec.version       = BasicQueue::VERSION
+  spec.authors       = ["Michael Imstepf"]
+  spec.email         = ["michael.imstepf@gmail.com"]
+  spec.summary       = %q{A first-in-first-out (FIFO) queue data structure.}
+  spec.description   = %q{It supports the usual enqueue and dequeue operations, along with methods for peeking at the first item, testing if the queue is empty and counting the number of items in the queue.}
+  spec.homepage      = "https://github.com/michaelimstepf/basic-queue"
+  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"
+end

data/lib/basic_queue.rb

@@ -0,0 +1,130 @@
+require "basic_queue/version"
+
+module BasicQueue
+
+# A basic first-in-first-out (FIFO) queue data structure.
+
+# It supports the usual enqueue and dequeue operations, 
+# along with methods for peeking at the first item, testing
+# if the queue is empty and counting the number of items in the queue.
+
+# This implementation uses a singly-linked list with a non-static
+# nested class for linked-list nodes.
+
+# All methods take constant time (Θ(1)). Hence, it is more performant than
+# an Array, since Array#unshift takes linear time (Θ(n)).
+
+# @author Robert Sedgewick
+# @author Kevin Wayne
+# @author Michael Imstepf
+# @see http://algs4.cs.princeton.edu/13stacks
+# @see http://algs4.cs.princeton.edu/13stacks/LinkedQueue.java.html
+class Queue
+  # Initializes the queue and sets variables.
+  def initialize
+    @length = 0
+    @first = nil
+    @last = nil
+  end
+
+  # Adds new item to the queue.
+  # @param item [Item] the item to be enqueued
+  # @return [Item] item
+  def enq(item)
+    # save previous old last node for use below
+    old_last = @last
+    
+    # create new last node and update @last_item
+    @last = Node.new(item, nil)    
+
+    if empty? # set to nil
+      @first = @last
+    else # point 2nd last node to last node
+      old_last.next_node = @last
+    end
+    
+    @length += 1
+
+    item
+  end
+
+  # Adds new item to the queue.
+  # Alias method for #enq().
+  # @param item [Item] the item to be enqueued
+  # @return [Item] item
+  def <<(item)
+    enq(item)
+  end
+
+  # Removes and returns the item on this queue that was least recently added.
+  # @return [Item] dequeued item
+  def deq
+    return nil if empty?
+    
+    # save previous first node for return value
+    old_first = @first
+
+    # update first node
+    @first = @first.next_node
+    @length -= 1
+
+    # avoid loitering
+    @last = nil if empty?
+
+    old_first.item
+  end
+
+  # Returns next item in the queue.
+  # @return [Item] item
+  def peek
+    empty? ? nil : @first.item
+  end
+
+  # Clears queue.
+  # @return [Boolean] true
+  def clear
+    @length = 0
+    @first = nil
+    @last = nil
+    true    
+  end
+
+  # Returns length of queue.
+  # @return [Integer]
+  def length
+    @length
+  end
+
+  # Returns length of queue.
+  # Alias method for #length.
+  def size
+    length
+  end
+
+  # Checks whether the queue is empty or not.
+  # @return [Boolean]
+  def empty?
+    length == 0
+  end
+end
+
+# In arrays and queues based on arrays, the enqueue method
+# (Array#unshift) is often expensive since it needs to iterate through each
+# array member and shift each member to the right, resulting in linear running time.
+# We use a singly linked list instead.
+
+# @author Robert Sedgewick
+# @author Kevin Wayne
+# @author Michael Imstepf
+# @see http://algs4.cs.princeton.edu/13stacks/LinkedQueue.java.html
+class Node
+  attr_reader :item
+  attr_accessor :next_node
+
+  def initialize(item, next_node)
+    @item = item
+    @next_node = next_node
+  end
+end
+
+end

data/lib/basic_queue/version.rb

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

data/spec/basic_queue_spec.rb

@@ -0,0 +1,188 @@
+require 'spec_helper'
+
+describe BasicQueue::Queue do
+  describe '#enq' do
+    queue = BasicQueue::Queue.new
+
+    it 'adds item to queue' do
+      queue.enq 'Michael'
+      expect(queue.length).to eq 1
+      queue.enq 'Peter'
+      expect(queue.length).to eq 2
+    end
+  end
+
+  describe '#<<' do
+    queue = BasicQueue::Queue.new
+
+    it 'adds item to queue' do
+      queue << 'Michael'
+      expect(queue.length).to eq 1
+      queue << 'Peter'
+      expect(queue.length).to eq 2
+    end
+  end
+
+  describe '#deq' do
+    context 'when items exist in queue' do
+      queue = BasicQueue::Queue.new
+      
+      it 'removes item from queue' do
+        queue.enq 'Michael'
+        queue.enq 'Peter'
+        expect(queue.deq).to eq 'Michael'
+        expect(queue.deq).to eq 'Peter'      
+      end
+    end
+
+    context 'when queue has been instantiated without items' do
+      queue = BasicQueue::Queue.new
+
+      it 'returns nil' do
+        expect(queue.deq).to be_nil
+      end
+    end
+
+    context 'when all items have been removed from queue' do
+      queue = BasicQueue::Queue.new
+
+      it 'returns nil' do
+        queue.enq 'Michael'
+        queue.enq 'Peter'
+        expect(queue.deq).to eq 'Michael'
+        expect(queue.deq).to eq 'Peter'        
+        expect(queue.deq).to be_nil
+      end
+    end
+
+    context 'when there is an underflow' do
+      queue = BasicQueue::Queue.new
+
+      it 'returns nil' do
+        queue.enq 'Michael'
+        queue.enq 'Peter'
+        expect(queue.deq).to eq 'Michael'
+        expect(queue.deq).to eq 'Peter'
+        expect(queue.deq).to eq nil
+        expect(queue.deq).to eq nil        
+        expect(queue.length).to eq 0
+      end
+    end    
+  end
+
+  describe '#clear' do
+    context 'when queue is empty' do
+      queue = BasicQueue::Queue.new      
+
+      it 'clears queue' do
+        expect(queue.clear).to be_truthy
+        expect(queue.length).to eq 0
+        queue.enq 'Michael'
+        expect(queue.deq).to eq 'Michael'
+      end
+    end
+
+    context 'when queue is not empty' do
+      queue = BasicQueue::Queue.new            
+
+      it 'clears queue' do
+        queue.enq 'Michael'
+        queue.enq 'Peter'
+        expect(queue.clear).to be_truthy
+        expect(queue.length).to eq 0
+        queue.enq 'Michael'
+        expect(queue.deq).to eq 'Michael'        
+      end
+    end    
+  end
+
+  describe '#length' do
+    context 'when queue has been instantiated without items' do
+      queue = BasicQueue::Queue.new
+
+      it 'returns 0' do
+        expect(queue.length).to eq 0
+      end
+    end
+
+    context 'when queue has 1 item' do
+      queue = BasicQueue::Queue.new
+
+      it 'returns 1' do
+        queue.enq 'Michael'        
+        expect(queue.length).to eq 1
+      end
+    end
+
+    context 'when queue has 2 items' do
+      queue = BasicQueue::Queue.new
+
+      it 'returns 2' do
+        queue.enq 'Michael'
+        queue.enq 'Peter'                
+        expect(queue.length).to eq 2
+      end
+    end
+
+    context 'when queue has been cleared' do
+      queue = BasicQueue::Queue.new
+
+      it 'returns 0' do
+        queue.enq 'Michael'
+        queue.enq 'Peter'                
+        queue.clear
+        expect(queue.length).to eq 0
+      end
+    end                 
+  end
+
+  describe '#size' do
+    context 'when queue has been instantiated without items' do
+      queue = BasicQueue::Queue.new
+
+      it 'returns 0' do
+        expect(queue.size).to eq 0
+      end
+    end
+  end
+
+  describe '#empty?' do
+    context 'when queue is empty' do
+      queue = BasicQueue::Queue.new
+
+      it 'returns true' do
+        expect(queue.empty?).to be_truthy        
+      end      
+    end
+
+    context 'when queue is not empty' do
+      queue = BasicQueue::Queue.new
+
+      it 'returns false' do
+        queue.enq 'Michael'        
+        expect(queue.empty?).to be_falsey        
+      end      
+    end    
+  end
+
+  describe '#peek' do
+    context 'when queue is empty' do
+      queue = BasicQueue::Queue.new
+
+      it 'returns nil' do
+        expect(queue.peek).to be_nil
+      end
+    end      
+
+    context 'when queue is not empty' do
+      queue = BasicQueue::Queue.new
+
+      it 'returns next item in the queue' do
+        queue.enq 'Michael'
+        queue.enq 'Peter'          
+        expect(queue.peek).to eq 'Michael'
+        expect(queue.peek).to eq 'Michael'
+      end
+    end      
+  end             
+end

data/spec/spec_helper.rb

@@ -0,0 +1,13 @@
+require 'basic_queue'
+
+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
+  config.run_all_when_everything_filtered = true  
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: basic_queue
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Michael Imstepf
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-07-04 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'
+description: It supports the usual enqueue and dequeue operations, along with methods
+  for peeking at the first item, testing if the queue is empty and counting the number
+  of items in the queue.
+email:
+- michael.imstepf@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- basic_queue.gemspec
+- lib/basic_queue.rb
+- lib/basic_queue/version.rb
+- spec/basic_queue_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/michaelimstepf/basic-queue
+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: A first-in-first-out (FIFO) queue data structure.
+test_files:
+- spec/basic_queue_spec.rb
+- spec/spec_helper.rb