Document usage of ArithmeticSequence in Array#slice, and add to NEWS (#3952)

1 files changed, 16 insertions, 5 deletions

diff --git a/array.c b/array.c
index f4c3e27af7..ea84473fdf 100644
--- a/array.c
+++ b/array.c
@@ -1775,11 +1775,22 @@ static VALUE rb_ary_aref2(VALUE ary, VALUE b, VALUE e);
  *    a[4..0] # => nil
  *    a[4..-1] # => nil
  *
- *  When a single argument +aseq+ is given,
- *  ...(to be described)
- *
- *  Raises an exception if given a single argument
- *  that is not an \Integer-convertible object or a \Range object:
+ *  When a single Enumerator::ArithmeticSequence argument +aseq+ is given,
+ *  returns an Array of elements corresponding to the indexes produced by
+ *  the sequence.
+ *    a = ['--', 'data1', '--', 'data2', '--', 'data3']
+ *    a[(1..).step(2)] # => ["data1", "data2", "data3"]
+ *
+ *  Unlike slicing with range, if the start or the end of the arithmetic sequence
+ *  is larger than array size, throws RangeError.
+ *    a = ['--', 'data1', '--', 'data2', '--', 'data3']
+ *    a[(1..11).step(2)]
+ *    # RangeError (((1..11).step(2)) out of range)
+ *    a[(7..).step(2)]
+ *    # RangeError (((7..).step(2)) out of range)
+ *
+ *  If given a single argument, and its type is not one of the listed, tries to
+ *  convert it to Integer, and raises if it is impossible:
  *    a = [:foo, 'bar', 2]
  *    # Raises TypeError (no implicit conversion of Symbol into Integer):
  *    a[:foo]