A tip about using Hash - and a documentation request

P

Per Velschow

I just spent several hours of investigating a problem that I had when
using instances of my own class as keys in a Hash. If you, like me, have
experience with this from a language like Java, you know that you have
to override both the hash method and the equality operator/method. What
took me by surprise was that Hash does NOT use the == operator when
comparing keys. Instead, it uses the eql? method. Thus, it is the eql?
method you have to define for your classes.

The above is actually documented in the Ruby core docs - but not in the
most obvious place in my opinion. It is mentioned only in the
Object.hash documentation. I never considered looking there for the
answer - I only looked at the docs for Hash and it makes no mention of
this fact. This may be my fault. But in my opinion this behavior is a
feature of the Hash class first and foremost. As such it is rather
important to document it in the Hash class.

/Per

P.S. One reason it took me so long to figure out is that Googling for
words like "hash", "key", etc. is not very specific and gives way too
many unrelated results. :)
 
E

Eric Hodel

The above is actually documented in the Ruby core docs - but not in
the
most obvious place in my opinion. It is mentioned only in the
Object.hash documentation. I never considered looking there for the
answer - I only looked at the docs for Hash and it makes no mention of
this fact. This may be my fault. But in my opinion this behavior is a
feature of the Hash class first and foremost. As such it is rather
important to document it in the Hash class.

Please provide a patch to the ruby-doc mailing list, or to ruby-core
and I'll commit it. You'll find the RDoc for Hash in hash.c in a
ruby tarball (or SVN), right above Init_Hash. It'll be easiest to
apply from trunk or ruby_1_8.

(e-mail address removed)

(e-mail address removed)
 
P

Per Velschow

I've never made a patch before, so I decided to follow the instructions
given at http://www.ruby-lang.org/en/community/ruby-core/ (up until
point 3). So I have a patch file now and I have run make and make test
with success. I had little success trying to install the docs using make
install-doc though. It creates yaml files only that I don't know what to
do with.

So how do you want me to proceed? I have the patch file. I could login
and submit it to the tracker as explained in the instructions from
above. Or do you want me to sign up to one of the mailing lists you
mentioned and post it there?
 
E

Eric Hodel

I've never made a patch before, so I decided to follow the
instructions
given at http://www.ruby-lang.org/en/community/ruby-core/ (up until
point 3). So I have a patch file now and I have run make and make test
with success. I had little success trying to install the docs using
make
install-doc though. It creates yaml files only that I don't know
what to
do with.

After installing the documentation you should be able to

ri Hash

and see your new documentation.

You should also be able to run:

rdoc --op rdoc hash.c

then open rdoc/index.html in your browser to find your RDoc.
So how do you want me to proceed? I have the patch file. I could login
and submit it to the tracker as explained in the instructions from
above. Or do you want me to sign up to one of the mailing lists you
mentioned and post it there?

Tracker works great too. Assign it to me, if the tracker allows you
to. It may be a while before I get around to committing it.

Thanks!
 
R

Ryan Davis

I've never made a patch before, so I decided to follow the
instructions
given at http://www.ruby-lang.org/en/community/ruby-core/ (up until
point 3). So I have a patch file now and I have run make and make test
with success. I had little success trying to install the docs using
make
install-doc though. It creates yaml files only that I don't know
what to
do with.

For the record... You RULE.
 
P

Per Velschow

OK, I submitted it to the tracker. It was not possible for me to assign
it. I made a note of it in the description instead.
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

Forum statistics

Threads
473,744
Messages
2,569,483
Members
44,901
Latest member
Noble71S45

Latest Threads

Top