Class: Hash

Inherits:
Object show all
Defined in:
lib/reactive_extensions/hash/sanitation.rb,
lib/reactive_extensions/object/sets.rb,
lib/reactive_extensions/hash/subtraction.rb

Overview

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

Instance Method Summary collapse

Instance Method Details

#-(hash) ⇒ Object

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

Raises:

  • (ArgumentError) 


16
17
18
19
 
# File 'lib/reactive_extensions/hash/subtraction.rb', line 16

def - (hash)
  raise ArgumentError.new("Hash can only be subtracted from its superset") unless superset_of? hash
  deep_dup.reject {|key, value| hash.has_key? key }
end

#clean(*bad_keys) ⇒ Object Also known as: not, except

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'}



38
39
40
41
 
# File 'lib/reactive_extensions/hash/sanitation.rb', line 38

def clean(*bad_keys)
  dup = self.reject {|key, value| bad_keys.flatten.include?(key) }
  dup
end

#clean!(*bad_keys) ⇒ Object Also known as: not!, except!

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'}



73
74
75
76
 
# File 'lib/reactive_extensions/hash/sanitation.rb', line 73

def clean!(*bad_keys)
  reject! {|key, value| bad_keys.flatten.include?(key) }
  self
end

#only(*good_keys) ⇒ Object

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'}



94
95
96
 
# File 'lib/reactive_extensions/hash/sanitation.rb', line 94

def only(*good_keys)
  dup = self.select {|key, value| good_keys.flatten.include?(key) }
end

#only!(*good_keys) ⇒ Object

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                                     # => {}



111
112
113
114
 
# File 'lib/reactive_extensions/hash/sanitation.rb', line 111

def only!(*good_keys)
  select! {|key, value| good_keys.flatten.include?(key) }
  self
end

#standardize(*kees) ⇒ Object

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



137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/reactive_extensions/hash/sanitation.rb', line 137

def standardize(*kees)
  options = kees.extract_options!
  dup     = deep_dup.only(kees)

  kees.each do |key| 
    unless dup.has_key? key
      raise ArgumentError.new("#{self} is missing required key #{key}") if options[:errors]
      dup[key] = nil
    end
  end

  dup
end

#standardize!(*kees) ⇒ Object

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'}



173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/reactive_extensions/hash/sanitation.rb', line 173

def standardize!(*kees)
  options = kees.extract_options!

  kees.each do |key|
    unless only!(kees).has_key? key
      raise ArgumentError.new("#{self} is missing required key #{key}") if options[:errors]
      self[key] = nil
    end
  end

  self
end

#subset_of?(hash) ⇒ Boolean

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

Returns:

  • (Boolean)

Raises:

  • (ArgumentError) 


17
18
19
20
21
 
# File 'lib/reactive_extensions/object/sets.rb', line 17

def subset_of?(hash)
  raise ArgumentError.new("Argument of #subset_of? must share the class of the calling object") unless hash.instance_of? Hash
  each {|key, value| return false unless hash[key] === value }
  true
end

#superset_of?(hash) ⇒ Boolean

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

Returns:

  • (Boolean)

Raises:

  • (ArgumentError) 


37
38
39
40
 
# File 'lib/reactive_extensions/object/sets.rb', line 37

def superset_of?(hash)
  raise ArgumentError.new("Argument of Hash#superset_of? must be a hash") unless hash.instance_of? Hash
  hash.subset_of? self
end