diff --git a/array.c b/array.c index 059d6911ee..fcfe01ab87 100644 --- 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 index 4b4c2c0ac8..7450322336 100644 --- a/array.rb +++ b/array.rb @@ -201,22 +201,37 @@ class Array 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 # => [] # - # Returns a new empty Array if no arguments given. + # 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. + # + # 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