[DOC] Tweaks for Array#fetch_values (#11603)

BurdetteLamar · web-flow · commit 0960c8aacd30 · 2024-09-12T15:19:20.000-04:00
diff --git a/array.c b/array.c
@@ -8600,6 +8600,7 @@ rb_ary_deconstruct(VALUE ary)
  *
  *  - #[] (aliased as #slice): Returns consecutive elements as determined by a given argument.
  *  - #fetch: Returns the element at a given offset.
+ *  - #fetch_values: Returns elements at given offsets.
  *  - #first: Returns one or more leading elements.
  *  - #last: Returns one or more trailing elements.
  *  - #max: Returns one or more maximum-valued elements,
diff --git a/array.rb b/array.rb
@@ -201,22 +201,37 @@ def last n = unspecified = true
   end
 
   #  call-seq:
-  #    array.fetch_values(*indexes) -> new_array
-  #    array.fetch_values(*indexes) {|key| ... } -> new_array
+  #    fetch_values(*indexes) -> new_array
+  #    fetch_values(*indexes) {|index| ... } -> new_array
+  #
+  #  With no block given, returns a new array containing the elements of +self+
+  #  at the offsets given by +indexes+;
+  #  each of the +indexes+ must be an
+  #  {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]:
   #
-  #  Returns a new Array containing the values associated with the given indexes *indexes:
   #    a = [:foo, :bar, :baz]
-  #    a.fetch_values(3, 1) # => [:baz, :foo]
+  #    a.fetch_values(3, 1)   # => [:baz, :foo]
+  #    a.fetch_values(3.1, 1) # => [:baz, :foo]
+  #    a.fetch_values         # => []
+  #
+  #  For a negative index, counts backwards from the end of the array:
+  #
+  #    a.fetch_values([-2, -1]) # [:bar, :baz]
+  #
+  #  When no block is given, raises an exception if any index is out of range.
+  #
+  #  With a block given, for each index:
+  #
+  #  - If the index in in range, uses an element of +self+ (as above).
+  #  - Otherwise calls, the block with the index, and uses the block's return value.
   #
-  #  Returns a new empty Array if no arguments given.
+  #  Example:
   #
-  #  When a block is given, calls the block with each missing index,
-  #  treating the block's return value as the value for that index:
   #    a = [:foo, :bar, :baz]
-  #    values = a.fetch_values(1, 0, 42, 777) {|index| index.to_s}
-  #    values # => [:bar, :foo, "42", "777"]
+  #    a.fetch_values(1, 0, 42, 777) {|index| index.to_s}
+  #    # => [:bar, :foo, "42", "777"]
   #
-  #  When no block is given, raises an exception if any given key is not found.
+  #  Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
   def fetch_values(*indexes, &block)
     indexes.map! { |i| fetch(i, &block) }
     indexes

Original file line number	Diff line number	Diff line change
`@@ -8600,6 +8600,7 @@ rb_ary_deconstruct(VALUE ary)`
`8600`	`8600`	`*`
`8601`	`8601`	`* - #[] (aliased as #slice): Returns consecutive elements as determined by a given argument.`
`8602`	`8602`	`* - #fetch: Returns the element at a given offset.`
	`8603`	`+ * - #fetch_values: Returns elements at given offsets.`
`8603`	`8604`	`* - #first: Returns one or more leading elements.`
`8604`	`8605`	`* - #last: Returns one or more trailing elements.`
`8605`	`8606`	`* - #max: Returns one or more maximum-valued elements,`