1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00

[DOC] Improve Hash's doc for missing keys

This commit is contained in:
Marc-Andre Lafortune 2020-07-29 16:04:55 -04:00 committed by Marc-André Lafortune
parent a586ccf21f
commit eae7aef020
Notes: git 2020-08-20 08:32:40 +09:00

181
hash.c
View file

@ -2187,38 +2187,24 @@ rb_hash_lookup(VALUE hash, VALUE key)
* hash.fetch(key) { |key| ... } -> value * hash.fetch(key) { |key| ... } -> value
* *
* Returns the value for the given +key+. * Returns the value for the given +key+.
* h = {foo: 0, bar: 1, baz: 2}
* h.fetch(:bar) # => 1
* *
* --- * If +key+ is not found, then the given +default+ or
* block (if any) will be used:
* *
* When neither +default+ nor a block given: * {}.fetch(:nosuch, :default) # => :default
* * If +key+ is found, returns its associated value. * {}.fetch(:nosuch) { |key| "No #{key}"}) # => "No nosuch"
* * Otherwise, raises an exception:
* h = {foo: 0, bar: 1, baz: 2}
* h.fetch(:bar) # => 1
* # Raises KeyError (key not found: :nosuch):
* h.fetch(:nosuch)
* *
* When +default+ is given, but no block: * If neither is given, an error is raised:
* * If +key+ is found, returns its associated value.
* * Otherwise, returns the given +default+:
* h = {foo: 0, bar: 1, baz: 2}
* h.fetch(:bar, :default) # => 1
* h.fetch(:nosuch, :default) # => :default
* *
* When a block is given, but no +default+: * {}.fetch(:foo) # => KeyError (key not found: :nosuch)
* * 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| raise 'Ignored'} # => 1
* h.fetch(:nosuch) { |key| "Value for #{key}"} # => "Value for nosuch"
* *
* When both +default+ and a block are given: * Note that the #default or #default_proc are always ignored by `fetch`
* * Ignores +default+ and issues a warning: 'block supersedes default value argument'. *
* * If +key+ is found, returns its associated value. * h = Hash.new(0)
* * Otherwise, calls the block with +key+, and returns the block's return value. * h[:nosuch] # => 0
* h = {foo: 0, bar: 1, baz: 2} * h.fetch(:nosuch) # => KeyError
* h.fetch(:bar, :default) { |key| raise 'Ignored'} # => 1
* h.fetch(:nosuch, :default) { |key| "Value for #{key}"} # => "Value for nosuch"
*/ */
static VALUE static VALUE
@ -2276,12 +2262,12 @@ rb_hash_fetch(VALUE hash, VALUE key)
* *
* With +key+ given, returns the default value for +key+, * With +key+ given, returns the default value for +key+,
* regardless of whether that key exists: * regardless of whether that key exists:
* h = {} * h = Hash.new { |hash, key| hash[key] = "No #{key}"}
* h.default(:nosuch) # => nil # h[:foo] = "Hello"
* h.default(:foo) # => "No foo"
* *
* The returned value will be determined either by the default proc or by the default value. * The returned value will be determined either by the default proc or by the default value.
* See {Default Values}[#class-Hash-label-Default+Values]. * See {Default Values}[#class-Hash-label-Default+Values].
*
*/ */
static VALUE static VALUE
@ -2757,6 +2743,10 @@ rb_hash_reject(VALUE hash)
* h1 = h.slice(:baz, :foo) * h1 = h.slice(:baz, :foo)
* h1 # => {:baz=>2, :foo=>0} * h1 # => {:baz=>2, :foo=>0}
* h1.equal?(h) # => false * h1.equal?(h) # => false
*
* The given keys that are not found are ignored:
* h = {foo: 0, bar: 1}
* h.slice(:not_there, :bar, :not_there_either) # => {bar: 1}
*/ */
static VALUE static VALUE
@ -2788,7 +2778,9 @@ rb_hash_slice(int argc, VALUE *argv, VALUE hash)
* *
* h = { a: 100, b: 200, c: 300 } * h = { a: 100, b: 200, c: 300 }
* h.except(:a) #=> {:b=>200, :c=>300} * h.except(:a) #=> {:b=>200, :c=>300}
* h.except(:b, :c, :d) #=> {:a=>100} *
* The given keys that are not found are ignored:
* h.except(:b, :c, :not_there, :idem) #=> {:a=>100}
*/ */
static VALUE static VALUE
@ -2815,9 +2807,11 @@ rb_hash_except(int argc, VALUE *argv, VALUE hash)
* h = {foo: 0, bar: 1, baz: 2} * h = {foo: 0, bar: 1, baz: 2}
* h.values_at(:foo, :baz) # => [0, 2] * h.values_at(:foo, :baz) # => [0, 2]
* *
* Returns an empty Array if no arguments given: * The {default values}[#class-Hash-label-Default+Values] will be used for keys
* h = {foo: 0, bar: 1, baz: 2} * that are not present:
* h.values_at # => [] * h.values_at(:hello, :foo) # => [nil, 0]
* h.default = -1
* h.values_at(:hello, :foo) # => [-1, 0]
*/ */
VALUE VALUE
@ -4540,7 +4534,7 @@ assoc_i(VALUE key, VALUE val, VALUE arg)
* *
* Returns +nil+ if key +key+ is not found: * Returns +nil+ if key +key+ is not found:
* h = {foo: 0, bar: 1, baz: 2} * h = {foo: 0, bar: 1, baz: 2}
* h.assoc(:nosuch) * h.assoc(:nosuch) # => nil
*/ */
VALUE VALUE
@ -4987,10 +4981,6 @@ rb_hash_any_p(int argc, VALUE *argv, VALUE hash)
* h.dig(:foo, :bar, :baz) # => 2 * h.dig(:foo, :bar, :baz) # => 2
* h.dig(:foo, :bar, :BAZ) # => nil * h.dig(:foo, :bar, :BAZ) # => nil
* *
* Returns +nil+ if any key is not found:
* h = { foo: {bar: {baz: 2}}}
* h.dig(:foo, :nosuch) # => nil
*
* The nested objects may include any that respond to \#dig. See: * The nested objects may include any that respond to \#dig. See:
* - Hash#dig * - Hash#dig
* - Array#dig * - Array#dig
@ -5002,6 +4992,14 @@ rb_hash_any_p(int argc, VALUE *argv, VALUE hash)
* Example: * Example:
* h = {foo: {bar: [:a, :b, :c]}} * h = {foo: {bar: [:a, :b, :c]}}
* h.dig(:foo, :bar, 2) # => :c * h.dig(:foo, :bar, 2) # => :c
*
* This method will use the {default values}[#class-Hash-label-Default+Values]
* for keys that are not present:
* h = {foo: {bar: [:a, :b, :c]}}
* h.dig(:hello) # => nil
* h.default_proc = -> (hash, _key) { hash }
* h.dig(:hello, :world) # => h
* h.dig(:hello, :world, :foo, :bar, 2) # => :c
*/ */
static VALUE static VALUE
@ -7280,60 +7278,47 @@ env_update(VALUE env, VALUE hash)
* *
* === Default Values * === Default Values
* *
* For a key that is not found, * The methods #[], #values_at and #dig need to return the value associated to a certain key
* method #[] returns a default value * When that key is not found, that value will be determined by its default proc (if any)
* determined by: * or else its default (initially `nil`).
*
* - Its default proc, if the default proc is not +nil+.
* - Its default value, otherwise.
*
* ==== Default Value
*
* A \Hash object's default value is relevant only
* when its default proc is +nil+. (Initially, both are +nil+).
* *
* You can retrieve the default value with method #default: * You can retrieve the default value with method #default:
* *
* h = Hash.new * h = Hash.new
* h.default # => nil * h.default # => nil
* *
* You can initialize the default value by passing an argument to method Hash.new: * You can set the default value by passing an argument to method Hash.new or
* with method #default=
* *
* h = Hash.new(false) * h = Hash.new(-1)
* h.default # => false * h.default # => -1
* h.default = 0
* h.default # => 0
* *
* You can update the default value with method #default=: * This default value is returned for #[], #values_at and #dig when a key is
* not found:
* *
* h.default = false * counts = {foo: 42}
* h.default # => false * counts.default # => nil (default)
* counts[:foo] = 42
* counts[:bar] # => nil
* counts.default = 0
* counts[:bar] # => 0
* counts.values_at(:foo, :bar, :baz) # => [42, 0, 0]
* counts.dig(:bar) # => 0
* *
* Incidentally, updating the default value (even to +nil+) * Note that the default value is used without being duplicated. It is not advised to set
* also sets the default proc to +nil+: * the default value to a mutable object:
* *
* h.default_proc = proc { } * synonyms = Hash.new([])
* h.default = nil * synonyms[:hello] # => []
* h.default_proc # => nil * synonyms[:hello] << :hi # => [:hi], but this mutates the default!
* synonyms.default # => [:hi]
* synonyms[:world] << :universe
* synonyms[:world] # => [:hi, :universe], oops
* synonyms.keys # => [], oops
* *
* When the default proc is +nil+, * To use a mutable object as default, it is recommended to use a default proc
* method #[] returns the value of method #default:
*
* h = Hash.new
* h.default_proc # => nil
* h.default # => nil
* h[:nosuch] # => nil
* h.default = false
* h[:nosuch] # => false
*
* For certain kinds of default values, the default value can be modified thus:
*
* h = Hash.new('Foo')
* h[:nosuch] # => "Foo"
* h[:nosuch].upcase! # => "FOO"
* h[:nosuch] # => "FOO"
* h.default = [0, 1]
* h[:nosuch] # => [0, 1]
* h[:nosuch].reverse! # => [1, 0]
* h[:nosuch] # => [1, 0]
* *
* ==== Default \Proc * ==== Default \Proc
* *
@ -7345,24 +7330,14 @@ env_update(VALUE env, VALUE hash)
* h = Hash.new * h = Hash.new
* h.default_proc # => nil * h.default_proc # => nil
* *
* You can initialize the default proc by calling Hash.new with a block: * You can set the default proc by calling Hash.new with a block or
* calling the method #default_proc=
* *
* h = Hash.new { |hash, key| "Default value for #{key}" } * h = Hash.new { |hash, key| "Default value for #{key}" }
* h.default_proc.class # => Proc * h.default_proc.class # => Proc
* * h.default_proc = proc { |hash, key| "Default value for #{key.inspect}" }
* You can update the default proc with method #default_proc=:
*
* h = Hash.new
* h.default_proc = proc { |hash, key| "Default value for #{key}" }
* h.default_proc.class # => Proc * h.default_proc.class # => Proc
* *
* Incidentally, updating the default proc (even to +nil+)
* also sets the default value to +nil+:
*
* h.default = false
* h.default_proc = nil
* h.default # => nil
*
* When the default proc is set (i.e., not +nil+) * When the default proc is set (i.e., not +nil+)
* and method #[] is called with with a non-existent key, * and method #[] is called with with a non-existent key,
* #[] calls the default proc with both the \Hash object itself and the missing key, * #[] calls the default proc with both the \Hash object itself and the missing key,
@ -7377,19 +7352,13 @@ env_update(VALUE env, VALUE hash)
* *
* However, the proc itself can add a new entry: * However, the proc itself can add a new entry:
* *
* h = Hash.new { |hash, key| hash[key] = "Subsequent value for #{key}"; "First value for #{key}" } * synonyms = Hash.new { |hash, key| hash[key] = [] }
* h.include?(:nosuch) # => false * synonyms.include?(:hello) # => false
* h[:nosuch] # => "First value for nosuch" * synonyms[:hello] << :hi # => [:hi]
* h.include?(:nosuch) # => true * synonyms[:world] << :universe # => [:universe]
* h[:nosuch] # => "Subsequent value for nosuch" * synonyms.keys # => [:hello, :world]
* h[:nosuch] # => "Subsequent value for nosuch"
* *
* You can set the default proc to +nil+, which restores control to the default value: * Note that setting the default proc will clear the default value and vice versa.
*
* h.delete(:nosuch)
* h.default_proc = nil
* h.default = false
* h[:nosuch] # => false
*/ */
void void