From: mrilu <mrilu@...>
Date: 2000-04-11T00:39:50+02:00
Subject: [ruby-talk:02429] Please join me, I'm Hashing documentation

This is a story about my hashing ventures, try to bear with me.

delete is good name. 
delete_if is another one. And it's marvellous that there is reject! too. 
I would like to see it to be symmetrical, so there's space for 
plain reject. And it should be clearly said it's different from delete_if.

I wanted to patch, make the source better, but this time there was no 
need for complex code enhancement. 1.5.newest contains already plain 
reject. So I'm glad to see documentation to be updated to source level :=).

Then I recognized it. There is need for collaborative work to make the 
documentation up to date.

I'm sure there'll be discussion how we can join our forces for better 
world(tm), but I wanted to act in hurry. So I list all the routines declared
in hash.c's Init_hash() which are not mentioned in the docs.

One more note before details of hash. We need a clear guideline for 
forecoming Ruby versions and standard coding when to name routine, routine!, 
routine? or routine=. (Maybe this is already in the FAQ ?).

I mark my <enhancements or questions like this>. Please feel free to 
correct my (buggy, as they say well in Japan:) english.

clone
  <I still don't know the differences between dup and clone, so I guess>.
dup
  dup is differs from clone by tainting the copy it makes (if the original
  was tainted).
rehash
  Recalculates hash code for each key.
  Note: copies old hash one key by one to new, so needs twice as much
  memory.
  <already explained examples here, discussed earlier at the ruby-talk>
to_hash
  <No idea whatsoever.>
to_s
  Same as hash.to_a.to_s
inspect
  returns string "{"+key.inspect+"=>"+value.inspect+key...+"}"

==
  Returns true if for every key in hash1 hash1[key] == hash2[key].
  <is this broken, should it be 'for every key in hash1 and hash2...'?>

store
  same as []=. Store adds a key,value-pair or updates old one.

sort
  same as hash.to_a.sort!.
  Btw. it should be obvious that there's no need for sort!
  but now it's said.

reject
  same as hash.dup.delete_if

=======

Other topics:

Actually there's almost always need for method and method!. And of these two the method! is more important. Method could always be emulated easily hash.dup.method!.

Need for invert!.

Should update be !-method? Anyway there's need for nondestructive update 
which is still mutable. (Maybe it should be named join).
def Hash.join(hash2)
  hash2.keys{|k| hash[k]=hash2[k] unless hash.has_key?(k) }
end

default
   <should it be default?>

From the docs it's not clear what's the difference of replace and update.
I guess replace is hash.clear.update(other_hash). (Added later: 
glance to the code confirmed my guess, so no surprise here :).

There's two Hash.shift routines in the docs, I don't see the other on 
the sources.

=====

Environment hash has following methods
apparently with the same functionality as hash methods:

[]
[]=
each
each_pair
each_key
each_value
delete
delete_if
reject!
reject
to_s
rehash
to_a
index
indexes
indices
size
length
empty?
keys
values
include?
member?
has_key?
has_value?
key?
value?
to_hash


Environment hash don't have the following methods of the hash:
new
[]-creation
initialize
clone
dup
inspect
==
fetch
store
default
default=
sort
shift
clear
invert
update
replace