Forum: Ruby-core [Bug #1545] Patches for the Hash Documentation

Bug #1545: Patches for the Hash Documentation
http://redmine.ruby-lang.org/issues/show/1545

Author: Run Paint Run Run
Status: Open, Priority: Normal
ruby -v: ruby 1.9.2dev (2009-05-28 trunk 23601) [i686-linux]

I've attached a couple of patches against hash.c to fix minor 
documentation typos. The 7th is an attempt to fix the verbiage regarding 
the ordering of hashes which states "The order in which you traverse a 
hash by either key or value may seem arbitrary, and will generally not 
be in the insertion order." This contradicts the doc/NEWS-1.9.1 file 
which, correctly, explains "Hash preserves order.  It enumerates its 
elements in the order in which the keys are inserted." I've tried to use 
the latter wording as much as possible in my suggested modification.

Excerpts from message of Sun May 31 06:38:54 +0300 2009:
> value may seem arbitrary, and will generally not be in the insertion order."
> This contradicts the doc/NEWS-1.9.1 file which, correctly, explains "Hash
> preserves order.  It enumerates its elements in the order in which the keys are
> inserted." I've tried to use the latter wording as much as possible in my
> suggested modification.

The wording should maybe *not* be changed? Even though I
have no doubt that everyone and their mothers will rely on
insertion order in the future, it is specified that it is
implementation-specific behaviour. (In my mind, using it
implies Hash being the wrong data structure, but that is
naturally debatable.)

Of course, if we view the RDoc as strictly applying to MRI
only, it is fine to change...a small mention of possible
unportability is OK in that case. But I am not sure if it
is feasible to make that assumption.


Eero

On Sun, May 31, 2009 at 12:10 PM, Eero Saynatkari
<ruby-ml@kittensoft.org> wrote:
[deletia]
> have no doubt that everyone and their mothers will rely on
> insertion order in the future, it is specified that it is
> implementation-specific behaviour. (In my mind, using it
> implies Hash being the wrong data structure, but that is
> naturally debatable.)

It was my impression that hashes preserving insertion order was
considered a feature, as opposed to an implementation detail, so we
probably need clarification on this point.

> Of course, if we view the RDoc as strictly applying to MRI
> only, it is fine to change...a small mention of possible
> unportability is OK in that case. But I am not sure if it
> is feasible to make that assumption.

I hadn't considered that as being an aim for the RDoc. Again, we need
clarification, I suppose.

Regardless, even if new wording is not added to describe the new
ordering, do we agree that we cannot continue to describe "the order
in which you traverse a hash" as "arbitrary" and "generally
not...in...insertion order."? :-)

Excerpts from Run Paint Run Run's message of Tue Jun 02 04:22:37 +0300 
2009:
> 
> It was my impression that hashes preserving insertion order was
> considered a feature, as opposed to an implementation detail, so we
> probably need clarification on this point.

And my distinct impression that this is an implementation
detail (although it definitely will not be so de facto.)
The NEWS file does not mention either direction. I will
search the list archives unless someone chimes in before
that.

> Regardless, even if new wording is not added to describe the new
> ordering, do we agree that we cannot continue to describe "the order
> in which you traverse a hash" as "arbitrary" and "generally
> not...in...insertion order."? :-)

If the traversal order is an implementation detail, then it
must remain something to that effect, if certainly not that
exact phrasing.


Eero

Issue #1545 has been updated by Run Paint Run Run.


> And my distinct impression that this is an implementation
> detail (although it definitely will not be so de facto.)
> The NEWS file does not mention either direction. I will
> search the list archives unless someone chimes in before
> that.

In [ruby-core:21856] matz wrote "Although I now recognize the ordered 
hash as 1.9 spec, I still
hesitate to add sorting method that returns "sorted" hash to the Hash 
class." Is this sufficient?

Could we at least get the typo patches applied?
----------------------------------------
http://redmine.ruby-lang.org/issues/show/1545