Bug #1385: Wonderful undocumented feature in Ruby 1.8.7 & 1.9

• Status: Closed
• Assignee: yugui (Yuki Sonoda)
• Target version: -
• ruby -v: ruby 1.9.1p0 (2009-01-30 revision 21907) [i386-darwin9.6.0]

[marcandre (Marc-Andre Lafortune)]

=begin
6 months ago, I begged for a natural way to construct a Hash from key-value pairs: http://redmine.ruby-lang.org/issues/show/666
Maybe because of a lack of superstitious devil worshippers, there was no additional comment on this issue # 666, which seems even stranger after a discovery I made by pure random luck (hey, my last name is not Lafortune for nothing!). It appears there already is a way, using Hash::[]

Example:
Hash[[[:i_like, :ruby], [:hello, "world!"], [:answer, 42]]]
=> {:i_like => :ruby, :hello => "world!", :answer => 42}

Wouhou, exciting! This works in both Ruby 1.8.7 and 1.9.1, but it is not documented anywhere where it should:
http://www.ruby-doc.org/core-1.9/classes/Hash.html#M002653
http://www.ruby-doc.org/core-1.8.7/classes/Hash.html#M000148
http://svn.ruby-lang.org/repos/ruby/tags/v1_8_7/NEWS
http://eigenclass.org/hiki/Changes+in+Ruby+1.9
The Ruby Programming Language (section 9.5.3.1)

At first I thought maybe my satanic incantations were to thank for this hidden feature, but the huge 1.9 changelog reads:

Fri Oct 26 01:48:28 2007 Yukihiro Matsumoto [e-mail]

* hash.c (rb_hash_s_create): Hash#[] now takes assocs as source of
  hash conversion.

So, thank you Matz!

I'm thus filing a bug report for the missing documentation, praying that the reason it is not documented is a simple oversight and that we can officially count on this for the future. In any case I eagerly included this cool feature in my backports for 1.8.x (http://github.com/marcandre/backports ) since I still don't get the point of 1.8.7 (http://blog.marc-andre.ca/2009/04/whats-point-of-ruby-187.html ) and I'll use Hash::[] until we get (one day maybe) my dreamed Enumerable#to_hash which I still favor.

I'd propose an updated doc similar to the following:

/*

• call-seq:

• Hash[ key, value, ... ]   => hash
  

• Hash[ [ [key, value], ... ] ]   => hash
  

• Hash[ object ]   => hash
  

• Creates a new hash populated with the given objects. Equivalent to
• the literal { key => value, ... }. In the first
• form, keys and values occur in pairs, so there must be an even number of arguments.
• The second and third form take a single argument which is either
• an array of key-value pairs or an object convertible to a hash.

• Hash["a", 100, "b", 200]                 #=> {"a"=>100, "b"=>200}
  

• Hash[ [ ["a" => 100], ["b" => 200] ] ]   #=> {"a"=>100, "b"=>200}
  

• Hash["a" => 100, "b" => 200]             #=> {"a"=>100, "b"=>200}
  

• {"a" => 100, "b" => 200}                 #=> {"a"=>100, "b"=>200}
  

*/

Is it just me or is the last example not quite insightful? In any case, if a different text than mine is used, note that the present version still mentions the old 1.8 syntax: { key, value, ... }

Is there a prize for the most long-winded bug report just for the documentation? To be a sure winner, I'll add that I find interesting that my infamous feature request # 666 would make the second form merge naturally into the third, since an array of key-value pairs would be convertible to a hash!

Thank you for your attention,

Marc-André Lafortune
=end

[marcandre (Marc-Andre Lafortune)]

=begin
As pointed out by Joel VanderWerf, my second usage example is wrong (it takes commas instead of =>). It should read:

/*

• call-seq:

• Hash[ key, value, ... ]   => hash
  

• Hash[ [ [key, value], ... ] ]   => hash
  

• Hash[ object ]   => hash
  

• Creates a new hash populated with the given objects. Equivalent to
• the literal { key => value, ... }. In the first
• form, keys and values occur in pairs, so there must be an even number of arguments.
• The second and third form take a single argument which is either
• an array of key-value pairs or an object convertible to a hash.

• Hash["a", 100, "b", 200]             #=> {"a"=>100, "b"=>200}
  

• Hash[ [ ["a", 100], ["b", 200] ] ]   #=> {"a"=>100, "b"=>200}
  

• Hash["a" => 100, "b" => 200]         #=> {"a"=>100, "b"=>200}
  

• {"a" => 100, "b" => 200}             #=> {"a"=>100, "b"=>200}
  

*/

Sorry!

=end

[marcandre (Marc-Andre Lafortune)]

=begin
This feature has been confirmed by Matz in ruby-core #23433, so this ticket can be closed after the change to the documentation has been applied. Thanks!
=end

[marcandre (Marc-Andre Lafortune)]

• File doc_hash.patch doc_hash.patch added

=begin
The included patch completes the documentation for Hash.[], including the form Hash[[[:a,1],[:b,2]]]
=end

[yugui (Yuki Sonoda)]

• Assignee set to yugui (Yuki Sonoda)

=begin

=end

[yugui (Yuki Sonoda)]

• Status changed from Open to Closed
• % Done changed from 0 to 100

=begin
Applied in changeset r24236.
=end