Bug #6680: Unclear rdoc for Array and String slicing

• Status: Closed
• Assignee: drbrain (Eric Hodel)
• Target version: 2.0.0
• ruby -v: ruby 1.9.3p243 (2012-06-28 revision 36244) [i686-linux]

[stomar (Marcus Stollsteimer)]

=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

http://stackoverflow.com/questions/3568222/array-slicing-in-ruby-looking-for-explanation-for-illogical-behaviour-taken-fr

or

http://www.ruby-forum.com/topic/1393096#990065

The attached patch tries to clarify the documentation.
=end

[drbrain (Eric Hodel)]

• Assignee set to drbrain (Eric Hodel)
• Target version set to 2.0.0
• Category set to doc

[drbrain (Eric Hodel)]

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

[drbrain (Eric Hodel)]

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.

[stomar (Marcus Stollsteimer)]

• 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

[stomar (Marcus Stollsteimer)]

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

[drbrain (Eric Hodel)]

• Status changed from Closed to Assigned

[drbrain (Eric Hodel)]

• 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

[drbrain (Eric Hodel)]

I incorporated the ideas of your two patches which seem to help clarify things. Let me know if this latest patch needs further adjustment.