Bug #6680
closedUnclear rdoc for Array and String slicing
Description
=begin
Slicing of arrays and strings specifying start/length or using a range is not documented well, and often leads to confusion, see for example
or
http://www.ruby-forum.com/topic/1393096#990065
The attached patch tries to clarify the documentation.
=end
Files
Updated by drbrain (Eric Hodel) over 12 years ago
- Assignee set to drbrain (Eric Hodel)
- Target version set to 2.0.0
- Category set to doc
Updated by drbrain (Eric Hodel) over 12 years ago
- Status changed from Open to Closed
- % Done changed from 0 to 100
This issue was solved with changeset r36298.
Marcus, thank you for reporting this issue.
Your contribution to Ruby is greatly appreciated.
May Ruby be with you.
- array.c (rb_ary_aref): Updated documentation to indicate the
starting index is an index into the array or string. Updated
examples to show behavior of indexes at the end of an array or
string. Based on patch by Marcus Stollsteimer. [Bug #6680] - array.c (rb_ary_aset): ditto.
- string.c (rb_str_aref): ditto. Also added descriptive argument
names to call-seq section.
Updated by drbrain (Eric Hodel) over 12 years ago
I chose to indicate that the start offset is an index instead of your text, but I kept your examples since the behavior isn't documented.
Updated by stomar (Marcus Stollsteimer) over 12 years ago
- File rdoc_for_array_and_string_slice_2_v1.patch rdoc_for_array_and_string_slice_2_v1.patch added
- File rdoc_for_array_and_string_slice_2_v2.patch rdoc_for_array_and_string_slice_2_v2.patch added
Hi Eric,
thank you, there are definitely some improvements here.
But: in my opinion the documentation is still unsatisfactory.
Having the examples surely helps in making clear that the
behavior is desired, but there is still no explanation.
The discussions I linked to in the original bug report
show that people are puzzled by the seemingly illogical
behavior, specifically that the same index value sometimes
does lie in the valid range and sometimes does not:
a = [1, 2, 3, 4]
a[4] #=> nil
a[4, 1] #=> [] (why?!)
Providing a consistent explanation really would help.
I attached two alternative suggestions for consideration.
Regards,
Marcus
Updated by stomar (Marcus Stollsteimer) over 12 years ago
- File typo_in_rdoc_for_array_and_string_slice.patch typo_in_rdoc_for_array_and_string_slice.patch added
Hi Eric,
there is a typo in the new examples, see new patch:
in the "special cases", a[6] (which is already given as example a couple
of lines above) should be a[6, 1], to show the difference between
a[a.size, length], which is a valid range, and a[a.size + 1, length],
which is not in valid range.
Updated by drbrain (Eric Hodel) over 12 years ago
- Status changed from Closed to Assigned
Updated by drbrain (Eric Hodel) over 12 years ago
- Status changed from Assigned to Closed
This issue was solved with changeset r36328.
Marcus, thank you for reporting this issue.
Your contribution to Ruby is greatly appreciated.
May Ruby be with you.
- array.c (rb_ary_aref): Added a description of the behavior of
index positioning. [Bug #6680] - array.c (rb_ary_aset): ditto. Reordered sentences for clarity.
- string.c (rb_str_aref_m): Added a description of the behavior of
index positioning
Updated by drbrain (Eric Hodel) over 12 years ago
I incorporated the ideas of your two patches which seem to help clarify things. Let me know if this latest patch needs further adjustment.