Methods
Public Class methods
from_xml(xml)
  # File activesupport/lib/active_support/core_ext/hash/conversions.rb, line 77
def from_xml(xml)
  typecast_xml_value(unrename_keys(ActiveSupport::XmlMini.parse(xml)))
end
Public Instance methods
assert_valid_keys(*valid_keys)

Validate all keys in a hash match *valid keys, raising ArgumentError on a mismatch. Note that keys are NOT treated indifferently, meaning if you use strings for keys but assert symbols as keys, this will fail.

Examples

{ :name => "Rob", :years => "28" }.assert_valid_keys(:name, :age) # => raises "ArgumentError: Unknown key(s): years"
{ :name => "Rob", :age => "28" }.assert_valid_keys("name", "age") # => raises "ArgumentError: Unknown key(s): name, age"
{ :name => "Rob", :age => "28" }.assert_valid_keys(:name, :age) # => passes, raises nothing
  # File activesupport/lib/active_support/core_ext/hash/keys.rb, line 41
def assert_valid_keys(*valid_keys)
  unknown_keys = keys - [valid_keys].flatten
  raise(ArgumentError, "Unknown key(s): #{unknown_keys.join(", ")}") unless unknown_keys.empty?
end
deep_merge(other_hash)

Returns a new hash with self and other_hash merged recursively.

  # File activesupport/lib/active_support/core_ext/hash/deep_merge.rb, line 3
def deep_merge(other_hash)
  dup.deep_merge!(other_hash)
end
deep_merge!(other_hash)

Returns a new hash with self and other_hash merged recursively. Modifies the receiver in place.

  # File activesupport/lib/active_support/core_ext/hash/deep_merge.rb, line 9
def deep_merge!(other_hash)
  other_hash.each_pair do |k,v|
    tv = self[k]
    self[k] = tv.is_a?(Hash) && v.is_a?(Hash) ? tv.deep_merge(v) : v
  end
  self
end
diff(h2)

Returns a hash that represents the difference between two hashes.

Examples:

{1 => 2}.diff(1 => 2)         # => {}
{1 => 2}.diff(1 => 3)         # => {1 => 2}
{}.diff(1 => 2)               # => {1 => 2}
{1 => 2, 3 => 4}.diff(1 => 2) # => {3 => 4}
  # File activesupport/lib/active_support/core_ext/hash/diff.rb, line 10
def diff(h2)
  dup.delete_if { |k, v| h2[k] == v }.merge!(h2.dup.delete_if { |k, v| has_key?(k) })
end
encode_json(encoder)
  # File activesupport/lib/active_support/json/encoding.rb, line 240
def encode_json(encoder)
  # values are encoded with use_options = false, because we don't want hash representations from ActiveModel to be
  # processed once again with as_json with options, as this could cause unexpected results (i.e. missing fields);

  # on the other hand, we need to run as_json on the elements, because the model representation may contain fields
  # like Time/Date in their original (not jsonified) form, etc.

  "{#{map { |k,v| "#{encoder.encode(k.to_s)}:#{encoder.encode(v, false)}" } * ','}}"
end
except(*keys)

Return a hash that includes everything but the given keys. This is useful for limiting a set of parameters to everything but a few known toggles:

@person.update_attributes(params[:person].except(:admin))

If the receiver responds to convert_key, the method is called on each of the arguments. This allows except to play nice with hashes with indifferent access for instance:

{:a => 1}.with_indifferent_access.except(:a)  # => {}
{:a => 1}.with_indifferent_access.except("a") # => {}
  # File activesupport/lib/active_support/core_ext/hash/except.rb, line 14
def except(*keys)
  dup.except!(*keys)
end
except!(*keys)

Replaces the hash without the given keys.

  # File activesupport/lib/active_support/core_ext/hash/except.rb, line 19
def except!(*keys)
  keys.each { |key| delete(key) }
  self
end
extract!(*keys)
  # File activesupport/lib/active_support/core_ext/hash/slice.rb, line 33
def extract!(*keys)
  result = {}
  keys.each {|key| result[key] = delete(key) }
  result
end
extractable_options?()

By default, only instances of Hash itself are extractable. Subclasses of Hash may implement this method and return true to declare themselves as extractable. If a Hash is extractable, Array#extract_options! pops it from the Array when it is the last element of the Array.

  # File activesupport/lib/active_support/core_ext/array/extract_options.rb, line 7
def extractable_options?
  instance_of?(Hash)
end
reverse_merge(other_hash)

Allows for reverse merging two hashes where the keys in the calling hash take precedence over those in the other_hash. This is particularly useful for initializing an option hash with default values:

def setup(options = {})
  options.reverse_merge! :size => 25, :velocity => 10
end

Using merge, the above example would look as follows:

def setup(options = {})
  { :size => 25, :velocity => 10 }.merge(options)
end

The default :size and :velocity are only set if the options hash passed in doesn’t already have the respective key.

  # File activesupport/lib/active_support/core_ext/hash/reverse_merge.rb, line 17
def reverse_merge(other_hash)
  other_hash.merge(self)
end
reverse_merge!(other_hash)

Performs the opposite of merge, with the keys and values from the first hash taking precedence over the second. Modifies the receiver in place.

This method is also aliased as reverse_update
  # File activesupport/lib/active_support/core_ext/hash/reverse_merge.rb, line 23
def reverse_merge!(other_hash)
  merge!( other_hash ){|k,o,n| o }
end
slice(*keys)

Slice a hash to include only the given keys. This is useful for limiting an options hash to valid keys before passing to a method:

def search(criteria = {})
  assert_valid_keys(:mass, :velocity, :time)
end

search(options.slice(:mass, :velocity, :time))

If you have an array of keys you want to limit to, you should splat them:

valid_keys = [:mass, :velocity, :time]
search(options.slice(*valid_keys))
  # File activesupport/lib/active_support/core_ext/hash/slice.rb, line 15
def slice(*keys)
  keys = keys.map! { |key| convert_key(key) } if respond_to?(:convert_key)
  hash = self.class.new
  keys.each { |k| hash[k] = self[k] if has_key?(k) }
  hash
end
slice!(*keys)

Replaces the hash with only the given keys. Returns a hash contained the removed key/value pairs

{:a => 1, :b => 2, :c => 3, :d => 4}.slice!(:a, :b) # => {:c => 3, :d =>4}
  # File activesupport/lib/active_support/core_ext/hash/slice.rb, line 25
def slice!(*keys)
  keys = keys.map! { |key| convert_key(key) } if respond_to?(:convert_key)
  omit = slice(*self.keys - keys)
  hash = slice(*keys)
  replace(hash)
  omit
end
stringify_keys()

Return a new hash with all keys converted to strings.

  # File activesupport/lib/active_support/core_ext/hash/keys.rb, line 3
def stringify_keys
  dup.stringify_keys!
end
stringify_keys!()

Destructively convert all keys to strings.

  # File activesupport/lib/active_support/core_ext/hash/keys.rb, line 8
def stringify_keys!
  keys.each do |key|
    self[key.to_s] = delete(key)
  end
  self
end
symbolize_keys()

Return a new hash with all keys converted to symbols, as long as they respond to to_sym.

This method is also aliased as to_options
  # File activesupport/lib/active_support/core_ext/hash/keys.rb, line 17
def symbolize_keys
  dup.symbolize_keys!
end
symbolize_keys!()

Destructively convert all keys to symbols, as long as they respond to to_sym.

This method is also aliased as to_options!
  # File activesupport/lib/active_support/core_ext/hash/keys.rb, line 23
def symbolize_keys!
  keys.each do |key|
    self[(key.to_sym rescue key) || key] = delete(key)
  end
  self
end
to_param(namespace = nil)

Converts a hash into a string suitable for use as a URL query string. An optional namespace can be passed to enclose the param names (see example below). The string pairs “key=value” that conform the query string are sorted lexicographically in ascending order.

Examples

{ :name => 'David', :nationality => 'Danish' }.to_param # => "name=David&nationality=Danish"

{ :name => 'David', :nationality => 'Danish' }.to_param('user') # => "user[name]=David&user[nationality]=Danish"
This method is also aliased as to_query
  # File activesupport/lib/active_support/core_ext/object/to_param.rb, line 45
def to_param(namespace = nil)
  collect do |key, value|
    value.to_query(namespace ? "#{namespace}[#{key}]" : key)
  end.sort * '&'
end
to_xml(options = {})

Returns a string containing an XML representation of its receiver:

{"foo" => 1, "bar" => 2}.to_xml
# =>
# <?xml version="1.0" encoding="UTF-8"?>
# <hash>
#   <foo type="integer">1</foo>
#   <bar type="integer">2</bar>
# </hash>

To do so, the method loops over the pairs and builds nodes that depend on the values. Given a pair key, value:

  • If value is a hash there’s a recursive call with key as :root.

  • If value is an array there’s a recursive call with key as :root, and key singularized as :children.

  • If value is a callable object it must expect one or two arguments. Depending on the arity, the callable is invoked with the options hash as first argument with key as :root, and key singularized as second argument. Its return value becomes a new node.

  • If value responds to to_xml the method is invoked with key as :root.

  • Otherwise, a node with key as tag is created with a string representation of value as text node. If value is nil an attribute “nil” set to “true” is added. Unless the option :skip_types exists and is true, an attribute “type” is added as well according to the following mapping:

    XML_TYPE_NAMES = {
      "Symbol"     => "symbol",
      "Fixnum"     => "integer",
      "Bignum"     => "integer",
      "BigDecimal" => "decimal",
      "Float"      => "float",
      "TrueClass"  => "boolean",
      "FalseClass" => "boolean",
      "Date"       => "date",
      "DateTime"   => "datetime",
      "Time"       => "datetime"
    }

By default the root node is “hash”, but that’s configurable via the :root option.

The default XML builder is a fresh instance of Builder::XmlMarkup. You can configure your own builder with the :builder option. The method also accepts options like :dasherize and friends, they are forwarded to the builder.

  # File activesupport/lib/active_support/core_ext/hash/conversions.rb, line 57
def to_xml(options = {})
  require 'active_support/builder' unless defined?(Builder)

  options = options.dup
  options[:indent]  ||= 2
  options[:root]    ||= "hash"
  options[:builder] ||= Builder::XmlMarkup.new(:indent => options[:indent])

  builder = options[:builder]
  builder.instruct! unless options.delete(:skip_instruct)

  root = ActiveSupport::XmlMini.rename_key(options[:root].to_s, options)

  builder.__send__(:method_missing, root) do
    each { |key, value| ActiveSupport::XmlMini.to_tag(key, value, options) }
    yield builder if block_given?
  end
end
with_indifferent_access()

Returns an +ActiveSupport::HashWithIndifferentAccess+ out of its receiver:

{:a => 1}.with_indifferent_access["a"] # => 1
  # File activesupport/lib/active_support/core_ext/hash/indifferent_access.rb, line 9
def with_indifferent_access
  ActiveSupport::HashWithIndifferentAccess.new_from_hash_copying_default(self)
end