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:
parent
a586ccf21f
commit
eae7aef020
Notes:
git
2020-08-20 08:32:40 +09:00
1 changed files with 75 additions and 106 deletions
181
hash.c
181
hash.c
|
@ -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
|
||||||
|
|
Loading…
Add table
Reference in a new issue