From 0e015f9389cd468b0ade2d336526bb75b5bf5015 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sun, 10 Jan 2021 14:13:24 -0600 Subject: [PATCH] Adds RDoc summary of Hash methods (#4045) * Adds RDoc summary of Hash methods --- hash.c | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) diff --git a/hash.c b/hash.c index 04d9c18dfc..a7a29ba3f6 100644 --- a/hash.c +++ b/hash.c @@ -6842,6 +6842,129 @@ env_update(VALUE env, VALUE hash) * synonyms.keys # => [:hello, :world] * * Note that setting the default proc will clear the default value and vice versa. + * + * === What's Here + * + * \Class \Hash provides methods that are useful for: + * + * - {Creating a Hash}[#class-Hash-label-Methods+for+Creating+a+Hash] + * - {Setting Hash State}[#class-Hash-label-Methods+for+Setting+Hash+State] + * - {Querying}[#class-Hash-label-Methods+for+Querying] + * - {Comparing}[#class-Hash-label-Methods+for+Comparing] + * - {Fetching}[#class-Hash-label-Methods+for+Fetching] + * - {Assigning}[#class-Hash-label-Methods+for+Assigning] + * - {Deleting}[#class-Hash-label-Methods+for+Deleting] + * - {Iterating}[#class-Hash-label-Methods+for+Iterating] + * - {Converting}[#class-Hash-label-Methods+for+Converting] + * - {Transforming Keys and Values}[#class-Hash-label-Methods+for+Transforming+Keys+and+Values] + * - {And more....}[#class-Hash-label-Other+Methods] + * + * \Class \Hash also includes methods from module Enumerable. + * + * ==== Methods for Creating a \Hash + * + * ::[]:: Returns a new hash populated with given objects. + * ::new:: Returns a new empty hash. + * ::try_convert:: Returns a new hash created from a given object. + * + * ==== Methods for Setting \Hash State + * + * #compare_by_identity:: Sets +self+ to consider only identity in comparing keys. + * #default=:: Sets the default to a given value. + * #default_proc=:: Sets the default proc to a given proc. + * #rehash:: Rebuilds the hash table by recomputing the hash index for each key. + * + * ==== Methods for Querying + * + * #any?:: Returns whether any element satisfies a given criterion. + * #compare_by_identity?:: Returns whether the hash considers only identity when comparing keys. + * #default:: Returns the default value, or the default value for a given key. + * #default_proc:: Returns the default proc. + * #empty?:: Returns whether there are no entries. + * #eql?:: Returns whether a given object is equal to +self+. + * #hash:: Returns the integer hash code. + * #has_value?:: Returns whether a given object is a value in +self+. + * #include?, #has_key?, #member?, #key?:: Returns whether a given object is a key in +self+. + * #length, #size:: Returns the count of entries. + * #value?:: Returns whether a given object is a value in +self+. + * + * ==== Methods for Comparing + * + * {#<}[#method-i-3C]:: Returns whether +self+ is a proper subset of a given object. + * {#<=}[#method-i-3C-3D]:: Returns whether +self+ is a subset of a given object. + * {#==}[#method-i-3D-3D]:: Returns whether a given object is equal to +self+. + * {#>}[#method-i-3E]:: Returns whether +self+ is a proper superset of a given object + * {#>=}[#method-i-3E-3D]:: Returns whether +self+ is a proper superset of a given object. + * + * ==== Methods for Fetching + * + * #[]:: Returns the value associated with a given key. + * #assoc:: Returns a 2-element array containing a given key and its value. + * #dig:: Returns the object in nested objects that is specified + * by a given key and additional arguments. + * #fetch:: Returns the value for a given key. + * #fetch_values:: Returns array containing the values associated with given keys. + * #key:: Returns the key for the first-found entry with a given value. + * #keys:: Returns an array containing all keys in +self+. + * #rassoc:: Returns a 2-element array consisting of the key and value + of the first-found entry having a given value. + * #values:: Returns an array containing all values in +self+/ + * #values_at:: Returns an array containing values for given keys. + * + * ==== Methods for Assigning + * + * #[]=, #store:: Associates a given key with a given value. + * #merge:: Returns the hash formed by merging each given hash into a copy of +self+. + * #merge!, #update:: Merges each given hash into +self+. + * #replace:: Replaces the entire contents of +self+ with the contents of a givan hash. + * + * ==== Methods for Deleting + * + * These methods remove entries from +self+: + * + * #clear:: Removes all entries from +self+. + * #compact!:: Removes all +nil+-valued entries from +self+. + * #delete:: Removes the entry for a given key. + * #delete_if:: Removes entries selected by a given block. + * #filter!, #select!:: Keep only those entries selected by a given block. + * #keep_if:: Keep only those entries selected by a given block. + * #reject!:: Removes entries selected by a given block. + * #shift:: Removes and returns the first entry. + * + * These methods return a copy of +self+ with some entries removed: + * + * #compact:: Returns a copy of +self+ with all +nil+-valued entries removed. + * #except:: Returns a copy of +self+ with entries removed for specified keys. + * #filter, #select:: Returns a copy of +self+ with only those entries selected by a given block. + * #reject:: Returns a copy of +self+ with entries removed as specified by a given block. + * #slice:: Returns a hash containing the entries for given keys. + * + * ==== Methods for Iterating + * #each, #each_pair:: Calls a given block with each key-value pair. + * #each_key:: Calls a given block with each key. + * #each_value:: Calls a given block with each value. + * + * ==== Methods for Converting + * + * #inspect, #to_s:: Returns a new String containing the hash entries. + * #to_a:: Returns a new array of 2-element arrays; + * each nested array contains a key-value pair from +self+. + * #to_h:: Returns +self+ if a \Hash; + * if a subclass of \Hash, returns a \Hash containing the entries from +self+. + * #to_hash:: Returns +self+. + * #to_proc:: Returns a proc that maps a given key to its value. + * + * ==== Methods for Transforming Keys and Values + * + * #transform_keys:: Returns a copy of +self+ with modified keys. + * #transform_keys!:: Modifies keys in +self+ + * #transform_values:: Returns a copy of +self+ with modified values. + * #transform_values!:: Modifies values in +self+. + * + * ==== Other Methods + * #flatten:: Returns an array that is a 1-dimensional flattening of +self+. + * #invert:: Returns a hash with the each key-value pair inverted. + * */ void