sarah 0.0.1

data/lib/sarah.rb

@@ -0,0 +1,388 @@
+# Sarah - Combination sequential array/random-access hash
+#
+# Sequential values beginning at key (index) 0 are stored in an array.
+# Values with sparse or non-numeric keys are stored in a hash. Values
+# may migrate between the two if holes in the sequential key sequence
+# are created or removed.
+#
+# @author Brian Katzung <briank@kappacs.com>, Kappa Computer Solutions, LLC
+# @copyright 2013 Brian Katzung and Kappa Computer Solutions, LLC
+# @license MIT License
+
+class Sarah
+
+    # @!attribute default
+    # The default value returned for non-existent keys.
+    attr_accessor :default
+
+    # @!attribute default_proc
+    # @return [Proc]
+    # The default proc to call for non-existent keys. This takes precedence
+    # over the default value. It is passed the Sarah and the referenced key
+    # (or nil) as parameters.
+    attr_accessor :default_proc
+
+    # Initialize a new instance.
+    #
+    # If passed a block, the block is called to provide default values
+    # instead of using the :default option value. The block is passed the
+    # hash and the requested key (or nil for a shift or pop on an empty
+    # sequential array).
+    #
+    # @param opts [Array] Setup options.
+    # @option opts :default The default value to return for a non-existent key.
+    # @option opts :default_proc The default proc to call for a non-existent
+    #   key.
+    # @option opts :array An array (or hash!) to use for initialization (first).
+    # @option opts :hash A hash (or array!) to use for initialization (second).
+    # @option opts :from An array or hash to use for initialization (third).
+    def initialize (opts = {}, &block)
+	clear
+	@default = opts[:default]
+	@default_proc = block || opts[:default_proc]
+	merge! opts[:array], opts[:hash], opts[:from]
+    end
+
+    # Clear all sequential array and random-access hash values.
+    #
+    # @return [Sarah]
+    def clear
+	@seq = []
+	@rnd = {}
+	self
+    end
+
+    # Test key existence.
+    #
+    # @param key The key to check for existence.
+    # @return [Boolean]
+    def has_key? (key)
+	@rnd.has_key?(key) or (key.is_a? Integer and
+	  key >= -@seq.size and key < @seq.size)
+    end
+
+    # Get a value by sequential or random-access key. If the key does not
+    # exist, the default value or initial block value is returned. If
+    # called with a range or an additional length parameter, a slice is
+    # returned instead.
+    #
+    # @param key The key for the value to be returned, or a range.
+    # @param len [Integer] An optional slice length.
+    # @return [Object, Array]
+    def [] (key, len = nil)
+	if len
+	    slice(key, len)
+	elsif key.is_a? Range
+	    slice(key)
+	elsif @rnd.has_key? key
+	    @rnd[key]
+	elsif key.is_a? Integer and key >= -@seq.size and key < @seq.size
+	    @seq[key]
+	else
+	    @default_proc ? @default_proc.call(self, key) : @default
+	end
+    end
+
+    # Get a value by sequential or random-access key. If the key does not
+    # exist, the local default or block value is returned. If no local or
+    # block value is supplied, a KeyError exception is raised instead.
+    #
+    # If a local block is supplied, it is passed the key as a parameter.
+    #
+    # @param key The key for the value to be returned.
+    # @param default The value to return if the key does not exist.
+    def fetch (key, *default)
+	if @rnd.has_key? key
+	    @rnd[key]
+	elsif key.is_a? Integer and key >= -@seq.size and key < @seq.size
+	    @seq[key]
+	elsif default.size > 0
+	    default[0]
+	elsif block_given?
+	    yield key
+	else
+	    raise KeyError.new("key not found: #{key}")
+	end
+    end
+
+    # Shift and return the first sequential array value.
+    #
+    # @return Object
+    def shift
+	if @seq.size > 0
+	    @seq.shift
+	elsif @default_proc
+	    @default_proc.call self, nil
+	else
+	    @default
+	end
+    end
+
+    # Pop and return the last sequential array value
+    def pop
+	if @seq.size > 0
+	    @seq.pop
+	elsif @default_proc
+	    @default_proc.call self, nil
+	else
+	    @default
+	end
+    end
+
+    # Iterate a block (required) over each key and value.
+    #
+    # @return [Sarah]
+    def each
+	@seq.each_index { |i| yield(i, @seq[i]) }
+	@rnd.each { |kv| yield(*kv) }
+	self
+    end
+
+    alias_method :each_pair, :each
+
+    # Iterate a block (required) over each key.
+    #
+    # @return [Sarah]
+    def each_index
+	@seq.each_index { |i| yield(i) }
+	@rnd.keys.each { |k| yield(k) }
+	self
+    end
+
+    # Set a value by sequential or random-access key.
+    #
+    # @param key The key for which the value should be set.
+    # @param value The value to set for the key.
+    # @return Returns the value.
+    def []= (key, value)
+	if key.is_a? Integer and key.abs <= @seq.size
+	    key += @seq.size if key < 0
+	    @seq[key] = value
+	    @rnd.delete key
+	else
+	    @rnd[key] = value
+	end
+
+	# Move adjacent random-access keys to the sequential array
+	key = @seq.size
+	while @rnd.has_key? key
+	    @seq[key] = @rnd.delete key
+	    key += 1
+	end
+
+	value
+    end
+
+    # Set values and/or key/value pairs.
+    #
+    # <tt>set([val1, ..., valN,] [key1 => kval1, ..., keyN => kvalN])</tt>
+    #
+    # @param list [Array] A list of sequential values or random-access 
+    #   key/value pairs to set.
+    # @return [Sarah]
+    def set (*list)
+	hash = (list.size > 0 and list[-1].is_a? Hash) ? list.pop : nil
+	merge! list
+	merge! hash if hash
+	self
+    end
+
+    # Set key/value pairs.
+    #
+    # <tt>set_kv(key1, val1, ..., keyN, valN)</tt>
+    #
+    # @param kvlist [Array] The list of key/value pairs to set.
+    # @return [Sarah]
+    def set_pairs (*kvlist)
+	kvlist.each_slice(2) { |kv| self.[]=(*kv) }
+	self
+    end
+
+    alias_method :set_kv, :set_pairs
+
+    # Append arrays/Sarahs (or merge hashes) of values.
+    #
+    # @param ahlist [Array<Array, Hash, Sarah>] The structures to append.
+    # @return [Sarah]
+    def append! (*ahlist)
+	ahlist.each do |ah|
+	    if ah.respond_to? :seq_values and ah.respond_to? :rnd
+		push *ah.seq_values
+		merge! ah.rnd
+	    elsif ah.respond_to? :each_pair
+		merge! ah
+	    elsif ah.respond_to? :each_index
+		push *ah
+	    end
+	end
+	self
+    end
+
+    # Insert arrays/Sarahs (or merge hashes) of values.
+    #
+    # @param ahlist [Array<Array, Hash, Sarah>] The structures to insert.
+    # @return [Sarah]
+    def insert! (*ahlist)
+	ahlist.reverse_each do |ah|
+	    if ah.respond_to? :seq_values and ah.respond_to? :rnd
+		unshift @ah.seq_values
+		merge! ah.rnd
+	    elsif ah.respond_to? :each_pair
+		merge! ah
+	    elsif ah.respond_to? :each_index
+		unshift *ah
+	    end
+	end
+	self
+    end
+
+    # Load/merge from a hash and/or array/Sarah (beginning at key 0).
+    #
+    # @param ahlist [Array<Array, Hash, Sarah>] The structures to load/merge.
+    # @return [Sarah]
+    def merge! (*ahlist)
+	ahlist.each do |ah|
+	    if ah.respond_to? :each_pair
+		ah.each_pair { |kv| self.[]=(*kv) }
+	    elsif ah.respond_to? :each_index
+		ah.each_index { |i| self[i] = ah[i] }
+	    end
+	end
+	self
+    end
+
+    alias_method :update, :merge!
+
+    # Unshift (insert) sequential values beginning at key 0.
+    #
+    # @param vlist [Array] A list of values to unshift (insert).
+    # @return [Sarah]
+    def unshift (*vlist)
+	(@seq.size...@seq.size+vlist.size).each { |k| @rnd.delete k }
+	@seq.unshift *vlist
+	self
+    end
+
+    # Push (append) sequential values.
+    #
+    # @param vlist [Array] A list of values to push (append).
+    # @return [Sarah]
+    def push (*vlist)
+	(@seq.size...@seq.size+vlist.size).each { |k| @rnd.delete k }
+	@seq.push *vlist
+	self
+    end
+
+    # Delete by sequential or random-access key, returning any existing value
+    # (or the default or block value, otherwise).
+    #
+    # @param key The key to be deleted.
+    # @return The value of the deleted key.
+    def delete_key (key)
+	return @rnd.delete key if @rnd.has_key? key
+	if key.is_a? Integer
+	    key += @seq.size if key < 0
+	    if key >= 0 and key < @seq.size
+		result = @seq[key]
+
+		# Move any following keys to the random-access hash
+		(key+1...@seq.size).each { |i| @rnd[i] = @seq[i] }
+
+		# Truncate the sequential array
+		@seq = @seq[0...key]
+
+		return result
+	    end
+	end
+	@default_proc ? @default_proc.call(self, nil) : @default
+    end
+
+    # Return the sequential array size.
+    #
+    # @return [Integer]
+    def seq_size; @seq.size; end
+
+    # Return the random-access hash size.
+    #
+    # @return [Integer]
+    def rnd_size; @rnd.size; end
+
+    # Return the total size.
+    #
+    # @return [Integer]
+    def size; @seq.size + @rnd.size; end
+
+    alias_method :seq_length, :seq_size
+    alias_method :rnd_length, :rnd_size
+    alias_method :length, :size
+
+    # Return the sequential-access array.
+    #
+    # @return [Array]
+    def seq; @seq; end
+
+    # Return the random-access hash.
+    #
+    # @return [Hash]
+    def rnd; @rnd; end
+
+    # Return the sequential array keys (indexes).
+    #
+    # @return [Array<Integer>]
+    def seq_keys; 0...@seq.size; end
+
+    # Return the random-access hash keys.
+    #
+    # @return [Array]
+    def rnd_keys; @rnd.keys; end
+
+    # Return all the keys.
+    #
+    # @return [Array]
+    def keys; seq_keys.to_a + rnd_keys; end
+
+    # Return the hash values.
+    def rnd_values; @rnd.values; end
+
+    # Return all the values.
+    def values; @seq + @rnd.values; end
+
+    alias_method :seq_values, :seq
+
+    # Slice all.
+    #
+    # @return [Sarah, Object]
+    def slice (*params)
+	res = @seq.slice *params
+	(res.is_a? Array) ? (self.class.new :array => res, :hash => @rnd,
+	  :default_proc => @default_proc, :default => @default) : res
+    end
+
+    # Slice all in place.
+    #
+    # @return [Sarah, Object]
+    def slice! (*params)
+	res = @seq.slice! *params
+	(res.is_a? Array) ? (self.class.new :array => res, :hash => @rnd,
+	  :default_proc => @default_proc, :default => @default) : res
+    end
+
+    # Slice sequential.
+    #
+    # @return [Sarah, Object]
+    def seq_slice (*params)
+	res = @seq.slice *params
+	(res.is_a? Array) ? (self.class.new :array => res,
+	  :default_proc => @default_proc, :default => @default) : res
+    end
+
+    # Slice sequential in place.
+    #
+    # @return [Sarah, Object]
+    def seq_slice! (*params)
+	res = @seq.slice! *params
+	(res.is_a? Array) ? (self.class.new :array => res,
+	  :default_proc => @default_proc, :default => @default) : res
+    end
+
+end

data/sarah.gemspec

@@ -0,0 +1,15 @@
+Gem::Specification.new do |s|
+  s.name         = "sarah"
+  s.version      = "0.0.1"
+  s.date         = "2013-07-08"
+  s.authors      = ["Brian Katzung"]
+  s.email        = ["briank@kappacs.com"]
+  s.homepage     = "http://rubygems.org/gems/sarah"
+  s.summary      = "Sequential array/random-access hash"
+  s.description  = "Implements a hybrid data structure composed of a sequential array and random-access hash"
+  s.license      = "MIT"
+ 
+  s.files        = Dir.glob("lib/**/*") + %w{sarah.gemspec}
+  s.test_files   = Dir.glob("test/**/*")
+  s.require_path = 'lib'
+end

data/test/00class.rb

@@ -0,0 +1,16 @@
+require 'minitest/autorun'
+require 'sarah'
+
+class TestSarah < MiniTest::Unit::TestCase
+
+    def test_cmethod_new
+	assert_respond_to Sarah, :new
+    end
+
+    def test_new_1
+	assert Sarah.new, "Failed to create new Sarah"
+    end
+
+end
+
+# END

data/test/01instance.rb

@@ -0,0 +1,31 @@
+require 'minitest/autorun'
+require 'sarah'
+
+class TestSarah < MiniTest::Unit::TestCase
+
+    def setup
+	@s = Sarah.new
+    end
+
+    def test_imethods_accessors
+	[
+	  :default, :default=, :default_proc, :default_proc=
+	].each { |method| assert_respond_to @s, method }
+    end
+
+    def test_imethods_user_api
+	[
+	  :clear, :has_key?, :[], :[]=, :fetch,
+	  :shift, :pop, :each, :each_pair, :each_index,
+	  :set, :set_pairs, :set_kv, :append!, :merge!,
+	  :unshift, :push, :delete_key,
+	  :size, :seq_size, :rnd_size, :length, :seq_length, :rnd_length,
+	  :seq, :rnd, :keys, :seq_keys, :rnd_keys,
+	  :values, :seq_values, :rnd_values,
+	  :slice, :slice!, :seq_slice, :seq_slice!
+	].each { |method| assert_respond_to @s, method }
+    end
+
+end
+
+# END

data/test/02new.rb

@@ -0,0 +1,39 @@
+require 'minitest/autorun'
+require 'sarah'
+
+class TestSarah < MiniTest::Unit::TestCase
+
+    def test_new_array
+	s = Sarah.new(:array => [1, 2])
+	assert_equal([1, 2], s.seq, "new array seq [...]")
+	assert_equal({}, s.rnd, "new array rnd {}")
+	assert_equal(2, s.seq_size, "new array seq_size")
+	assert_equal(0, s.rnd_size, "new array rnd_size")
+    end
+
+    def test_new_hash
+	s = Sarah.new(:hash => { :one => 1, :two => 2 })
+	assert_equal([], s.seq, "new hash seq []")
+	assert_equal({ :one => 1, :two => 2 }, s.rnd, "new hash rnd {...}")
+	assert_equal(0, s.seq_size, "new hash seq_size")
+	assert_equal(2, s.rnd_size, "new hash rnd_size")
+    end
+
+    def test_new_mixed
+	s = Sarah.new(:array => [1, 2], :hash => { :one => 1, :two => 2 })
+	assert_equal([1, 2], s.seq, "new mixed seq [...]")
+	assert_equal({ :one => 1, :two => 2 }, s.rnd, "new mixed rnd {...}")
+	assert_equal(2, s.seq_size, "new mixed seq_size")
+	assert_equal(2, s.rnd_size, "new mixed rnd_size")
+    end
+
+    def test_new_consecutive
+	s = Sarah.new(:array => [0, 1], :hash => { 2 => :two, 3 => :three })
+	assert_equal([0, 1, :two, :three], s.seq, "new consecutive [...]")
+	assert_equal(4, s.seq_size, "new consecutive seq_size")
+	assert_equal(0, s.rnd_size, "new consecutive rnd_size")
+    end
+
+end
+
+# END

data/test/03set_get.rb

@@ -0,0 +1,59 @@
+require 'minitest/autorun'
+require 'sarah'
+
+class TestSarah < MiniTest::Unit::TestCase
+
+    def setup
+	@s = Sarah.new(:array => [1, 2], :hash => { :a => 3, :b => 4 })
+    end
+
+    def test_clear
+	assert_equal(4, @s.size, "has size 4 before clear")
+	@s.clear
+	assert_equal(0, @s.size, "has size 0 after clear")
+    end
+
+    def test_has_key
+	assert_equal(true, @s.has_key?(0), "has key 0")
+	assert_equal(true, @s.has_key?(-1), "has key -1")
+	assert_equal(true, @s.has_key?(:a), "has key :a")
+	assert_equal(false, @s.has_key?(2), "has no key 2")
+	assert_equal(false, @s.has_key?(:c), "has no key :c")
+    end
+
+    def test_get_set
+	assert_equal(1, @s[0], "get key 0 value 1")
+	assert_equal(2, @s[1], "get key 1 value 2")
+	assert_equal(3, @s[:a], "get key :a value 3")
+	assert_equal(4, @s[:b], "get key :b value 4")
+
+	@s[2] = 5
+	@s[:c] = 6
+	assert_equal(5, @s[2], "set/get key 2 value 5")
+	assert_equal(6, @s[:c], "set/get key :c value 6")
+    end
+
+    def test_default
+	assert_equal(1, @s[0], "confirm key 0 value 1")
+	assert_equal(nil, @s[2], "default default nil")
+
+	s = Sarah.new(:array => [0], :default => false)
+	assert_equal(0, s[0], "confirm key 0 value 0")
+	assert_equal(false, s[1], "explicit default false")
+
+	s = Sarah.new(:array => [0]) { |s, key| key }
+	assert_equal(0, s[0], "confirm key 0 value 0")
+	assert_equal(1, s[1], "block default 1")
+	assert_equal(2, s[2], "block default 2")
+    end
+
+    def test_fetch
+	assert_equal(1, @s.fetch(0), "fetch key 0 value 0")
+	assert_raises(KeyError, "fetch with exception") { @s.fetch 2 }
+	assert_equal(false, @s.fetch(2, false), "fetch with default")
+	assert_equal(2, @s.fetch(2) { |key| key }, "fetch with block")
+    end
+
+end
+
+# END

data/test/04stack.rb

@@ -0,0 +1,34 @@
+require 'minitest/autorun'
+require 'sarah'
+
+class TestSarah < MiniTest::Unit::TestCase
+
+    def test_stack
+	s = Sarah.new
+	s.push 1, 2, 3
+	s.unshift 4, 5, 6
+	assert_equal([4, 5, 6, 1, 2, 3], s.seq, "push + unshift")
+	assert_equal(4, s.shift, "shift")
+	assert_equal(3, s.pop, "pop")
+	assert_equal([5, 6, 1, 2], s.seq, "after shift, pop")
+    end
+
+    def test_append
+	s = Sarah.new
+	s.append! [1], { :one => 1 }, [2], [3]
+	s.append! [4], { :two => 2 }, [5], [6]
+	assert_equal([1, 2, 3, 4, 5, 6], s.seq, "append ary")
+	assert_equal({ :one => 1, :two => 2 }, s.rnd, "append hsh")
+    end
+
+    def test_insert
+	s = Sarah.new
+	s.insert! [1], { :one => 1 }, [2], [3]
+	s.insert! [4], { :two => 2 }, [5], [6]
+	assert_equal([4, 5, 6, 1, 2, 3], s.seq, "insert ary")
+	assert_equal({ :one => 1, :two => 2 }, s.rnd, "insert hsh")
+    end
+
+end
+
+# END

data/test/run_tests.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+
+export RUBYLIB=../lib
+
+# Run the specified tests (or all of them)
+for t in ${*:-[0-9]*.rb}
+do ruby $t
+done

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification 
+name: sarah
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Brian Katzung
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2013-07-08 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: Implements a hybrid data structure composed of a sequential array and random-access hash
+email: 
+- briank@kappacs.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/sarah.rb
+- sarah.gemspec
+- test/02new.rb
+- test/00class.rb
+- test/04stack.rb
+- test/01instance.rb
+- test/run_tests.sh
+- test/03set_get.rb
+has_rdoc: true
+homepage: http://rubygems.org/gems/sarah
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Sequential array/random-access hash
+test_files: 
+- test/02new.rb
+- test/00class.rb
+- test/04stack.rb
+- test/01instance.rb
+- test/run_tests.sh
+- test/03set_get.rb