hash_extend 0.0.1 → 1.0.0

data/README.md

@@ -1,2 +1,265 @@
-hash_extend
-===========
+# HashExtend
+
+Extend ruby Hash. No override.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'hash_extend'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install hash_extend
+
+## Usage
+
+### stealth_delete
+
+Delete key(s) passed by, but return the hash instead of the deleted value
+
+```ruby
+	stealth_delete! *keys
+	stealth_delete *keys
+```
+
+Demo
+
+```ruby
+	{:one=>1, :two=>2, :three=>3}.stealth_delete :one
+	#=> {:two=>2, :three=>3}
+	
+	{:one=>1, :two=>2, :three=>3}.stealth_delete :one, :three
+	#=> {:two=>2}
+	
+	{:one=>1, :two=>2, :three=>3}.stealth_delete :four
+	#=> {:one=>1, :two=>2, :three=>3}
+	
+	{:one=>1, :two=>2, :three=>3}.stealth_delete :one, :four
+	#=> {:two=>2, :three=>3}
+```
+
+Code
+
+```ruby	
+	def stealth_delete! *keys
+	  	keys.each do |key|
+	    	delete key
+	  	end
+	  	return self
+	end
+```
+
+
+### map_values
+
+Update values through block
+
+```ruby
+	map_values!
+	map_values
+```
+
+Demo
+
+```ruby
+	# square values
+	{:one=>1, :two=>2, :three=>3}.map_values{ |value| value ** 2 }
+	#=> {:one=>1, :two=>4, :three=>9}
+```
+
+Code
+
+```ruby	
+	def map_values!
+  		self.each do |key, value|
+    		self[key] = yield value
+  		end
+	end
+```
+
+
+### map_keys
+
+Update keys through block
+
+```ruby
+	map_keys!
+	map_keys
+```
+
+Demo
+
+```ruby
+	{"one"=>1, "two"=>2, "three"=>3}.map_keys(&:to_sym)
+	#=> {:one=>1, :two=>2, :three=>3}
+```
+
+Code
+
+```ruby	
+	def map_keys
+    	self.inject({}) do |hash, (key, value)|
+      		hash[yield key] = value; hash
+    	end
+	end
+	
+	def map_keys! &block
+    	to_map = self.dup
+    	self.clear.merge! to_map.map_keys &block
+  	end
+```
+
+Perfomances : Generaly, use the "!" is faster than the "no self modification" methods. Cause the last one used to "dup" the object. As we can't modify keys hash during iteration, here it's the reverse.
+
+
+### delete_many
+
+Delete severals keys in one
+
+Demo
+
+```ruby
+	h = Hash[:one, 1, :two, 2, :three, 3]		#=> {:one=>1, :two=>2, :three=>3}
+	h.delete_many(:un, :trois)					#=> [1, 3]
+	h											#=> {:two=>2}
+	
+	h.delete_many(:six)							#=> [nil]
+```
+
+Code
+
+```ruby	
+	def delete_many *keys
+  		keys.map{ |key| self.delete(key) }
+	end
+```
+
+
+### insert
+
+Insert a value through descendance of keys (hash in hash)
+
+Demo
+
+```ruby
+	h = Hash.new		#=> {}
+	h.insert(12, :calendar, :gregorian, :months)
+	#=> {:calendar => {:gregorian => {:months => 12}}}
+
+	h.insert(13, :calendar, :lunar, :months)
+	#=> {:calendar => {:gregorian => {:months => 12}, :lunar => {:months => 13}}}
+```
+
+Code
+
+```ruby	
+	def insert value, *keys
+  		if keys.size > 1
+    		shifted = keys.shift
+    
+    		self[shifted] ||= Hash.new
+    		self[shifted] = self[shifted].insert value, *keys
+  		else
+    		self[keys.first] = value
+  		end
+  	
+  		self
+	end
+```
+
+
+### compact
+
+Allow to compact hash just like arrays. Well, you can check nil, or black, or whatever you want on keys OR values
+
+```ruby
+	compact! options = Hash.new
+	compact options = Hash.new
+```
+
+Arguments : ':compare' must be in %w{key value}, default is :value
+Arguments : ':with' is recommended in %w{blank? empty?}, default is :nil?
+
+Demo
+
+```ruby
+	{:un=>1, :deux=>2, :trois=>3, :quatre=>nil, :cinq=>[]}.compact!
+	#=> {:cinq=>[], :un=>1, :deux=>2, :trois=>3}
+
+	{:un=>1, :deux=>2, :trois=>3, :quatre=>nil, :cinq=>[]}.compact!(:with=>:blank?)
+	#=> {:un=>1, :deux=>2, :trois=>3}
+	
+	# for the perverts ones
+	{:un=>1, :deux=>2, :trois=>3, :quatre=>nil, :cinq=>[]}.compact!(:with=>"is_a?(Fixnum)")
+	#=> {:quatre=>nil, :cinq=>[]}
+	
+	# And for the ones who REALLY care about memory
+	{:un=>1, "deux"=>2, "trois"=>3, "quatre"=>nil, :cinq=>[]}.compact!(:compare => :key, :with=>"is_a?(String)")
+	#=> {:un=>1, :cinq=>[]}
+```
+
+Code
+
+```ruby	
+	def compact! options = Hash.new
+  		compare = options.delete(:compare) || :value
+  		raise ArgumentError, ":compare option must be in %w{key value}" unless [:key, :value].include? compare.to_sym
+  
+  		if (with = options.delete :with)
+    		self.each do |key, value|
+      			self.delete(key) if eval "#{ compare }.#{ with }"
+    		end
+    
+  		else
+    		self.each do |key, value|
+      			self.delete(key) if eval "#{ compare }.nil?"
+    		end
+  		end
+  
+  		self
+	end
+```
+
+
+### select_by
+
+Select into hash from a collection of keys. Usefull to select correct params after a form.
+
+```ruby
+	select_by! *collection
+	select_by *collection
+```
+
+Demo
+
+```ruby
+	{:one=>1, :two=>2, :three=>3, :four=>4}.select_by :one, :three
+	#=> {:one=>1, :three=>3}
+	
+	{:one=>1, :two=>2, :three=>3, :four=>4}.select_by :one, :six
+	#=> {:one=>1}
+	
+	{:one=>1, :two=>2, :three=>3, :four=>4}.select_by :six, :seven
+	#=> {}
+```
+
+Code
+
+```ruby	
+	def select_by! *collection
+  		self.keep_if{ |field, _| collection.include? field.to_sym }  
+	end
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/lib/hash_extend/version.rb

@@ -1,3 +1,3 @@
 module HashExtend
-  VERSION = "0.0.1"
+  VERSION = "1.0.0"
 end

data/lib/hash_extend.rb

@@ -1,19 +1,114 @@
 require "hash_extend/version"
 
 class Hash
+
+  # ?> {1=>1, 2=>2}.stealth_delete(1)
+  #   => {2=>2}
+  # delete key(s) but return self instead of deleted value
+  def stealth_delete! *keys
+    keys.each do |key|
+      delete key
+    end
+    return self
+  end
+  
+  
+  # ?> {1=>1, 2=>2}.map_values{ |v| v**2 }
+  #   => {1=>1, 2=>4}
+  # modify values fro hash through block
+  def map_values!
+    self.each do |key, value|
+      self[key] = yield value
+    end
+  end
+  
+  # ?> {1=>1, 2=>2}.map_keys{ |k| k.to_s }
+  #   => {"2"=>2, "1"=>1}
+  # modify keys from hash through block
+  def map_keys
+    self.inject({}) do |hash, (key, value)|
+      hash[yield key] = value; hash
+    end
+  end
+  
+  def map_keys! &block
+    to_map = self.dup
+    self.clear.merge! to_map.map_keys &block
+  end
+  
+  
+  # ?> h = Hash[:un, 1, :deux, 2, :trois, 3]
+  #   => {:un=>1, :deux=>2, :trois=>3}
+  # ?> h.delete_many(:un, :trois)
+  #   => [1, 3]
+  # ?> h
+  #   => {:deux=>2}
+  #  
+  # ?> h.delete_many(:six)
+  #   => [nil]
+  # delete severals keys in one time
   def delete_many *keys
     keys.map{ |key| self.delete(key) }
   end
-
-  def select_from_collection! collection
-    self.keep_if{ |field, value| collection.include? field.to_sym }
+  
+  
+  # ?> insert("valeur", Hash.new, :key_one, :key_two, :key_wi)
+  #   => {:key_one=>{:key_two=>{:key_wi=>"valeur"}}}
+  # insert a value trough severals "levels" of hashs
+  def insert value, *keys
+    if keys.size > 1
+      shifted = keys.shift
+      
+      self[shifted] ||= Hash.new
+      self[shifted] = self[shifted].insert value, *keys
+    else
+      self[keys.first] = value
+    end
+    
+    self
   end
-
-  ["select_from_collection"].each do |method_name|
-    define_method method_name do |*args|
+  
+  # ?> {:un=>1, :deux=>2, :trois=>3, :quatre=>nil, :cinq=>[]}.compact!
+  #   => {:cinq=>[], :un=>1, :deux=>2, :trois=>3}
+  # ?> {:un=>1, :deux=>2, :trois=>3, :quatre=>nil, :cinq=>[]}.compact!(:with=>:blank?)
+  #   => {:un=>1, :deux=>2, :trois=>3}
+  # ?> {:un=>1, :deux=>2, :trois=>3, :quatre=>nil, :cinq=>[]}.compact!(:with=>"is_a?(Fixnum)")
+  #   => {:quatre=>nil, :cinq=>[]}
+  # allow to compact (like Array), default on value.nil?
+  def compact! options = Hash.new
+    compare = options.delete(:compare) || :value
+    raise ArgumentError, ":compare option must be in %w{key value}" unless [:key, :value].include? compare.to_sym
+    
+    if (with = options.delete :with)
+      self.each do |key, value|
+        self.delete(key) if eval "#{ compare }.#{ with }"
+      end
+      
+    else
+      self.each do |key, value|
+        self.delete(key) if eval "#{ compare }.nil?"
+      end
+    end
+    
+    self
+  end
+  
+  
+  # ?> {:action=>"index", :controller=>"home", :id=>"42", :firstname=>"thomas", :name=>"petrachi"}.select_from_collection! [:id, :firstname, :name]
+  #   => {:firstname=>"thomas", :name=>"petrachi", :id=>"42"}
+  # something like #keep_if, but instead of block, pass collection of keys to select
+  def select_by! collection, *args, &block
+    self.keep_if{ |field, _| collection.include? field.to_sym }  
+  end
+  
+  
+  # duplicate method without self modification
+  [:stealth_delete, :map_values, :compact, :select_by].each do |method_name|
+    define_method method_name do |*args, &block|
       hash = self.dup
-      eval "hash.#{ method_name }! *args"
+      eval "hash.#{ method_name }! *args, &block"
       return hash
     end
   end
+  
 end

metadata

@@ -1,33 +1,23 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: hash_extend
-version: !ruby/object:Gem::Version 
-  hash: 29
+version: !ruby/object:Gem::Version
+  version: 1.0.0
   prerelease: 
-  segments: 
-  - 0
-  - 0
-  - 1
-  version: 0.0.1
 platform: ruby
-authors: 
+authors:
 - Thomas Petrachi
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-09-27 00:00:00 Z
+date: 2012-09-30 00:00:00.000000000 Z
 dependencies: []
-
-description: "in dev : extend hash methods"
-email: 
+description: ! 'in dev : extend hash methods'
+email:
 - thomas.petrachi@vodeclic.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - Gemfile
 - LICENSE.txt
@@ -36,38 +26,28 @@ files:
 - hash_extend.gemspec
 - lib/hash_extend.rb
 - lib/hash_extend/version.rb
-homepage: ""
+homepage: ''
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
-summary: "in dev : add :delete_many"
+summary: ! 'in dev : add :delete_many'
 test_files: []
-