ÿØÿà JFIF ÿÛ „ ( %!1!%*+... 983,7(-.-
U:RDoc::NormalClass[iI" Hash:ET@I" Object;To:RDoc::Markup::Document: @parts[o;;[Öo: RDoc::Markup::Paragraph;[I">A \Hash maps each of its unique keys to a specific value.;To: RDoc::Markup::BlankLine o; ;[I"8A \Hash has certain similarities to an \Array, but:;To:RDoc::Markup::List:
@type: BULLET: @items[o:RDoc::Markup::ListItem: @label0;[o; ;[I"+An \Array index is always an \Integer.;To;;0;[o; ;[I",A \Hash key can be (almost) any object.;T@S:RDoc::Markup::Heading:
leveli: textI"\Hash \Data Syntax;T@o; ;[I"IThe older syntax for \Hash data uses the "hash rocket," =>:;T@o:RDoc::Markup::Verbatim;[I"+h = {:foo => 0, :bar => 1, :baz => 2}
;TI"(h # => {:foo=>0, :bar=>1, :baz=>2}
;T: @format0o; ;[I"?Alternatively, but only for a \Hash key that's a \Symbol, ;TI",you can use a newer JSON-style syntax, ;TI"+where each bareword becomes a \Symbol:;T@o;;[I""h = {foo: 0, bar: 1, baz: 2}
;TI"(h # => {:foo=>0, :bar=>1, :baz=>2}
;T;0o; ;[I"7You can also use a \String in place of a bareword:;T@o;;[I"(h = {'foo': 0, 'bar': 1, 'baz': 2}
;TI"(h # => {:foo=>0, :bar=>1, :baz=>2}
;T;0o; ;[I" And you can mix the styles:;T@o;;[I"'h = {foo: 0, :bar => 1, 'baz': 2}
;TI"(h # => {:foo=>0, :bar=>1, :baz=>2}
;T;0o; ;[I"4But it's an error to try the JSON-style syntax ;TI"1for a key that's not a bareword or a String:;T@o;;[I"H# Raises SyntaxError (syntax error, unexpected ':', expecting =>):
;TI"h = {0: 'zero'}
;T;0o; ;[I"THash value can be omitted, meaning that value will be fetched from the context ;TI" by the name of the key:;T@o;;[ I" x = 0
;TI"
y = 100
;TI"h = {x:, y:}
;TI" h # => {:x=>0, :y=>100}
;T;0S;;i;I"Common Uses;T@o; ;[I"2You can use a \Hash to give names to objects:;T@o;;[I"/person = {name: 'Matz', language: 'Ruby'}
;TI"4person # => {:name=>"Matz", :language=>"Ruby"}
;T;0o; ;[I";You can use a \Hash to give names to method arguments:;T@o;;[ I"def some_method(hash)
;TI" p hash
;TI" end
;TI"Lsome_method({foo: 0, bar: 1, baz: 2}) # => {:foo=>0, :bar=>1, :baz=>2}
;T;0o; ;[I"?Note: when the last argument in a method call is a \Hash, ;TI"%the curly braces may be omitted:;T@o;;[I"Jsome_method(foo: 0, bar: 1, baz: 2) # => {:foo=>0, :bar=>1, :baz=>2}
;T;0o; ;[I"1You can use a \Hash to initialize an object:;T@o;;[I"class Dev
;TI"& attr_accessor :name, :language
;TI" def initialize(hash)
;TI"! self.name = hash[:name]
;TI") self.language = hash[:language]
;TI" end
;TI" end
;TI"4matz = Dev.new(name: 'Matz', language: 'Ruby')
;TI"6matz # => #
;T;0S;;i;I"Creating a \Hash;T@o; ;[I"3You can create a \Hash object explicitly with:;T@o; ; ;
;[o;;0;[o; ;[I"IA {hash literal}[doc/syntax/literals_rdoc.html#label-Hash+Literals].;T@o; ;[I"4You can convert certain objects to Hashes with:;T@o; ; ;
;[o;;0;[o; ;[I"/\Method {Hash}[Kernel.html#method-i-Hash].;T@o; ;[I"7You can create a \Hash by calling method Hash.new.;T@o; ;[I"Create an empty Hash:;T@o;;[I"h = Hash.new
;TI"h # => {}
;TI"h.class # => Hash
;T;0o; ;[I"6You can create a \Hash by calling method Hash.[].;T@o; ;[I"Create an empty Hash:;T@o;;[I"h = Hash[]
;TI"h # => {}
;T;0o; ;[I")Create a \Hash with initial entries:;T@o;;[I"&h = Hash[foo: 0, bar: 1, baz: 2]
;TI"(h # => {:foo=>0, :bar=>1, :baz=>2}
;T;0o; ;[I"EYou can create a \Hash by using its literal form (curly braces).;T@o; ;[I"Create an empty \Hash:;T@o;;[I" h = {}
;TI"h # => {}
;T;0o; ;[I")Create a \Hash with initial entries:;T@o;;[I""h = {foo: 0, bar: 1, baz: 2}
;TI"(h # => {:foo=>0, :bar=>1, :baz=>2}
;T;0S;;i;I"\Hash Value Basics;T@o; ;[I"FThe simplest way to retrieve a \Hash value (instance method #[]):;T@o;;[I""h = {foo: 0, bar: 1, baz: 2}
;TI"h[:foo] # => 0
;T;0o; ;[I"OThe simplest way to create or update a \Hash value (instance method #[]=):;T@o;;[
I""h = {foo: 0, bar: 1, baz: 2}
;TI"h[:bat] = 3 # => 3
;TI"1h # => {:foo=>0, :bar=>1, :baz=>2, :bat=>3}
;TI"h[:foo] = 4 # => 4
;TI"1h # => {:foo=>4, :bar=>1, :baz=>2, :bat=>3}
;T;0o; ;[I"HThe simplest way to delete a \Hash entry (instance method #delete):;T@o;;[I""h = {foo: 0, bar: 1, baz: 2}
;TI"h.delete(:bar) # => 1
;TI" h # => {:foo=>0, :baz=>2}
;T;0S;;i;I"Entry Order;T@o; ;[I"YA \Hash object presents its entries in the order of their creation. This is seen in:;T@o; ; ;
;[o;;0;[o; ;[I"iIterative methods such as each, each_key, each_pair, each_value.;To;;0;[o; ;[I"ZOther order-sensitive methods such as shift, keys, values.;To;;0;[o; ;[I"5The \String returned by method inspect.;T@o; ;[I"@A new \Hash has its initial ordering per the given entries:;T@o;;[I" h = Hash[foo: 0, bar: 1]
;TI" h # => {:foo=>0, :bar=>1}
;T;0o; ;[I"&New entries are added at the end:;T@o;;[I"h[:baz] = 2
;TI"(h # => {:foo=>0, :bar=>1, :baz=>2}
;T;0o; ;[I"0Updating a value does not affect the order:;T@o;;[I"h[:baz] = 3
;TI"(h # => {:foo=>0, :bar=>1, :baz=>3}
;T;0o; ;[I":But re-creating a deleted entry can affect the order:;T@o;;[I"h.delete(:foo)
;TI"h[:foo] = 5
;TI"(h # => {:bar=>1, :baz=>3, :foo=>5}
;T;0S;;i;I"\Hash Keys;T@S;;i ;I"\Hash Key Equivalence;T@o; ;[I"VTwo objects are treated as the same \hash key when their hash value ;TI"Jis identical and the two objects are eql? to each other.;T@S;;i ;I""Modifying an Active \Hash Key;T@o; ;[I"GModifying a \Hash key while it is in use damages the hash's index.;T@o; ;[I")This \Hash has keys that are Arrays:;T@o;;[ I"a0 = [ :foo, :bar ]
;TI"a1 = [ :baz, :bat ]
;TI" h = {a0 => 0, a1 => 1}
;TI" h.include?(a0) # => true
;TI"h[a0] # => 0
;TI" a0.hash # => 110002110
;T;0o; ;[I"CModifying array element a0[0] changes its hash value:;T@o;;[I"a0[0] = :bam
;TI" a0.hash # => 1069447059
;T;0o; ;[I"!And damages the \Hash index:;T@o;;[I" h.include?(a0) # => false
;TI"h[a0] # => nil
;T;0o; ;[I"9You can repair the hash index using method +rehash+:;T@o;;[I"6h.rehash # => {[:bam, :bar]=>0, [:baz, :bat]=>1}
;TI" h.include?(a0) # => true
;TI"h[a0] # => 0
;T;0o; ;[I"#A \String key is always safe. ;TI"(That's because an unfrozen \String ;TI"Ipassed as a key will be replaced by a duplicated and frozen \String:;T@o;;[
I"s = 'foo'
;TI"s.frozen? # => false
;TI"h = {s => 0}
;TI" first_key = h.keys.first
;TI"!first_key.frozen? # => true
;T;0S;;i ;I" User-Defined \Hash Keys;T@o; ;[I"oTo be useable as a \Hash key, objects must implement the methods hash and eql?. ;TI"mNote: this requirement does not apply if the \Hash uses #compare_by_identity since comparison will then ;TI"Trely on the keys' object id instead of hash and eql?.;T@o; ;[I"l\Object defines basic implementation for hash and eq? that makes each object ;TI"oa distinct key. Typically, user-defined classes will want to override these methods to provide meaningful ;TI"Tbehavior, or for example inherit \Struct that has useful definitions for these.;T@o; ;[I"CA typical implementation of hash is based on the ;TI"Pobject's data while eql? is usually aliased to the overridden ;TI" == method:;T@o;;[#I"class Book
;TI"# attr_reader :author, :title
;TI"
;TI"% def initialize(author, title)
;TI" @author = author
;TI" @title = title
;TI" end
;TI"
;TI" def ==(other)
;TI"! self.class === other &&
;TI"& other.author == @author &&
;TI"! other.title == @title
;TI" end
;TI"
;TI" alias eql? ==
;TI"
;TI" def hash
;TI"* @author.hash ^ @title.hash # XOR
;TI" end
;TI" end
;TI"
;TI"3book1 = Book.new 'matz', 'Ruby in a Nutshell'
;TI"3book2 = Book.new 'matz', 'Ruby in a Nutshell'
;TI"
;TI"reviews = {}
;TI"
;TI")reviews[book1] = 'Great reference!'
;TI"*reviews[book2] = 'Nice and compact!'
;TI"
;TI"reviews.length #=> 1
;T;0S;;i;I"Default Values;T@o; ;[I"`The methods #[], #values_at and #dig need to return the value associated to a certain key. ;TI"\When that key is not found, that value will be determined by its default proc (if any) ;TI"+or else its default (initially `nil`).;T@o; ;[I"=You can retrieve the default value with method #default:;T@o;;[I"h = Hash.new
;TI"h.default # => nil
;T;0o; ;[I"PYou can set the default value by passing an argument to method Hash.new or ;TI"with method #default=;T@o;;[ I"h = Hash.new(-1)
;TI"h.default # => -1
;TI"h.default = 0
;TI"h.default # => 0
;T;0o; ;[I"OThis default value is returned for #[], #values_at and #dig when a key is ;TI"not found:;T@o;;[
I"counts = {foo: 42}
;TI"'counts.default # => nil (default)
;TI"counts[:foo] = 42
;TI"counts[:bar] # => nil
;TI"counts.default = 0
;TI"counts[:bar] # => 0
;TI"8counts.values_at(:foo, :bar, :baz) # => [42, 0, 0]
;TI" counts.dig(:bar) # => 0
;T;0o; ;[I"\Note that the default value is used without being duplicated. It is not advised to set ;TI"+the default value to a mutable object:;T@o;;[ I" synonyms = Hash.new([])
;TI" synonyms[:hello] # => []
;TI"Gsynonyms[:hello] << :hi # => [:hi], but this mutates the default!
;TI"!synonyms.default # => [:hi]
;TI"#synonyms[:world] << :universe
;TI"2synonyms[:world] # => [:hi, :universe], oops
;TI"!synonyms.keys # => [], oops
;T;0o; ;[I"PTo use a mutable object as default, it is recommended to use a default proc;T@S;;i ;I"Default \Proc;T@o; ;[I"AWhen the default proc for a \Hash is set (i.e., not +nil+), ;TI"Vthe default value returned by method #[] is determined by the default proc alone.;T@o; ;[I"AYou can retrieve the default proc with method #default_proc:;T@o;;[I"h = Hash.new
;TI" h.default_proc # => nil
;T;0o; ;[I"FYou can set the default proc by calling Hash.new with a block or ;TI"&calling the method #default_proc=;T@o;;[ I"=h = Hash.new { |hash, key| "Default value for #{key}" }
;TI"$h.default_proc.class # => Proc
;TI"Nh.default_proc = proc { |hash, key| "Default value for #{key.inspect}" }
;TI"$h.default_proc.class # => Proc
;T;0o; ;[ I"4When the default proc is set (i.e., not +nil+) ;TI" "Default value for nosuch"
;T;0o; ;[I"JNote that in the example above no entry for key +:nosuch+ is created:;T@o;;[I"$h.include?(:nosuch) # => false
;T;0o; ;[I"2However, the proc itself can add a new entry:;T@o;;[
I"8synonyms = Hash.new { |hash, key| hash[key] = [] }
;TI"*synonyms.include?(:hello) # => false
;TI"(synonyms[:hello] << :hi # => [:hi]
;TI"4synonyms[:world] << :universe # => [:universe]
;TI")synonyms.keys # => [:hello, :world]
;T;0o; ;[I"TNote that setting the default proc will clear the default value and vice versa.;T@S;;i;I"What's Here;T@o; ;[I"+First, what's elsewhere. \Class \Hash:;T@o; ; ;
;[o;;0;[o; ;[I"PInherits from {class Object}[Object.html#class-Object-label-What-27s+Here].;To;;0;[o; ;[I"ZIncludes {module Enumerable}[Enumerable.html#module-Enumerable-label-What-27s+Here], ;TI"1which provides dozens of additional methods.;T@o; ;[I"}[#method-i-3E];T;[o; ;[I"BReturns whether +self+ is a proper superset of a given object;To;;[I"{#>=}[#method-i-3E-3D];T;[o; ;[I"CReturns whether +self+ is a proper superset of a given object.;T@S;;i ;I"Methods for Fetching;T@o; ; ;;[o;;[I"#[];T;[o; ;[I"3Returns the value associated with a given key.;To;;[I" #assoc;T;[o; ;[I"DReturns a 2-element array containing a given key and its value.;To;;[I" #dig;T;[o; ;[I";T@+[I">=;T@+[I"[];T@+[I"[]=;T@+[I" any?;T@+[I"
assoc;T@+[I"
clear;T@+[I" compact;T@+[I"
compact!;T@+[I"compare_by_identity;T@+[I"compare_by_identity?;T@+[I"deconstruct_keys;T@+[I" default;T@+[I"
default=;T@+[I"default_proc;T@+[I"default_proc=;T@+[I" delete;T@+[I"delete_if;T@+[I"dig;T@+[I" each;T@+[I"
each_key;T@+[I"each_pair;T@+[I"each_value;T@+[I" empty?;T@+[I" eql?;T@+[I" except;T@+[I"
fetch;T@+[I"fetch_values;T@+[I" filter;T@+[I" filter!;T@+[I" flatten;T@+[I"
has_key?;T@+[I"has_value?;T@+[I" hash;T@+[I"
include?;T@+[I"initialize_copy;T@+[I" inspect;T@+[I" invert;T@+[I" keep_if;T@+[I"key;T@+[I" key?;T@+[I" keys;T@+[I" length;T@+[I" member?;T@+[I"
merge;T@+[I" merge!;T@+[I" rassoc;T@+[I" rehash;T@+[I" reject;T@+[I" reject!;T@+[I" replace;T@+[I" select;T@+[I" select!;T@+[I"
shift;T@+[I" size;T@+[I"
slice;T@+[I"
store;T@+[I" to_a;T@+[I" to_h;T@+[I" to_hash;T@+[I" to_proc;T@+[I" to_s;T@+[I"transform_keys;T@+[I"transform_keys!;T@+[I"transform_values;T@+[I"transform_values!;T@+[I" update;T@+[I" value?;T@+[I" values;T@+[I"values_at;T@+[ [U:RDoc::Context::Section[i 0o;;[ ;0;0[I" hash.c;TI"lib/pp.rb;TI"lib/pp.rb;TcRDoc::TopLevel