summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--enum.c136
1 files changed, 129 insertions, 7 deletions
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)
/*
- * 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