facets 0.6.3

data/lib/facet/hash/inverse.rb

@@ -0,0 +1,29 @@
+#--
+# Credit goes to Tilo Sloboda.
+#++
+class Hash
+  # Create a "true" inverse hash by storing mutliple values
+  # in Arrays.
+  #
+  #   require 'facet/hash/inverse'
+  #
+  #   h = {"a"=>3, "b"=>3, "c"=>3, "d"=>2, "e"=>9, "f"=>3, "g"=>9}
+  #
+  #   h.invert                #=> {2=>"d", 3=>"f", 9=>"g"}
+  #   h.inverse               #=> {2=>"d", 3=>["f", "c", "b", "a"], 9=>["g", "e"]}
+  #   h.inverse.inverse       #=> {"a"=>3, "b"=>3, "c"=>3, "d"=>2, "e"=>9, "f"=>3, "g"=>9}
+  #   h.inverse.inverse == h  #=> true
+  #
+  def inverse
+    i = Hash.new
+    self.each_pair{ |k,v|
+      if (Array === v)
+        v.each{ |x| i[x] = ( i.has_key?(x) ? [k,i[x]].flatten : k ) }
+      else
+        i[v] = ( i.has_key?(v) ? [k,i[v]].flatten : k )
+      end
+    }
+    return i
+  end
+    
+end

data/lib/facet/hash/keys_to_s.rb

@@ -0,0 +1,50 @@
+#--
+# Adapted from Gavin Sinclair's #convert_keys.
+#++
+class Hash
+  
+  # Converts all keys in the Hash to be String values, returning a new Hash.
+  # With a from_class parameter, limits conversion to only a certain class of keys.
+  # It defaults to nil which convert any key class.
+  #
+  #   require 'facet/hash/keys_to_string'
+  #
+  #   foo = { :name=>'Gavin', :wife=>:Lisa }
+  #   foo.to_s_keys    #=>  { "name"=>"Gavin", "wife"=>:Lisa }
+  #   foo.inspect      #=>  { :name =>"Gavin", :wife=>:Lisa }
+  #
+  def keys_to_s( from_class=nil )
+    raise ArgumentError, "Parameter must be a class" unless from_class.kind_of?(Class) if from_class
+    self.dup.keys_to_s!( from_class )
+  end
+  
+  
+  # Synonym for Hash#keys_to_string, but modifies the receiver in place (and returns it).
+  # With a from_class parameter, limits conversion to only a certain class of keys.
+  # It defaults to nil which convert any key class.
+  #
+  #   require 'facet/hash/keys_to_string'
+  #
+  #   foo = { :name=>'Gavin', :wife=>:Lisa }
+  #   foo.to_s_keys!    #=>  { "name"=>"Gavin", "wife"=>:Lisa }
+  #   foo.inspect       #=>  { "name"=>"Gavin", "wife"=>:Lisa }
+  #
+  def keys_to_s!( from_class=nil )
+    raise ArgumentError, "Parameter must be a class" unless from_class.kind_of?(Class) if from_class
+    if from_class
+      self.each_key{ |k| self[k.to_s]=self.delete(k) if k.respond_to?(:to_s) and k.class == from_class }
+    else
+      self.each_key{ |k| self[k.to_s]=self.delete(k) if k.respond_to?(:to_s) }
+    end
+    self
+  end
+
+  # For Ruby/Extensions compatibility.
+  alias_method( :convert_keys, :keys_to_s )
+  alias_method( :convert_keys!, :keys_to_s! )
+
+  # These are deprecated.
+  #alias_method( :keys_to_string, :keys_to_s )
+  #alias_method( :keys_to_string!, :keys_to_s! )
+  
+end

data/lib/facet/hash/keys_to_sym.rb

@@ -0,0 +1,59 @@
+#--
+# Adapted from Gavin Sinclair's graceous work #symbolify_keys.
+#++
+class Hash
+
+  # Converts all keys in the Hash to be Symbol values, returning a new Hash.
+  # With a from_class parameter, limits conversion to only a certain class of keys.
+  # It defaults to String --use nil to convert any key class.
+  #
+  #   require 'facet/hash/keys_to_symbol'
+  #
+  #   foo = { :name=>'Gavin', 'wife'=>:Lisa }
+  #   foo.keys_to_sym    #=>  { :name=>"Gavin", :wife=>:Lisa }
+  #   foo.inspect        #=>  { "name" =>"Gavin", "wife"=>:Lisa }
+  #
+  def keys_to_sym( from_class=String )
+    raise ArgumentError, "Parameter must be a class" unless from_class.kind_of?(Class) if from_class
+    self.dup.keys_to_sym!( from_class )
+  end
+  
+  # Synonym for Hash#keys_to_symbol, but modifies the receiver in place (and returns it).
+  # With a from_class parameter, limits conversion to only a certain class of keys.
+  # It defaults to String --use nil to convert any key class.
+  #
+  #   require 'facet/hash/keys_to_symbol'
+  #
+  #   foo = { 'name'=>'Gavin', 'wife'=>:Lisa }
+  #   foo.keys_to_sym!    #=>  { :name=>"Gavin", :wife=>:Lisa }
+  #   foo.inspect         #=>  { :name=>"Gavin", :wife=>:Lisa }
+  #
+  def keys_to_sym!( from_class=String )
+    raise ArgumentError, "Parameter must be a class" unless from_class.kind_of?(Class) if from_class
+    if from_class
+      self.each_key{ |k| self[k.to_sym]=self.delete(k) if k.respond_to?(:to_sym) and k.class == from_class }
+    else
+      self.each_key{ |k| self[k.to_sym]=self.delete(k) if k.respond_to?(:to_sym) }
+    end
+    self
+  end
+
+  # Aliases for better Extensions and Rails compatibility
+  alias_method( :symbolize_keys, :keys_to_sym )
+  alias_method( :symbolize_keys!, :keys_to_sym! )
+  
+  #--
+  # Old names (deprecated):
+  #alias_method( :keys_to_symbol, :keys_to_sym )
+  #alias_method( :keys_to_symbol!, :keys_to_sym! )
+  #++
+  
+  #--
+  # Rails has these aliases too, but they are not very good for 
+  # gerenal use, IMHO. But perhaps someone can convince me otherwise.
+  #alias_method( :to_options,  :symbolize_keys )
+  #alias_method( :to_options!, :symbolize_keys! )
+  #++
+  
+end
+

data/lib/facet/hash/shuffle.rb

@@ -0,0 +1,51 @@
+#--
+# Adapted from rand.rb by:
+# * Ilmari Heikkinen <mailto:kig@misfiring.net>
+# * Christian Neukirchen <mailto:chneukirchen@gmail.com>
+#++
+class Hash
+
+  # Return the key-value pairs with _keys_ and _values_
+  # shuffled independedly.
+  #
+  #   require 'facet/hash/shuffle'
+  #
+  #   {:a=>1, :b=>2, :c=>3}.shuffle_hash_pairs  
+  #
+  # produces
+  #
+  #   [[:a, 3], [:b, 1], [:c, 2]]
+  #
+  def shuffle_hash_pairs
+    keys.shuffle.zip(values.sort_by{Kernel.rand})
+  end
+
+  # Returns a copy of the hash with _values_ arranged
+  # in new random order.
+  #
+  #   require 'facet/hash/shuffle'
+  #
+  #   h = {:a=>1, :b=>2, :c=>3}
+  #   h.shuffle_hash  #=> {:b=>2, :c=>1, :a>3}
+  #
+  def shuffle_hash
+    shuffled = {}
+    shuffle_hash_pairs.each{|k, v| shuffled[k] = v }
+    shuffled
+  end
+
+  # Destructive shuffle_hash.  Arrange the values in 
+  # a new random order.
+  #
+  #   require 'facet/hash/shuffle'
+  #
+  #   h = {:a => 1, :b => 2, :c => 3}
+  #   h.shuffle_hash!
+  #   h  #=> {:b=>2, :c=>1, :a=>3}
+  #
+  def shuffle_hash!
+    shuffle_hash_pairs.each{ |k, v| self[k] = v }
+    self
+  end
+
+end

data/lib/facet/hash/slice.rb

@@ -0,0 +1,11 @@
+class Hash
+  # Alias #slice to #values_at.
+  #
+  #   require "facet/hash/slice"
+  # 
+  #   h = { :a => 1, :b => 2, :c => 3 }
+  #   h.slice(:a)      #=> [1]
+  #   h.slice(:a, :b)  #=> [1,2]
+  #
+  alias_method( :slice, :values_at )
+end

data/lib/facet/hash/swap!.rb

@@ -0,0 +1,14 @@
+class Hash
+  # Swap the values of a pair of keys.
+  #
+  #   require 'facet/hash/swap!'
+  #
+  #   {:a=>1,:b=>2}.swap!  #=> {:a=>2,:b=>1}
+  #
+  def swap!( key1, key2 )
+    tmp = self[key1]
+    self[key1] = self[key2]
+    self[key2] = tmp
+    self
+  end
+end

data/lib/facet/hash/swapkey!.rb

@@ -0,0 +1,22 @@
+#--
+# Credit goes to Gavin Sinclair.
+#++
+class Hash
+  # Modifies the receiving Hash so that the value previously referred to by 
+  # _oldkey_ is referenced by _newkey_; _oldkey_ is removed from the Hash.
+  # If _oldkey_ does not exist as a key in the Hash, no change is effected.
+  #
+  # Returns a reference to the Hash.
+  #
+  #   require 'facet/hash/swapkey!'
+  #
+  #   foo = { :a=>1, :b=>2 }
+  #   foo.swapkey!('a',:a)       #=> { 'a'=>1, :b=>2 }
+  #   foo.swapkey!('b',:b)       #=> { 'a'=>1, 'b'=>2 }
+  #   foo.swapkey!('foo','bar')  #=> { 'a'=>1, 'b'=>2 }
+  #
+  def swapkey!( newkey, oldkey )
+    self[newkey] = self.delete(oldkey) if self.has_key?(oldkey)
+    self
+  end
+end

data/lib/facet/hash/to_h.rb

@@ -0,0 +1,13 @@
+class Hash
+  # Return a rehashing of _self_.
+  #
+  #   require 'facet/hash/to_h'
+  #
+  #   {"a"=>1,"b"=>2}.to_h  #=> {"b"=>2,"a"=>1}
+  #
+  #--
+  # A horse is a horse, a horse of course.
+  #++
+  def to_h; rehash; end
+end
+

data/lib/facet/hash/to_ostruct.rb

@@ -0,0 +1,30 @@
+require 'ostruct'
+class Hash
+  
+  # Turns a hash into a generic object using an OpenStruct.
+  #
+  #   require 'facet/hash/to_ostruct'
+  #
+  #   o = { 'a' => 1 }.to_ostruct
+  #   o.a  #=> 1
+  #
+  def to_ostruct
+    OpenStruct.new( self )
+  end
+  
+  # Like to_ostruct but recusively objectifies all hash elements as well.
+  #
+  #   require 'facet/hash/to_ostruct'
+  #
+  #   o = { 'a' => { 'b' => 1 } }.to_ostruct_recurse
+  #   o.a.b  #=> 1
+  #
+  def to_ostruct_recurse
+    o = self.dup
+    each_pair do |k,v|
+      o[k] = v.to_ostruct_recurse if v.respond_to?( :to_ostruct_recurse )
+    end
+    OpenStruct.new( o )
+  end
+  
+end 

data/lib/facet/hash/traverse.rb

@@ -0,0 +1,35 @@
+
+class Hash
+
+  # Returns a new hash created by traversing the hash and its subhashes,
+  # executing the given block on the key and value. The block should 
+  # return a 2-element array of the form +[key, value]+.
+  #
+  #   require 'facet/hash/traverse'
+  #
+  #   h = { "A"=>"A", "B"=>"B" }
+  #   h.traverse { |k,v| [k.downcase, v] }
+  #   h  #=> { "a"=>"A", "b"=>"B" }
+  #
+  def traverse(&b)
+    inject({}) do |h,(k,v)|
+      nk, nv = b[k,v]
+      h[nk] = ( Hash === v ? v.traverse(&b) : nv )
+      h
+    end
+  end
+
+  # In place version of traverse, which traverses the hash and its
+  # subhashes, executing the given block on the key and value.
+  #
+  #   require 'facet/hash/traverse'
+  #
+  #   h = { "A"=>"A", "B"=>"B" }
+  #   h.traverse! { |k,v| [k.downcase, v] }
+  #   h  #=> { "a"=>"A", "b"=>"B" }
+  #
+  def traverse!( &yld )
+    self.replace( self.traverse( &yld ) )
+  end
+
+end

data/lib/facet/hash/update_each.rb

@@ -0,0 +1,24 @@
+class Hash
+  # Iterates through each pair and updates a the hash 
+  # in place. This is formally equivalent to #collate!
+  # But does not use #collate to accomplish the task.
+  # Hence #update_each is probably a bit faster.
+  #
+  #   require 'facet/hash/update_each'
+  #
+  #   # example to do
+  #
+  #--
+  # Note that this may get some fine tuning as currently
+  # it expects the block to return a "mini-hash" pair.
+  #++
+  def update_each  # :yield:
+    dup.each_pair{ |k,v| update( yield(k,v) ); }
+    self
+  end
+  # Same as #update_each, but deletes the key element first.
+  def replace_each  # :yield:
+    dup.each_pair{ |k,v| delete( k ); update( yield(k,v) ); }
+    self
+  end
+end

data/lib/facet/hash/weave.rb

@@ -0,0 +1,64 @@
+class Hash
+  # Weaves two hashes producing a new hash.
+  # The two hashes need to be compatible
+  # according to the following rules for each node:
+  #
+  #   <tt>
+  #   hash, hash => hash (recursive +)
+  #   hash, array => error
+  #   hash, value => error
+  #   array, hash => error
+  #   array, array => array + array
+  #   array, value => array << value
+  #   value, hash => error
+  #   value, array => array.unshift(valueB)
+  #   valueA, valueB => valueB
+  #   </tt>
+  #
+  # Example:
+  #
+  #   require 'facet/hash/weave'
+  #
+  #   # to do
+  #
+  def weave(h)
+    raise ArgumentError, "Hash expected" unless h.kind_of?(Hash)
+    s = self.clone
+    h.each { |k,node|
+      node_is_hash = node.kind_of?(Hash)
+      node_is_array = node.kind_of?(Array)
+      if s.has_key?(k)
+        self_node_is_hash = s[k].kind_of?(Hash)
+        self_node_is_array = s[k].kind_of?(Array)
+        if self_node_is_hash
+          if node_is_hash
+            s[k] = s[k].weave(node)
+          elsif node_is_array
+            raise ArgumentError, 'Incompatible hash addition' #self[k] = node
+          else
+            raise ArgumentError, 'Incompatible hash addition' #self[k] = node
+          end
+        elsif self_node_is_array
+          if node_is_hash
+            raise ArgumentError, 'Incompatible hash addition' #self[k] = node
+          elsif node_is_array
+            s[k] += node
+          else
+            s[k] << node
+          end
+        else
+          if node_is_hash
+            raise ArgumentError, 'Incompatible hash addition' #self[k] = node
+          elsif node_is_array
+            s[k].unshift( node )
+          else
+            s[k] = node
+          end
+        end
+      else
+        s[k] = node
+      end
+    }
+    s
+  end
+end

data/lib/facet/hash/zipnew.rb

@@ -0,0 +1,15 @@
+class Hash
+  # Creates a new hash from two arrays --a keys array and
+  # a values array.
+  #
+  #   require 'facet/hash/zipnew'
+  #
+  #   Hah.zipnew(["a","b","c"], [1,2,3])
+  #     #=> { "a"=>1, "b"=>2, "c"=>3 }
+  #
+  def Hash.zipnew(keys,values) # or some better name
+    h = {}
+    keys.size.times{ |i| h[ keys[i] ] = values[i] }
+    h
+  end
+end

data/lib/facet/integer.rb

@@ -0,0 +1,9 @@
+
+# base
+
+# common
+require "facet/integer/factorial"
+require "facet/integer/evenodd?"
+require "facet/integer/times_collect"
+
+# uncommon