class Hash

Ruby’s core Has class. See documentation for version 2.1.5, 2.0.0, or 1.9.3.

Public Instance Methods

-(hash) click to toggle source

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
clean(*bad_keys) click to toggle source

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
Also aliased as: not, except
clean!(*bad_keys) click to toggle source

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
Also aliased as: not!, except!
except(*bad_keys)
Alias for: clean
except!(*bad_keys)
Alias for: clean!
not(*bad_keys)
Alias for: clean
not!(*bad_keys)
Alias for: clean!
only(*good_keys) click to toggle source

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
only!(*good_keys) click to toggle source

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
standardize(*kees) click to toggle source

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
standardize!(*kees) click to toggle source

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
subset_of?(hash) click to toggle source

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
superset_of?(hash) click to toggle source

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