ruby-changes:61654
From: Burdette <ko1@a...>
Date: Wed, 10 Jun 2020 20:45:49 +0900 (JST)
Subject: [ruby-changes:61654] 8d4b259408 (master): Enhanced Rdoc for Array#fetch and Array#index (#3202)
https://git.ruby-lang.org/ruby.git/commit/?id=8d4b259408 From 8d4b2594086d753bc3e7e5dd16ec827bc360be58 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Wed, 10 Jun 2020 06:45:29 -0500 Subject: Enhanced Rdoc for Array#fetch and Array#index (#3202) * Enhanced Rdoc for Array#fetch and Array#index * Couple of tweaks (per review) in Rdoc for Hash diff --git a/array.c b/array.c index 8f06c3c..4589137 100644 --- a/array.c +++ b/array.c @@ -1033,9 +1033,9 @@ rb_ary_s_try_convert(VALUE dummy, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L1033 * or a single argument +0+, * ignores the block and returns a new empty \Array: * - * a = Array.new(0) { |n| fail 'Cannot happen' } + * a = Array.new(0) { |n| raise 'Cannot happen' } * a # => [] - * a = Array.new { |n| fail 'Cannot happen' } + * a = Array.new { |n| raise 'Cannot happen' } * a # => [] * * With a block and arguments +size+ and +default_value+, @@ -1991,26 +1991,56 @@ rb_ary_last(int argc, const VALUE *argv, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L1991 /* * call-seq: - * ary.fetch(index) -> obj - * ary.fetch(index, default) -> obj - * ary.fetch(index) {|index| block} -> obj - * - * Tries to return the element at position +index+, but throws an IndexError - * exception if the referenced +index+ lies outside of the array bounds. This - * error can be prevented by supplying a second argument, which will act as a - * +default+ value. - * - * Alternatively, if a block is given it will only be executed when an - * invalid +index+ is referenced. - * - * Negative values of +index+ count from the end of the array. - * - * a = [ 11, 22, 33, 44 ] - * a.fetch(1) #=> 22 - * a.fetch(-1) #=> 44 - * a.fetch(4, 'cat') #=> "cat" - * a.fetch(100) {|i| puts "#{i} is out of bounds"} - * #=> "100 is out of bounds" + * array.fetch(index) -> element + * array.fetch(index, default_value) -> element + * array.fetch(index) {|index| ... } -> element + * + * Returns the element at offset +index+. + * + * Argument +index+ must be an + * {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects] + * + * --- + * + * With the single argument +index+, returns the element at offset +index+: + * a = [:foo, 'bar', baz = 2] + * a.fetch(1) # => "bar" + * + * If +index+ is negative, counts from the end of the array: + * a = [:foo, 'bar', baz = 2] + * a.fetch(-1) # => 2 + * a.fetch(-2) # => "bar" + * + * --- + * + * With arguments +index+ and +default_value+, + * returns the element at offset +index+ if index is in range, + * otherwise returns +default_value+: + * a = [:foo, 'bar', baz = 2] + * a.fetch(1, nil) # => "bar" + * a.fetch(50, nil) # => nil + * + * --- + * + * With argument +index+ and a block, + * returns the element at offset +index+ if index is in range + * (and the block is not called); otherwise calls the block with index and returns its return value: + * + * a = [:foo, 'bar', baz = 2] + * a.fetch(1) { |index| raise 'Cannot happen' } # => "bar" + * a.fetch(50) { |index| "Value for #{index}" } # => "Value for 50" + * + * --- + * + * Raises an exception if +index+ is not an \Integer-convertible object. + * a = [:foo, 'bar', baz = 2] + * # Raises TypeError (no implicit conversion of Symbol into Integer): + * a.fetch(:foo) + * + * Raises an exception if +index+ is out of range and neither default_value nor a block given: + * a = [:foo, 'bar', baz = 2] + * # Raises IndexError (index 50 outside of array bounds: -3...3): + * a.fetch(50) */ static VALUE @@ -2043,30 +2073,54 @@ rb_ary_fetch(int argc, VALUE *argv, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L2073 /* * call-seq: - * ary.find_index(obj) -> int or nil - * ary.find_index {|item| block} -> int or nil - * ary.find_index -> Enumerator - * ary.index(obj) -> int or nil - * ary.index {|item| block} -> int or nil - * ary.index -> Enumerator + * array.index(object) -> integer or nil + * array.index {|element| ... } -> integer or nil + * array.index -> new_enumerator + * array.find_index(object) -> integer or nil + * array.find_index {|element| ... } -> integer or nil + * array.find_index -> new_enumerator * - * Returns the _index_ of the first object in +ary+ such that the object is - * <code>==</code> to +obj+. + * Array#index is an alias for Array#find_index. * - * If a block is given instead of an argument, returns the _index_ of the - * first object for which the block returns +true+. Returns +nil+ if no - * match is found. + * --- * - * See also Array#rindex. + * When argument +object+ is given but no block, + * returns the index of the first element +element+ + * for which <tt>object == element</tt>: + * a = [:foo, 'bar', baz = 2, 'bar'] + * a.index('bar') # => 1 * - * An Enumerator is returned if neither a block nor argument is given. + * Returns +nil+ if no such element found: + * a = [:foo, 'bar', baz = 2] + * a.index(:nosuch) # => nil * - * a = [ "a", "b", "c" ] - * a.index("b") #=> 1 - * a.index("z") #=> nil - * a.index {|x| x == "b"} #=> 1 + * --- * - * Array#index is an alias for Array#find_index. + * When both argument +object+ and a block are given, + * calls the block with each successive element; + * returns the index of the first element for which the block returns a truthy value: + * a = [:foo, 'bar', baz = 2, 'bar'] + * a.index { |element| element == 'bar' } # => 1 + * + * Returns +nil+ if the block never returns a truthy value: + * a = [:foo, 'bar', baz = 2] + * a.index { |element| element == :X } # => nil + * + * --- + * + * When neither an argument nor a block is given, returns a new Enumerator: + * a = [:foo, 'bar', baz = 2] + * e = a.index + * e # => #<Enumerator: [:foo, "bar", 2]:index> + * e.each { |element| element == 'bar' } # => 1 + * + * --- + * + * When both an argument and a block given, gives a warning (warning: given block not used) + * and ignores the block: + * a = [:foo, 'bar', baz = 2, 'bar'] + * index = a.index('bar') { raise 'Cannot happen' } + * index # => 1 */ static VALUE diff --git a/hash.c b/hash.c index 139b822..93fe10e 100644 --- a/hash.c +++ b/hash.c @@ -2226,7 +2226,7 @@ rb_hash_lookup(VALUE hash, VALUE key) https://github.com/ruby/ruby/blob/trunk/hash.c#L2226 * * If +key+ is found, returns its associated value. * * Otherwise, calls the block with +key+, and returns the block's return value. * h = {foo: 0, bar: 1, baz: 2} - * h.fetch(:bar) { |key| fail 'Ignored'} # => 1 + * h.fetch(:bar) { |key| raise 'Ignored'} # => 1 * h.fetch(:nosuch) { |key| "Value for #{key}"} # => "Value for nosuch" * * When both +default+ and a block are given: @@ -2234,7 +2234,7 @@ rb_hash_lookup(VALUE hash, VALUE key) https://github.com/ruby/ruby/blob/trunk/hash.c#L2234 * * If +key+ is found, returns its associated value. * * Otherwise, calls the block with +key+, and returns the block's return value. * h = {foo: 0, bar: 1, baz: 2} - * h.fetch(:bar, :default) { |key| fail 'Ignored'} # => 1 + * h.fetch(:bar, :default) { |key| raise 'Ignored'} # => 1 * h.fetch(:nosuch, :default) { |key| "Value for #{key}"} # => "Value for nosuch" * * --- @@ -2526,7 +2526,7 @@ rb_hash_delete(VALUE hash, VALUE key) https://github.com/ruby/ruby/blob/trunk/hash.c#L2526 * If a block is given and +key+ is found, ignores the block, * deletes the entry, and returns the associated value: * h = {foo: 0, bar: 1, baz: 2} - * h.delete(:baz) { |key| fail 'Will never happen'} # => 2 + * h.delete(:baz) { |key| raise 'Will never happen'} # => 2 * h # => {:foo=>0, :bar=>1} * * If a block is given and +key+ is not found, @@ -4397,7 +4397,7 @@ rb_hash_update_block_i(VALUE key, VALUE value, VALUE hash) https://github.com/ruby/ruby/blob/trunk/hash.c#L4397 * Example: * h = {foo: 0, bar: 1, baz: 2} * h.merge # => {:foo=>0, :bar=>1, :baz=>2} - * h1 = h.merge! { |key, old_value, new_value| fail 'Cannot happen' } + * h1 = h.merge! { |key, old_value, new_value| raise 'Cannot happen' } * h1 # => {:foo=>0, :bar=>1, :baz=>2} * h1.equal?(h) # => true # Identity check * @@ -4547,7 +4547,7 @@ rb_hash_update_by(VALUE hash1, VALUE hash2, rb_hash_update_func *func) https://github.com/ruby/ruby/blob/trunk/hash.c#L4547 * h1 = h.merge * h1 # => {:foo=>0, :bar=>1, :baz=>2} * h1.equal?(h) # => false # Identity check - * h2 = h.merge { |key, old_value, new_value| fail 'Cannot happen' } + * h2 = h.merge { |key, old_value, new_value| raise 'Cannot happen' } * h2 # => {:foo=>0, :bar=>1, :baz=>2} * h2.equal?(h) # => false # Identity check * @@ -5553,7 +5553,7 @@ env_delete(VALUE name) https://github.com/ruby/ruby/blob/trunk/hash.c#L5553 * If a block given and the environment variable exists, * deletes the environment variable and returns its value (ignoring the block): * ENV['foo'] = '0' - * ENV.delete('foo') { |name| fail 'ignored' } # => "0" + * ENV.delete('foo') { |name| raise 'ignored' } # => "0" * Raises an exception if +name+ is invalid. * See {Invalid Names and Values}[#class-ENV-label-Invalid+Names+and+Values]. */ -- cgit v0.10.2 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/