hashery 1.5.0 → 2.0.0

data/lib/hashery/key_hash.rb

@@ -1,186 +1,61 @@
-require 'hashery/core_ext'
-
-# The KeyHash class is a Hash compatible class which converts
-# all keys to strings. This has two advantages. First it
-# means hash entries have indifferent access. <tt>1</tt>,
-# <tt>"1"</tt> and <tt>:1</tt> are all equivalent. Any object
-# that defines <tt>#to_s</tt> can be used as a key. Secondly,
-# since strings are garbage collected so are KeyHash objects. 
-# 
-# The KeyHash class works like a normal Hash. But notice the
-# significant distinction of indifferent key access.
-# 
-#   s = KeyHash.new
-#   s[:x] = 1
-#   s[:x]       #=> 1
-#   s['x']      #=> 1
-# 
-# We can see that internally the key has indeed been converted
-# to a String.
-# 
-#   s.to_h      #=> {'x'=>1 }
-# 
-# Becuase of the way in which KeyHash is designed, it has a nice
-# secondary usage. KeyHash defines a private method called
-# #convert_key. This method handles the conversion of the key
-# whenever the underlying hash is altered. If you have need
-# for a different kind of Hash, one the has a special restraint
-# on the key, it is easy enough to subclass KeyHash and override
-# the is method. Eg.
-# 
-#   class Upash < KeyHash
-#     def convert_key(key)
-#       key.to_s.upcase
-#     end
-#   end
-# 
-#   u = Upash.new
-#   u.replace(:a=>1, :b=>2)
-#   u.to_h  #=> { 'A'=>1, 'B'=>2 }
-#
-#
-# NOTE: KeyHash does not yet handle default_proc.
-
-class KeyHash < Hash
-
-  #
-  def self.[](*hash)
-    s = new
-    super(*hash).each{ |k,v| s[k] = v }
-    s
-  end
-
-  #
-  def [](key)
-    super(convert_key(key))
-  end
-
-  #
-  def []=(key,value)
-    super(convert_key(key), value)
-  end
-
-  #
-  def <<(other)
-    case other
-    when Hash
-      super(other.rekey{ |key| convert_key(key) })
-    when Array
-      self[other[0]] = other[1]
-    else
-      raise ArgumentError
-    end
-  end
-
-  #
-  def fetch(key)
-    super(convert_key(key))
-  end
-
-  #
-  def store(key, value)
-    super(convert_key(key), value)
-  end
-
-  #
-  def key?(key)
-    super(convert_key(key))
-  end
-
-  #
-  def has_key?(key)
-    super(convert_key(key))
-  end
-
-  #
-  def include?(key)
-    super(convert_key(key))
-  end
-
-  #
-  def member?(key)
-    super(convert_key(key))
-  end
-
-  # Synonym for #rekey, but modifies the receiver in place (and returns it).
-  #
-  #   foo = { :name=>'Gavin', :wife=>:Lisa }.to_stash
-  #   foo.rekey!{ |k| k.upcase }  #=>  { "NAME"=>"Gavin", "WIFE"=>:Lisa }
-  #   foo.inspect                 #=>  { "NAME"=>"Gavin", "WIFE"=>:Lisa }
-  #
-  def rekey!(*args, &block)
-    # for backward comptability (TODO: DEPRECATE?).
-    block = args.pop.to_sym.to_proc if args.size == 1
-    if args.empty?
-      block = lambda{|k| k} unless block
-      keys.each do |k|
-        nk = block[k]
-        self[nk.to_s]=delete(k) #if nk
-      end
-    else
-      raise ArgumentError, "3 for 2" if block
-      to, from = *args
-      self[to] = delete(from) if has_key?(from)
+require 'hashery/crud_hash'
+
+module Hashery
+
+  # The KeyHash class is a Hash class which accepts a block for
+  # normalizing keys.
+  #
+  # The KeyHash class is essentially the same as a normal Hash.
+  # But notice the significant distinction of indifferent key
+  # access.
+  # 
+  #   s = KeyHash.new
+  #   s[:x] = 1
+  #   s[:x]       #=> 1
+  #   s['x']      #=> 1
+  # 
+  # We can see that internally the key has indeed been converted
+  # to a String.
+  # 
+  #   s.to_h      #=> {'x'=>1 }
+  # 
+  # By default all keys are converted to strings. This has two advantages
+  # over a regular Hash is many usecases. First it means hash entries have
+  # indifferent access. <tt>1</tt>, <tt>"1"</tt> and <tt>:1</tt> are all
+  # equivalent --any object that defines <tt>#to_s</tt> can be used as a key.
+  # Secondly, since strings are garbage collected so will default KeyHash
+  # objects. 
+  # 
+  # But keys can be normalized by any function. Theses functions can be quite
+  # unique.
+  #
+  #   h = KeyHash.new(0){ |k| k.to_i }
+  #   h[1.34] += 1
+  #   h[1.20] += 1
+  #   h[1.00] += 1
+  #   h  #=> { 1 => 3 }
+  #
+  class KeyHash < CRUDHash
+
+    #
+    # Unlike a regular Hash, a KeyHash's block sets the `key_proc` rather
+    # than the `default_proc`.
+    #
+    def initialize(*default, &block)
+      super(*default)
+      @key_proc = block || Proc.new{ |k| k.to_s }
     end
-    self
-  end
-
-  #
-  def rekey(*args, &block)
-    dup.rekey!(*args, &block)
-  end
-
-  #
-  def delete(key)
-    super(convert_key(key))
-  end
-
-  #
-  def update(other)
-    super(other.rekey{ |key| convert_key(key) })
-  end
-
-  # Same as #update.
-  def merge!(other)
-    super(other.rekey{ |key| convert_key(key) })
-  end
 
-  #
-  def merge(other)
-    super(other.rekey{ |key| convert_key(key) })
-  end
-
-  #
-  def replace(other)
-    super(other.rekey{ |key| convert_key(key) })
-  end
-
-  #
-  def values_at(*keys)
-    super(*keys.map{ |key| convert_key(key) })
-  end
-
-  #
-  def to_hash
-    h = {}
-    each{ |k,v| h[k] = v }
-    h
   end
 
-  alias_method :to_h, :to_hash
-
-  private
-
-    def convert_key(key)
-      key.to_s
-    end
-
 end
 
-class Hash
-  # Convert a Hash to a KeyHash object.
-  def to_keyhash
-    KeyHash[self]
-  end
-end
+#class Hash
+#  #
+#  # Convert a Hash to a KeyHash object.
+#  #
+#  def to_keyhash
+#    Hashery::KeyHash[self]
+#  end
+#end
 

data/lib/hashery/linked_list.rb

@@ -1,195 +1,249 @@
-# LinkedList
-#
-# Copyright (C) 2006 Kirk Haines <khaines@enigo.com>.
-#
-# General Public License (GPL)
-#
-# 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.
-
 require 'enumerator'
 
-# LinkedList implements a simple doubly linked list with efficient
-# hash-like element access.
-#
-# This is a simple linked list implementation with efficient random
-# access of data elements.  It was inspired by George Moscovitis'
-# LRUCache implementation found in Facets 1.7.30, but unlike the
-# linked list in that cache, this one does not require the use of a
-# mixin on any class to be stored.  The linked list provides the
-# push, pop, shift, unshift, first, last, delete and length methods
-# which work just like their namesakes in the Array class, but it
-# also supports setting and retrieving values by key, just like a
-# hash.
-#
-# LinkedList was ported from the original in Kirk Hanes IOWA web framework.
-#
-class LinkedList
-
-        include Enumerable
-
-        # Represents a single node of the linked list.
-
-        class Node
-                attr_accessor :key, :value, :prev_node, :next_node
-
-                def initialize(key=nil,value=nil,prev_node=nil,next_node=nil)
-                        @key = key
-                        @value = value
-                        @prev_node = prev_node
-                        @next_node = next_node
-                end
-        end
-
-        def initialize
-                @head = Node.new
-                @tail = Node.new
-                @lookup = Hash.new
-                node_join(@head,@tail)
-        end
-
-        def [](v)
-                @lookup[v].value
-        end
-
-        def []=(k,v)
-                if @lookup.has_key?(k)
-                        @lookup[k].value = v
-                else
-                        n = Node.new(k,v,@head,@head.next_node)
-                        node_join(n,@head.next_node)
-                        node_join(@head,n)
-                        @lookup[k] = n
-                end
-                v
-        end
-
-        def empty?
-                @lookup.empty?
-        end
-
-        def delete(k)
-                n = @lookup.delete(k)
-                v = n ? node_purge(n) : nil
-                v
-        end
-
-        def first
-                @head.next_node.value
-        end
-
-        def last
-                @tail.prev_node.value
-        end
-
-        def shift
-                k = @head.next_node.key
-                n = @lookup.delete(k)
-                node_delete(n) if n
-        end
-
-        def unshift(v)
-                if @lookup.has_key?(v)
-                        n = @lookup[v]
-                        node_delete(n)
-                        node_join(n,@head.next_node)
-                        node_join(@head,n)
-                else
-                        n = Node.new(v,v,@head,@head.next_node)
-                        node_join(n,@head.next_node)
-                        node_join(@head,n)
-                        @lookup[v] = n
-                end
-                v
-        end
-
-        def pop
-                k = @tail.prev_node.key
-                n = @lookup.delete(k)
-                node_delete(n) if n
-        end
-
-        def push(v)
-                if @lookup.has_key?(v)
-                        n = @lookup[v]
-                        node_delete(n)
-                        node_join(@tail.prev_node,n)
-                        node_join(n,@tail)
-                else
-                        n = Node.new(v,v,@tail.prev_node,@tail)
-                        node_join(@tail.prev_node,n)
-                        node_join(n,@tail)
-                        @lookup[v] = n
-                end
-                v
-        end
-
-        def queue
-                r = []
-                n = @head
-                while (n = n.next_node) and n != @tail
-                        r << n.key
-                end
-                r
-        end
-
-        def to_a
-                r = []
-                n = @head
-                while (n = n.next_node) and n != @tail
-                        r << n.value
-                end
-                r
-        end
-
-        def length
-                @lookup.length
-        end
-
-        def each
-                n = @head
-                while (n = n.next_node) and n != @tail
-                        yield(n.key,n.value)
-                end
-        end
-
-        private
-
-        def node_delete(n)
-                node_join(n.prev_node,n.next_node)
-                v = n.value
-        end
-
-        def node_purge(n)
-                node_join(n.prev_node,n.next_node)
-                v = n.value
-                n.value = nil
-                n.key = nil
-                n.next_node = nil
-                n.prev_node = nil
-                v
-        end
-
-        def node_join(a,b)
-                a.next_node = b
-                b.prev_node = a
-        end
+module Hashery
+
+  # LinkedList implements a simple doubly linked list with efficient
+  # hash-like element access.
+  #
+  # This is a simple linked-list implementation with efficient random
+  # access of data elements.  It was inspired by George Moscovitis'
+  # LRUCache implementation found in Facets 1.7.30, but unlike the
+  # linked-list in that cache, this one does not require the use of a
+  # mixin on any class to be stored.  The linked-list provides the
+  # push, pop, shift, unshift, first, last, delete and length methods
+  # which work just like their namesakes in the Array class, but it
+  # also supports setting and retrieving values by key, just like a
+  # hash.
+  #
+  # LinkedList was ported from the original in Kirk Hanes IOWA web framework.
+  #
+  # == Acknowledgements
+  #
+  # LinkedList is based on the LinkedList library by Kirk Haines.
+  #
+  # Copyright (C) 2006 Kirk Haines <khaines@enigo.com>.
+  #
+  class LinkedList
+
+    include Enumerable
+
+    # Represents a single node of the linked list.
+    #
+    class Node
+      attr_accessor :key, :value, :prev_node, :next_node
+
+      def initialize(key=nil,value=nil,prev_node=nil,next_node=nil)
+        @key = key
+        @value = value
+        @prev_node = prev_node
+        @next_node = next_node
+      end
+    end
+
+    #
+    # Initialize new LinkedList instance.
+    #
+    def initialize
+      @head   = Node.new
+      @tail   = Node.new
+      @lookup = Hash.new
+
+      node_join(@head,@tail)
+    end
+
+    #
+    # Lookup entry by key.
+    #
+    def [](key)
+      @lookup[key].value
+    end
+
+    #
+    # Add node to linked list.
+    #
+    def []=(k,v)
+      if @lookup.has_key?(k)
+        @lookup[k].value = v
+      else
+        n = Node.new(k,v,@head,@head.next_node)
+        node_join(n,@head.next_node)
+        node_join(@head,n)
+        @lookup[k] = n
+      end
+      v
+    end
+
+    #
+    # Is linked list empty?
+    #
+    def empty?
+      @lookup.empty?
+    end
+
+    #
+    # Remove node idenified by key.
+    #
+    def delete(key)
+      n = @lookup.delete(key)
+      v = n ? node_purge(n) : nil
+      v
+    end
+
+    #
+    # Get value of first node.
+    #
+    def first
+      @head.next_node.value
+    end
+
+    #
+    # Get value of last node.
+    #
+    def last
+      @tail.prev_node.value
+    end
+
+    #
+    #
+    #
+    def shift
+      k = @head.next_node.key
+      n = @lookup.delete(k)
+      node_delete(n) if n
+    end
+
+    #
+    #
+    #
+    def unshift(v)
+      if @lookup.has_key?(v)
+        n = @lookup[v]
+        node_delete(n)
+        node_join(n,@head.next_node)
+        node_join(@head,n)
+      else
+        n = Node.new(v,v,@head,@head.next_node)
+        node_join(n,@head.next_node)
+        node_join(@head,n)
+        @lookup[v] = n
+      end
+      v
+    end
+
+    #
+    #
+    #
+    def pop
+      k = @tail.prev_node.key
+      n = @lookup.delete(k)
+      node_delete(n) if n
+    end
+
+    #
+    #
+    #
+    def push(v)
+      if @lookup.has_key?(v)
+        n = @lookup[v]
+        node_delete(n)
+        node_join(@tail.prev_node,n)
+        node_join(n,@tail)
+      else
+        n = Node.new(v,v,@tail.prev_node,@tail)
+        node_join(@tail.prev_node,n)
+        node_join(n,@tail)
+        @lookup[v] = n
+      end
+      v
+    end
+
+    alias :<< :push
+
+    #
+    # Produces an Array of key values.
+    #
+    # Returns [Array].
+    #
+    def queue
+      r = []
+      n = @head
+      while (n = n.next_node) and n != @tail
+        r << n.key
+      end
+      r
+    end
+
+    #
+    # Converts to an Array of node values.
+    #
+    # Returns [Array].
+    #
+    def to_a
+      r = []
+      n = @head
+      while (n = n.next_node) and n != @tail
+        r << n.value
+      end
+      r
+    end
+
+    #
+    # Number of nodes.
+    #
+    def length
+      @lookup.length
+    end
+
+    alias size length
+
+    #
+    # Iterate over nodes, starting with the head node
+    # and ending with the tail node.
+    #
+    def each
+      n = @head
+      while (n = n.next_node) and n != @tail
+        yield(n.key,n.value)
+      end
+    end
+
+  private
+
+    #
+    # Delete a node.
+    #
+    # n - A node.
+    #
+    def node_delete(n)
+      node_join(n.prev_node,n.next_node)
+      v = n.value
+    end
+
+    #
+    # Purge a node.
+    #
+    # n - A node.
+    #
+    def node_purge(n)
+      node_join(n.prev_node,n.next_node)
+      v = n.value
+      n.value = nil
+      n.key = nil
+      n.next_node = nil
+      n.prev_node = nil
+      v
+    end
+
+    # Join two nodes.
+    #
+    # a - A node.
+    # b - A node.
+    #
+    def node_join(a,b)
+      a.next_node = b
+      b.prev_node = a
+    end
+
+  end
 
 end
-