Project

General

Profile

Actions

Bug #6680

closed

Unclear rdoc for Array and String slicing

Added by stomar (Marcus Stollsteimer) over 12 years ago. Updated over 12 years ago.

Status:
Closed
Target version:
ruby -v:
ruby 1.9.3p243 (2012-06-28 revision 36244) [i686-linux]
Backport:
[ruby-core:46026]

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


Files

rdoc_for_array_and_string_slice.patch (2.83 KB) rdoc_for_array_and_string_slice.patch stomar (Marcus Stollsteimer), 07/01/2012 07:27 AM
rdoc_for_array_and_string_slice_2_v1.patch (2.02 KB) rdoc_for_array_and_string_slice_2_v1.patch stomar (Marcus Stollsteimer), 07/04/2012 09:38 PM
rdoc_for_array_and_string_slice_2_v2.patch (2.02 KB) rdoc_for_array_and_string_slice_2_v2.patch stomar (Marcus Stollsteimer), 07/04/2012 09:38 PM
typo_in_rdoc_for_array_and_string_slice.patch (435 Bytes) typo_in_rdoc_for_array_and_string_slice.patch stomar (Marcus Stollsteimer), 07/04/2012 11:51 PM

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
Actions #2

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

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

Actions #5

Updated by stomar (Marcus Stollsteimer) over 12 years ago

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
Actions #7

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.

Actions

Also available in: Atom PDF

Like0
Like0Like0Like0Like0Like0Like0Like0Like0