Bug #1545: Patches for the Hash Documentation

• Status: Closed
• Assignee: -

[runpaint (Run Paint Run Run)]

=begin
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.
=end

[rue (Eero Saynatkari)]

=begin
Excerpts from message of Sun May 31 06:38:54 +0300 2009:

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.

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

--
Magic is insufficiently advanced technology.

=end

[runpaint (Run Paint Run Run)]

=begin
On Sun, May 31, 2009 at 12:10 PM, Eero Saynatkari
[e-mail] wrote:
[deletia]

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.

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.)

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."? :-)

--
Run Paint Run Run

=end

[rue (Eero Saynatkari)]

=begin
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

Magic is insufficiently advanced technology.

=end

[runpaint (Run Paint Run Run)]

=begin

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?
=end

[marcandre (Marc-Andre Lafortune)]

• Status changed from Open to Closed

=begin
Applied in changeset r25081.
=end