class Hash
Ruby’s core Has class. See documentation for version 2.1.5, 2.0.0, or 1.9.3.
Public Instance Methods
The #-
method takes a single hash as an argument. It deletes the key-value pairs of the argument from the calling hash. An ArgumentError is raised if the argument is not a hash or not a subset of the
Examples:
{:foo => 'bar', :baz => :qux} - {:baz => :qux} # => {:foo => 'bar'} {:foo => 'bar'} - {:norf => :raboo} # => {:foo => 'bar'} {:foo => 'bar'} - {:foo => 'bar'} {:foo => 'bar'} - [1, 2, 3] # => ArgumentError
# File lib/reactive_extensions/hash/subtraction.rb 16 def - (hash) 17 raise ArgumentError.new("Hash can only be subtracted from its superset") unless superset_of? hash 18 deep_dup.reject {|key, value| hash.has_key? key } 19 end
The #clean
method returns a duplicate of the calling hash with the specified +*bad_keys+, if present, removed. If none of the bad keys are present, #clean
will simply return a duplicate hash.
The #clean
method takes an arbitrary number of parameters, designated +*bad_keys+. Any of these keys that are present in the hash calling the method will be removed in the duplicate that is returned.
#clean
is a non-destructive method. The original hash will still be unchanged after it is called.
#clean
returns the cleaned duplicate of the hash calling it.
#clean
may also be called by the aliases #not
and #except
.
Examples:
hash = {:foo => 'bar', :bar => 'baz'} hash.clean(:foo) # => {:bar => 'baz'} hash.not(:foo, :bar) # => {} hash.except(:bar, :norf) # => {:foo => 'bar'} hash.clean(:norf) # => {:foo => 'bar', :bar => 'baz'} hash # => {:foo => bar', :bar => 'baz'}
# File lib/reactive_extensions/hash/sanitation.rb 38 def clean(*bad_keys) 39 dup = self.reject {|key, value| bad_keys.flatten.include?(key) } 40 dup 41 end
The #clean!
method returns a duplicate of the calling hash with the specified +*bad_keys+, if present, removed. If none of the bad keys are present, #clean!
will simply return a duplicate hash.
#clean!
returns self
.
The #clean!
method takes an arbitrary number of parameters, designated +*bad_keys+. Any of these keys that are present in the hash calling the method will be removed in the duplicate that is returned.
#clean!
is a destructive method that modifies the hash that calls it in place. For an analogous non-destructive method, use #clean
.
#clean!
may also be called by the aliases #not!
and #except!
.
Examples:
hash = {:foo => 'bar', :bar => 'baz'} hash.clean!(:foo) # => {:bar => 'baz'} hash # => {:bar => 'baz'} hash.not!(:foo, :bar) # => {} hash # => {} hash = {:foo => 'bar', :bar => 'baz'} hash.except!(:bar, :norf) # => {:foo => 'bar'} hash # => {:foo => 'bar'}
# File lib/reactive_extensions/hash/sanitation.rb 73 def clean!(*bad_keys) 74 reject! {|key, value| bad_keys.flatten.include?(key) } 75 self 76 end
The #only
method returns a duplicate of the calling hash with only the specified +*good_keys+, if present. If none of the good keys are present, #only
will simply return an empty hash.
#only
is a non-destructive method. The original hash will still be unchanged after it is called.
Examples:
hash = {:foo => 'bar', :bar => 'baz'} hash.only(:foo) # => {:foo => 'bar'} hash.only(:qux) # => {} hash # => {:foo => 'bar', :bar => 'baz'}
# File lib/reactive_extensions/hash/sanitation.rb 94 def only(*good_keys) 95 dup = self.select {|key, value| good_keys.flatten.include?(key) } 96 end
The #only!
method returns a duplicate of the calling hash with only the specified +*good_keys+, if present. If none of the good keys are present, #only!
will simply return an empty hash.
#only!
is a destructive method. The original hash will be changed in place when it is called.
Examples:
hash = {:foo => 'bar', :bar => 'baz'} hash.only!(:foo) # => {:foo => 'bar'} hash.only!(:qux) # => {} hash # => {}
# File lib/reactive_extensions/hash/sanitation.rb 111 def only!(*good_keys) 112 select! {|key, value| good_keys.flatten.include?(key) } 113 self 114 end
The #standardize
method returns a duplicate of the calling hash with the +*keys+ specified as arguments. Any other keys in the hash will be removed. Behavior when adding keys depends on whether the :errors
option is set to true
or false
(default).
If the :errors
option is set to false
, the method will add any missing keys to the hash, populating them with nil
values. If :errors
is set to true
, then an ArgumentError
will be raised unless all values are present in the hash already.
Examples with +:errors => false+:
hash = {:foo => 'bar', :bar => 'baz'} hash.standardize(:foo) # => {:foo => 'bar'} hash.standardize(:foo, :qux) # => {:foo => 'bar', :qux => nil} hash # => {:foo => 'bar', :bar => 'baz'}
Examples with +:errors => true+:
hash = {:foo => 'bar', :bar 'baz'} hash.standardize(:foo, :errors => true) # => {:foo => 'bar'} hash.standardize(:foo, :qux, :errors => true) # => ArgumentError
# File lib/reactive_extensions/hash/sanitation.rb 137 def standardize(*kees) 138 options = kees.extract_options! 139 dup = deep_dup.only(kees) 140 141 kees.each do |key| 142 unless dup.has_key? key 143 raise ArgumentError.new("#{self} is missing required key #{key}") if options[:errors] 144 dup[key] = nil 145 end 146 end 147 148 dup 149 end
The #standardize!
method modifies the calling hash such that its keys match the +*kees+ specified as arguments. Any other keys in the hash will be removed. If passed +:errors => true+, an ArgumentError
will be raised in the event keys present in the arguments are not present in the calling hash. Otherwise, any such keys will be added to the hash and populated with nil values.
#standardize!
is a destructive method; the calling hash will be changed in place when it is called.
Examples with +:errors => false+:
hash = {:foo => 'bar', :bar => 'baz'} hash.standardize!(:foo, :qux) # => {:foo => 'bar', :qux => nil} hash.standardize!(:foo) # => {:foo => 'bar'} hash # => {:foo => 'bar'}
Examples with +:errors => true+:
hash = {:foo => 'bar', :bar 'baz'} hash.standardize!(:foo, :errors => true) # => {:foo => 'bar'} hash.standardize!(:foo, :qux, :errors => true) # => ArgumentError hash # => {:foo => 'bar'}
# File lib/reactive_extensions/hash/sanitation.rb 173 def standardize!(*kees) 174 options = kees.extract_options! 175 176 kees.each do |key| 177 unless only!(kees).has_key? key 178 raise ArgumentError.new("#{self} is missing required key #{key}") if options[:errors] 179 self[key] = nil 180 end 181 end 182 183 self 184 end
The #subset_of?
method checks whether the calling hash is a subset of the given hash
. It returns true if all key-value pairs in the calling hash are also present in the hash passed as an argument. If the calling hash is empty, the method returns true.
Examples:
hash = {:foo => 'bar', :bar => 'baz', :baz => 'qux'} {:baz => 'qux'}.subset_of? hash # => true {:bar => 'baz', :norf => 'foo'}.subset_of? hash # => false {:norf => 'foo'}.subset_of? hash # => false {:foo => 'qux'}.subset_of? hash # => false {}.subset_of? hash # => true {:foo => 'bar'}.subset_of? 'foobar' # => ArgumentError
# File lib/reactive_extensions/object/sets.rb 17 def subset_of?(hash) 18 raise ArgumentError.new("Argument of #subset_of? must share the class of the calling object") unless hash.instance_of? Hash 19 each {|key, value| return false unless hash[key] === value } 20 true 21 end
The #superset_of?
method checks whether the calling hash is a superset of the given hash
. It returns true if all key-value pairs in the calling hash are also present in the hash passed as an argument. If the argument hash is empty, the method returns true.
Examples:
hash = {:foo => 'bar', :bar => 'baz', :baz => 'qux'} hash.superset_of? {:baz => 'qux'} # => true hash.superset_of? {:bar => 'baz', :norf => 'foo'} # => false hash.superset_of? {:norf => 'foo'} # => false hash.superset_of? {:foo => 'qux'} # => false hash.superset_of? {} # => true {:foo => 'bar'}.superset_of? 'foobar' # => ArgumentError
# File lib/reactive_extensions/object/sets.rb 37 def superset_of?(hash) 38 raise ArgumentError.new("Argument of Hash#superset_of? must be a hash") unless hash.instance_of? Hash 39 hash.subset_of? self 40 end