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

Merged-By: mrkn <mrkn@ruby-lang.org>

NEWS.md

@@ -149,6 +149,14 @@ Outstanding ones only.
         * Array#uniq
         * Array#*
 
+    * Can be sliced with Enumerator::ArithmeticSequence
+
+        ```ruby
+        dirty_data = ['--', 'data1', '--', 'data2', '--', 'data3']
+        dirty_data[(1..).step(2)] # take each second element
+        # => ["data1", "data2", "data3"]
+        ```
+
 * ConditionVariable
 
     * ConditionVariable#wait may now invoke the `block`/`unblock` scheduler

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,
+ *  When a single Enumerator::ArithmeticSequence argument +aseq+ is given,
- *  ...(to be described)
+ *  returns an Array of elements corresponding to the indexes produced by
+ *  the sequence.
+ *    a = ['--', 'data1', '--', 'data2', '--', 'data3']
+ *    a[(1..).step(2)] # => ["data1", "data2", "data3"]
  *
- *  Raises an exception if given a single argument
+ *  Unlike slicing with range, if the start or the end of the arithmetic sequence
- *  that is not an \Integer-convertible object or a \Range object:
+ *  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]

enumerator.c

@@ -3333,6 +3333,9 @@ enumerator_plus(VALUE obj, VALUE eobj)
  * that is a representation of sequences of numbers with common difference.
  * Instances of this class can be generated by the Range#step and Numeric#step
  * methods.
+ *
+ * The class can be used for slicing Array (see Array#slice) or custom
+ * collections.
  */
 
 VALUE