Class: ActiveSupport::HashWithIndifferentAccess
Relationships & Source Files | |
Extension / Inclusion / Inheritance Descendants | |
Subclasses:
|
|
Super Chains via Extension / Inclusion / Inheritance | |
Class Chain:
self,
::Hash
|
|
Instance Chain:
self,
::Hash
|
|
Inherits: | Hash |
Defined in: | activesupport/lib/active_support/hash_with_indifferent_access.rb |
Overview
Hash With Indifferent Access
Implements a hash where keys :foo
and "foo"
are considered to be the same.
rgb = ActiveSupport::HashWithIndifferentAccess.new
rgb[:black] = '#000000'
rgb[:black] # => '#000000'
rgb['black'] # => '#000000'
rgb['white'] = '#FFFFFF'
rgb[:white] # => '#FFFFFF'
rgb['white'] # => '#FFFFFF'
Internally symbols are mapped to strings when used as keys in the entire writing interface (calling #[]=, #merge, etc). This mapping belongs to the public interface. For example, given:
hash = ActiveSupport::HashWithIndifferentAccess.new(a: 1)
You are guaranteed that the key is returned as a string:
hash.keys # => ["a"]
Technically other types of keys are accepted:
hash = ActiveSupport::HashWithIndifferentAccess.new(a: 1)
hash[0] = 0
hash # => {"a"=>1, 0=>0}
but this class is intended for use cases where strings or symbols are the expected keys and it is convenient to understand both as the same. For example the params
hash in Ruby on Rails.
Note that core extensions define Hash#with_indifferent_access:
rgb = { black: '#000000', white: '#FFFFFF' }.with_indifferent_access
which may be handy.
To access this class outside of Rails, require the core extension with:
require "active_support/core_ext/hash/indifferent_access"
which will, in turn, require this file.
Class Method Summary
::Hash
- Inherited
.from_trusted_xml | Builds a |
.from_xml | Returns a |
Instance Attribute Summary
-
#extractable_options? ⇒ Boolean
readonly
Returns
true
so that Array#extract_options! finds members of this class.
::Hash
- Inherited
#extractable_options? | By default, only instances of |
Instance Method Summary
-
#[](key)
Same as
Hash#[]
where the key passed as argument can be either a string or a symbol: -
#[]=(key, value)
(also: #store)
Assigns a new value to the hash:
-
#assoc(key)
Same as
Hash#assoc
where the key passed as argument can be either a string or a symbol: - #compact
- #deep_stringify_keys
- #deep_stringify_keys!
- #deep_symbolize_keys
-
#default(key = (no_key = true))
Same as
Hash#default
where the key passed as argument can be either a string or a symbol: -
#delete(key)
Removes the specified key from the hash.
-
#dig(*args)
Same as
Hash#dig
where the key passed as argument can be either a string or a symbol: -
#dup
Returns a shallow copy of the hash.
-
#except(*keys)
(also: #without)
Returns a hash with indifferent access that includes everything except given keys.
-
#fetch(key, *extras)
Same as
Hash#fetch
where the key passed as argument can be either a string or a symbol: -
#fetch_values(*indices, &block)
Returns an array of the values at the specified indices, but also raises an exception when one of the keys can’t be found.
-
#has_key?(key)
Alias for #key?.
-
#include?(key)
Alias for #key?.
-
#key?(key) ⇒ Boolean
(also: #include?, #has_key?, #member?)
Checks the hash for a key matching the argument passed in:
-
#member?(key)
Alias for #key?.
-
#merge(*hashes, &block)
This method has the same semantics of #update, except it does not modify the receiver but rather returns a new hash with indifferent access with the result of the merge.
-
#merge!(*other_hashes, &block)
Alias for #update.
- #nested_under_indifferent_access
- #regular_update
- #regular_writer
- #reject(*args, &block)
-
#replace(other_hash)
Replaces the contents of this hash with other_hash.
-
#reverse_merge(other_hash)
(also: #with_defaults)
Like #merge but the other way around: Merges the receiver into the argument and returns a new hash with indifferent access as result:
-
#reverse_merge!(other_hash)
(also: #with_defaults!)
Same semantics as #reverse_merge but modifies the receiver in-place.
- #select(*args, &block)
- #slice(*keys)
- #slice!(*keys)
-
#store(key, value)
Alias for #[]=.
- #stringify_keys
- #stringify_keys!
- #symbolize_keys (also: #to_options)
-
#to_hash
Convert to a regular hash with string keys.
-
#to_options
Alias for #symbolize_keys.
- #to_options!
- #transform_keys(hash = NOT_GIVEN, &block)
- #transform_keys!(hash = NOT_GIVEN, &block)
- #transform_values(&block)
-
#update(*other_hashes, &block)
(also: #merge!)
Updates the receiver in-place, merging in the hashes passed as arguments:
-
#values_at(*keys)
Returns an array of the values at the specified indices:
-
#with_defaults(other_hash)
Alias for #reverse_merge.
-
#with_defaults!(other_hash)
Alias for #reverse_merge!.
- #with_indifferent_access
-
#without(*keys)
Alias for #except.
::Hash
- Inherited
#assert_valid_keys | Validates all keys in a hash match |
#blank? | A hash is blank if it’s empty: |
#compact_blank! | Removes all blank values from the |
#deep_dup | Returns a deep copy of hash. |
#deep_merge | Returns a new hash with |
#deep_merge! | Same as |
#deep_stringify_keys | Returns a new hash with all keys converted to strings. |
#deep_stringify_keys! | Destructively converts all keys to strings. |
#deep_symbolize_keys | Returns a new hash with all keys converted to symbols, as long as they respond to |
#deep_symbolize_keys! | Destructively converts all keys to symbols, as long as they respond to |
#deep_transform_keys | Returns a new hash with all keys converted by the block operation. |
#deep_transform_keys! | Destructively converts all keys by using the block operation. |
#deep_transform_values | Returns a new hash with all values converted by the block operation. |
#deep_transform_values! | Destructively converts all values by using the block operation. |
#except | Returns a hash that includes everything except given keys. |
#except! | Removes the given keys from hash and returns it. |
#extract! | Removes and returns the key/value pairs matching the given keys. |
#nested_under_indifferent_access | Alias for Hash#with_indifferent_access. |
#reverse_merge | Merges the caller into |
#reverse_merge! | Destructive #reverse_merge. |
#reverse_update | Alias for Hash#reverse_merge!. |
#slice! | Replaces the hash with only the given keys. |
#stringify_keys | Returns a new hash with all keys converted to strings. |
#stringify_keys! | Destructively converts all keys to strings. |
#symbolize_keys | Returns a new hash with all keys converted to symbols, as long as they respond to |
#symbolize_keys! | Destructively converts all keys to symbols, as long as they respond to |
#to_options | Alias for Hash#symbolize_keys. |
#to_options! | Alias for Hash#symbolize_keys!. |
#to_param | Alias for Hash#to_query. |
#to_query | Returns a string representation of the receiver suitable for use as a URL query string: |
#to_xml | Returns a string containing an XML representation of its receiver: |
#with_defaults | Alias for Hash#reverse_merge. |
#with_defaults! | Alias for Hash#reverse_merge!. |
#with_indifferent_access | Returns an |
Constructor Details
.new(constructor = nil) ⇒ HashWithIndifferentAccess
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 70
def initialize(constructor = nil) if constructor.respond_to?(:to_hash) super() update(constructor) hash = constructor.is_a?(Hash) ? constructor : constructor.to_hash self.default = hash.default if hash.default self.default_proc = hash.default_proc if hash.default_proc elsif constructor.nil? super() else super(constructor) end end
Class Method Details
.[](*args)
[ GitHub ]Instance Attribute Details
#extractable_options? ⇒ Boolean
(readonly)
Returns true
so that Array#extract_options! finds members of this class.
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 58
def true end
Instance Method Details
#[](key)
Same as Hash#[]
where the key passed as argument can be either a string or a symbol:
counters = ActiveSupport::HashWithIndifferentAccess.new
counters[:foo] = 1
counters['foo'] # => 1
counters[:foo] # => 1
counters[:zoo] # => nil
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 168
def [](key) super(convert_key(key)) end
#[]=(key, value) Also known as: #store
Assigns a new value to the hash:
hash = ActiveSupport::HashWithIndifferentAccess.new
hash[:key] = 'value'
This value can be later fetched using either :key
or 'key'
.
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 98
def []=(key, value) regular_writer(convert_key(key), convert_value(value, conversion: :assignment)) end
#assoc(key)
Same as Hash#assoc
where the key passed as argument can be either a string or a symbol:
counters = ActiveSupport::HashWithIndifferentAccess.new
counters[:foo] = 1
counters.assoc('foo') # => ["foo", 1]
counters.assoc(:foo) # => ["foo", 1]
counters.assoc(:zoo) # => nil
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 181
def assoc(key) super(convert_key(key)) end
#compact
[ GitHub ]# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 375
def compact dup.tap(&:compact!) end
#deep_stringify_keys
[ GitHub ]# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 319
def deep_stringify_keys; dup end
#deep_stringify_keys!
[ GitHub ]# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 317
def deep_stringify_keys!; self end
#deep_symbolize_keys
[ GitHub ]# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 324
def deep_symbolize_keys; to_hash.deep_symbolize_keys! end
#default(key = (no_key = true))
Same as Hash#default
where the key passed as argument can be either a string or a symbol:
hash = ActiveSupport::HashWithIndifferentAccess.new(1)
hash.default # => 1
hash = ActiveSupport::HashWithIndifferentAccess.new { |hash, key| key }
hash.default # => nil
hash.default('foo') # => 'foo'
hash.default(:foo) # => 'foo'
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 223
def default(key = (no_key = true)) if no_key super() else super(convert_key(key)) end end
#delete(key)
Removes the specified key from the hash.
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 303
def delete(key) super(convert_key(key)) end
#dig(*args)
Same as Hash#dig
where the key passed as argument can be either a string or a symbol:
counters = ActiveSupport::HashWithIndifferentAccess.new
counters[:foo] = { bar: 1 }
counters.dig('foo', 'bar') # => 1
counters.dig(:foo, : ) # => 1
counters.dig(:zoo) # => nil
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 208
def dig(*args) args[0] = convert_key(args[0]) if args.size > 0 super(*args) end
#dup
Returns a shallow copy of the hash.
hash = ActiveSupport::HashWithIndifferentAccess.new({ a: { b: 'b' } })
dup = hash.dup
dup[:a][:c] = 'c'
hash[:a][:c] # => "c"
dup[:a][:c] # => "c"
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 264
def dup self.class.new(self).tap do |new_hash| set_defaults(new_hash) end end
#except(*keys) Also known as: #without
Returns a hash with indifferent access that includes everything except given keys.
hash = { a: "x", b: "y", c: 10 }.with_indifferent_access
hash.except(:a, "b") # => {c: 10}.with_indifferent_access
hash # => { a: "x", b: "y", c: 10 }.with_indifferent_access
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 311
def except(*keys) dup.except!(*keys) end
#fetch(key, *extras)
Same as Hash#fetch
where the key passed as argument can be either a string or a symbol:
counters = ActiveSupport::HashWithIndifferentAccess.new
counters[:foo] = 1
counters.fetch('foo') # => 1
counters.fetch(:, 0) # => 0
counters.fetch(: ) { |key| 0 } # => 0
counters.fetch(:zoo) # => KeyError: key not found: "zoo"
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 195
def fetch(key, *extras) super(convert_key(key), *extras) end
#fetch_values(*indices, &block)
Returns an array of the values at the specified indices, but also raises an exception when one of the keys can’t be found.
hash = ActiveSupport::HashWithIndifferentAccess.new
hash[:a] = 'x'
hash[:b] = 'y'
hash.fetch_values('a', 'b') # => ["x", "y"]
hash.fetch_values('a', 'c') { |key| 'z' } # => ["x", "z"]
hash.fetch_values('a', 'c') # => KeyError: key not found: "c"
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 251
def fetch_values(*indices, &block) indices.map! { |key| convert_key(key) } super end
#has_key?(key)
Alias for #key?.
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 156
alias_method :has_key?, :key?
#include?(key)
Alias for #key?.
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 155
alias_method :include?, :key?
#key?(key) ⇒ Boolean
Also known as: #include?, #has_key?, #member?
Checks the hash for a key matching the argument passed in:
hash = ActiveSupport::HashWithIndifferentAccess.new
hash['key'] = 'value'
hash.key?(:key) # => true
hash.key?('key') # => true
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 151
def key?(key) super(convert_key(key)) end
#member?(key)
Alias for #key?.
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 157
alias_method :member?, :key?
#merge(*hashes, &block)
This method has the same semantics of #update, except it does not modify the receiver but rather returns a new hash with indifferent access with the result of the merge.
#merge!(*other_hashes, &block)
Alias for #update.
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 143
alias_method :merge!, :update
#nested_under_indifferent_access
[ GitHub ]# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 66
def nested_under_indifferent_access self end
#regular_update
[ GitHub ]# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 90
alias_method :regular_update, :update unless method_defined?(:regular_update)
#regular_writer
[ GitHub ]# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 89
alias_method :regular_writer, :[]= unless method_defined?(:regular_writer)
#reject(*args, &block)
[ GitHub ]# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 332
def reject(*args, &block) return to_enum(:reject) unless block_given? dup.tap { |hash| hash.reject!(*args, &block) } end
#replace(other_hash)
Replaces the contents of this hash with other_hash.
h = { "a" => 100, "b" => 200 }
h.replace({ "c" => 300, "d" => 400 }) # => {"c"=>300, "d"=>400}
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 298
def replace(other_hash) super(self.class.new(other_hash)) end
#reverse_merge(other_hash) Also known as: #with_defaults
Like #merge but the other way around: Merges the receiver into the argument and returns a new hash with indifferent access as result:
hash = ActiveSupport::HashWithIndifferentAccess.new
hash['a'] = nil
hash.reverse_merge(a: 0, b: 1) # => {"a"=>nil, "b"=>1}
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 283
def reverse_merge(other_hash) super(self.class.new(other_hash)) end
#reverse_merge!(other_hash) Also known as: #with_defaults!
Same semantics as #reverse_merge but modifies the receiver in-place.
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 289
def reverse_merge!(other_hash) super(self.class.new(other_hash)) end
#select(*args, &block)
[ GitHub ]# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 327
def select(*args, &block) return to_enum(:select) unless block_given? dup.tap { |hash| hash.select!(*args, &block) } end
#slice(*keys)
[ GitHub ]# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 365
def slice(*keys) keys.map! { |key| convert_key(key) } self.class.new(super) end
#slice!(*keys)
[ GitHub ]# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 370
def slice!(*keys) keys.map! { |key| convert_key(key) } super end
#store(key, value)
Alias for #[]=.
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 102
alias_method :store, :[]=
#stringify_keys
[ GitHub ]# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 318
def stringify_keys; dup end
#stringify_keys!
[ GitHub ]# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 316
def stringify_keys!; self end
#symbolize_keys Also known as: #to_options
[ GitHub ]# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 322
def symbolize_keys; to_hash.symbolize_keys! end
#to_hash
Convert to a regular hash with string keys.
#to_options
Alias for #symbolize_keys.
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 323
alias_method :, :symbolize_keys
#to_options!
[ GitHub ]# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 325
def ; self end
#transform_keys(hash = NOT_GIVEN, &block)
[ GitHub ]# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 344
def transform_keys(hash = NOT_GIVEN, &block) return to_enum(:transform_keys) if NOT_GIVEN.equal?(hash) && !block_given? dup.tap { |h| h.transform_keys!(hash, &block) } end
#transform_keys!(hash = NOT_GIVEN, &block)
[ GitHub ]# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 349
def transform_keys!(hash = NOT_GIVEN, &block) return to_enum(:transform_keys!) if NOT_GIVEN.equal?(hash) && !block_given? if hash.nil? super elsif NOT_GIVEN.equal?(hash) keys.each { |key| self[yield(key)] = delete(key) } elsif block_given? keys.each { |key| self[hash[key] || yield(key)] = delete(key) } else keys.each { |key| self[hash[key] || key] = delete(key) } end self end
#transform_values(&block)
[ GitHub ]# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 337
def transform_values(&block) return to_enum(:transform_values) unless block_given? dup.tap { |hash| hash.transform_values!(&block) } end
#update(*other_hashes, &block) Also known as: #merge!
Updates the receiver in-place, merging in the hashes passed as arguments:
hash_1 = ActiveSupport::HashWithIndifferentAccess.new
hash_1[:key] = 'value'
hash_2 = ActiveSupport::HashWithIndifferentAccess.new
hash_2[:key] = 'New Value!'
hash_1.update(hash_2) # => {"key"=>"New Value!"}
hash = ActiveSupport::HashWithIndifferentAccess.new
hash.update({ "a" => 1 }, { "b" => 2 }) # => { "a" => 1, "b" => 2 }
The arguments can be either an HashWithIndifferentAccess
or a regular ::Hash
. In either case the merge respects the semantics of indifferent access.
If the argument is a regular hash with keys :key
and "key"
only one of the values end up in the receiver, but which one is unspecified.
When given a block, the value for duplicated keys will be determined by the result of invoking the block with the duplicated key, the value in the receiver, and the value in other_hash
. The rules for duplicated keys follow the semantics of indifferent access:
hash_1[:key] = 10
hash_2['key'] = 12
hash_1.update(hash_2) { |key, old, new| old + new } # => {"key"=>22}
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 132
def update(*other_hashes, &block) if other_hashes.size == 1 update_with_single_argument(other_hashes.first, block) else other_hashes.each do |other_hash| update_with_single_argument(other_hash, block) end end self end
#values_at(*keys)
Returns an array of the values at the specified indices:
hash = ActiveSupport::HashWithIndifferentAccess.new
hash[:a] = 'x'
hash[:b] = 'y'
hash.values_at('a', 'b') # => ["x", "y"]
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 237
def values_at(*keys) keys.map! { |key| convert_key(key) } super end
#with_defaults(other_hash)
Alias for #reverse_merge.
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 286
alias_method :with_defaults, :reverse_merge
#with_defaults!(other_hash)
Alias for #reverse_merge!.
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 292
alias_method :with_defaults!, :reverse_merge!
#with_indifferent_access
[ GitHub ]# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 62
def with_indifferent_access dup end
#without(*keys)
Alias for #except.
# File 'activesupport/lib/active_support/hash_with_indifferent_access.rb', line 314
alias_method :without, :except