Bug #6680

Unclear rdoc for Array and String slicing

Added by Marcus Stollsteimer about 2 years ago. Updated about 2 years ago.

[ruby-core:46026]
Status:Closed
Priority:Normal
Assignee:Eric Hodel
Category:doc
Target version:2.0.0
ruby -v:ruby 1.9.3p243 (2012-06-28 revision 36244) [i686-linux] Backport:

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

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

rdoc_for_array_and_string_slice.patch Magnifier (2.83 KB) Marcus Stollsteimer, 07/01/2012 07:27 AM

rdoc_for_array_and_string_slice_2_v1.patch Magnifier (2.02 KB) Marcus Stollsteimer, 07/04/2012 09:38 PM

rdoc_for_array_and_string_slice_2_v2.patch Magnifier (2.02 KB) Marcus Stollsteimer, 07/04/2012 09:38 PM

typo_in_rdoc_for_array_and_string_slice.patch Magnifier (435 Bytes) Marcus Stollsteimer, 07/04/2012 11:51 PM

Associated revisions

Revision 36298
Added by Eric Hodel about 2 years ago

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

Revision 36328
Added by Eric Hodel about 2 years ago

  • 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

History

#1 Updated by Eric Hodel about 2 years ago

  • Assignee set to Eric Hodel
  • Target version set to 2.0.0
  • Category set to doc

#2 Updated by Eric Hodel about 2 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.

#3 Updated by Eric Hodel about 2 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.

#4 Updated by Marcus Stollsteimer about 2 years ago

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] #=>

Providing a consistent explanation really would help.

I attached two alternative suggestions for consideration.

Regards,
Marcus

#5 Updated by Marcus Stollsteimer about 2 years ago

Hi Eric,

there is a typo in the new examples, see new patch:

in the "special cases", a6 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.

#6 Updated by Eric Hodel about 2 years ago

  • Status changed from Closed to Assigned

#7 Updated by Eric Hodel about 2 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

#8 Updated by Eric Hodel about 2 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.

Also available in: Atom PDF