[ruby-core:23225] [Bug #1385] Wonderful undocumented feature in Ruby 1.8.7 & 1.9

Bug #1385: Wonderful undocumented feature in Ruby 1.8.7 & 1.9
http://redmine.ruby-lang.org/issues/show/1385

Author: Marc-Andre Lafortune
Status: Open, Priority: Normal
ruby -v: ruby 1.9.1p0 (2009-01-30 revision 21907) [i386-darwin9.6.0]

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 <code>{ <i>key</i> => <i>value</i>, ... }</code>. 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: <code>{ <i>key</i>, <i>value</i>, ... }</code>

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


----------------------------------------
http://redmine.ruby-lang.org