ruby-changes:64745
From: Burdette <ko1@a...>
Date: Tue, 5 Jan 2021 13:39:29 +0900 (JST)
Subject: [ruby-changes:64745] f2d0d4cb0a (master): RDoc: Enhanced introduction for Enumerable (#4004)
https://git.ruby-lang.org/ruby.git/commit/?id=f2d0d4cb0a From f2d0d4cb0ace469e2ca2fd11e16261df1f2840ff Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Mon, 4 Jan 2021 22:39:13 -0600 Subject: RDoc: Enhanced introduction for Enumerable (#4004) * RDoc: Enhanced introduction for Enumerable * RDoc: Enhanced introduction for Enumerable * RDoc: Enhanced introduction for Enumerable diff --git a/enum.c b/enum.c index f1f0e13..ef35f9b 100644 --- a/enum.c +++ b/enum.c @@ -4221,13 +4221,135 @@ enum_compact(VALUE obj) https://github.com/ruby/ruby/blob/trunk/enum.c#L4221 /* - * The Enumerable mixin provides collection classes with several - * traversal and searching methods, and with the ability to sort. The - * class must provide a method #each, which yields - * successive members of the collection. If Enumerable#max, #min, or - * #sort is used, the objects in the collection must also implement a - * meaningful <code><=></code> operator, as these methods rely on an - * ordering between members of the collection. + * == What's Here + * + * \Module \Enumerable provides methods that are useful to a collection class for: + * - {Querying}[#module-Enumerable-label-Methods+for+Querying] + * - {Fetching}[#module-Enumerable-label-Methods+for+Fetching] + * - {Searching}[#module-Enumerable-label-Methods+for+Searching] + * - {Sorting}[#module-Enumerable-label-Methods+for+Sorting] + * - {Iterating}[#module-Enumerable-label-Methods+for+Iterating] + * - {And more....}[#module-Enumerable-label-Other+Methods] + * + * === Methods for Querying + * + * These methods return information about the \Enumerable other than the elements themselves: + * + * #include?, #member?:: Returns +true+ if self == object, +false+ otherwise. + * #all?:: Returns +true+ if all elements meet a specified criterion; +false+ otherwise. + * #any?:: Returns +true+ if any element meets a specified criterion; +false+ otherwise. + * #none?:: Returns +true+ if no element meets a specified criterion; +false+ otherwise. + * #one?:: Returns +true+ if exactly one element meets a specified criterion; +false+ otherwise. + * #count:: Returns the count of elements, + * based on an argument or block criterion, if given. + * #tally:: Returns a new \Hash containing the counts of occurrences of each element. + * + * === Methods for Fetching + * + * These methods return entries from the \Enumerable, without modifying it: + * + * <i>Leading, trailing, or all elements</i>: + * #entries, #to_a:: Returns all elements. + * #first:: Returns the first element or leading elements. + * #take:: Returns a specified number of leading elements. + * #drop:: Returns a specified number of trailing elements. + * #take_while:: Returns leading elements as specified by the given block. + * #drop_while:: Returns trailing elements as specified by the given block. + * + * <i>Minimum and maximum value elements</i>: + * #min:: Returns the elements whose values are smallest among the elements, + * as determined by <tt><=></tt> or a given block. + * #max:: Returns the elements whose values are largest among the elements, + * as determined by <tt><=></tt> or a given block. + * #minmax:: Returns a 2-element \Array containing the smallest and largest elements. + * #min_by:: Returns the smallest element, as determined by the given block. + * #max_by:: Returns the largest element, as determined by the given block. + * #minmax_by:: Returns the smallest and largest elements, as determined by the given block. + * + * <i>Groups, slices, and partitions</i>: + * #group_by:: Returns a \Hash that partitions the elements into groups. + * #partition:: Returns elements partitioned into two new Arrays, as determined by the given block. + * #slice_after:: Returns a new \Enumerator whose entries are a partition of +self+, + based either on a given +object+ or a given block. + * #slice_before:: Returns a new \Enumerator whose entries are a partition of +self+, + based either on a given +object+ or a given block. + * #slice_when:: Returns a new \Enumerator whose entries are a partition of +self+ + based on the given block. + * #chunk:: Returns elements organized into chunks as specified by the given block. + * #chunk_while:: Returns elements organized into chunks as specified by the given block. + * + * === Methods for Searching and Filtering + * + * These methods return elements that meet a specified criterion. + * + * #find, #detect:: Returns an element selected by the block. + * #find_all, #filter, #select:: Returns elements selected by the block. + * #find_index:: Returns the index of an element selected by a given object or block. + * #reject:: Returns elements not rejected by the block. + * #uniq:: Returns elements that are not duplicates. + * + * === Methods for Sorting + * + * These methods return elements in sorted order. + * + * #sort:: Returns the elements, sorted by <tt><=></tt> or the given block. + * #sort_by:: Returns the elements, sorted by the given block. + * + * === Methods for Iterating + * + * #each_entry:: Calls the block with each successive element + * (slightly different from #each). + * #each_with_index:: Calls the block with each successive element and its index. + * #each_with_object:: Calls the block with each successive element and a given object. + * #each_slice:: Calls the block with successive non-overlapping slices. + * #each_cons:: Calls the block with successive overlapping slices. + * (different from #each_slice). + * #reverse_each:: Calls the block with each successive element, in reverse order. + * + * === Other Methods + * + * #map, #collect:: Returns objects returned by the block. + * #filter_map:: Returns truthy objects returned by the block. + * #flat_map, #collect_concat:: Returns flattened objects returned by the block. + * #grep:: Returns elements selected by a given object + * or objects returned by a given block. + * #grep_v:: Returns elements selected by a given object + * or objects returned by a given block. + * #reduce, #inject:: Returns the object formed by combining all elements. + * #sum:: Returns the sum of the elements, using method +++. + * #zip:: Combines each element with elements from other enumerables; + * returns the n-tuples or calls the block with each. + * #cycle:: Calls the block with each element, cycling repeatedly. + * + * == Usage + * + * To use module \Enumerable in a collection class: + * - Include it: + * include Enumerable + * - Implement method <tt>#each</tt> + * which must yield successive elements of the collection. + * This method will be called by almost any \Enumerable method. + * + * == \Enumerable in Ruby Core Classes + * Some Ruby classes include \Enumerable: + * - Array + * - Dir + * - Hash + * - IO + * - Range + * - Set + * - Struct + * Virtually all methods in \Enumerable call method +#each+ in the including class: + * - <tt>Hash#each</tt> yields the next key-value pair as a 2-element \Array. + * - <tt>Struct#each</tt> yields the next name-value pair as a 2-element \Array. + * - For the other classes above, +#each+ yields the next object from the collection. + * + * == About the Examples + * The example code snippets for the \Enumerable methods: + * - Always show the use of one or more \Array-like classes (often \Array itself). + * - Sometimes show the use of a \Hash-like class. + * For some methods, though, the usage would not make sense, + * and so it is not shown. Example: #tally would find exactly one of each \Hash entry. */ void -- cgit v0.10.2 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/