Implementing Enumerable: Write One Method, Get 22 Free

Table of contents:

Implementing Enumerable Write One Method, Get 22 Free

Implementing Enumerable Write One Method, Get 22 Free

Problem

You want to give a class all the useful iterator and iteration-related features of Ruby's arrays (sort, detect, inject, and so on), but your class can't be a subclass of Array. You don't want to define all those methods yourself.

Solution

Implement an each method, then include the Enumerable module. It defines 22 of the most useful iteration methods in terms of the each implementation you provide.

Here's a class that keeps multiple arrays under the covers. By defining each, it can expose a large interface that lets the user treat it like a single array:

	class MultiArray
	 include Enumerable

	 def initialize(*arrays)
	 @arrays = arrays
	 end

	 def each
	 @arrays.each { |a| a.each { |x| yield x } }
	 end
	end

	ma = MultiArray.new([1, 2], [3], [4])
	ma.collect # => [1, 2, 3, 4]
	ma.detect { |x| x > 3 } # => 4
	ma.map { |x| x ** 2 } # => [1, 4, 9, 16]
	ma.each_with_index { |x, i| puts "Element #{i} is #{x}" }
	# Element 0 is 1
	# Element 1 is 2
	# Element 2 is 3
	# Element 3 is 4

Discussion

The Enumerable module is the most common mixin module. It lets you add a lot of behavior to your class for a little investment. Since Ruby relies so heavily on iterator methods, and almost every data structure can be iterated over in some way, it's no wonder that so many of the classes in Ruby's standard library include Enumerable: Dir, Hash, Range, and String, just to name a few.

Here's the complete list of methods you can get by including Enumerable. Many of them are described elsewhere in this book, especially in Chapter 4. Perhaps the most useful are collect, inject, find_all, and sort_by.

	Enumerable.instance_methods.sort
	# => ["all?", "any?", "collect", "detect", "each_with_index", "entries",
	# => "find", "find_all", "grep", "include?", "inject", "map", "max",
	# => "member?", "min", "partition", "reject", "select", "sort", "sort_by",
	# => "to_a", "zip"]

Although you can get all these methods simply by implementing an each method, some of the methods won't work unless your each implementation returns objects that can be compared to each other. For example, a data structure that contains both numbers and strings can't be sorted, since it makes no sense to compare a number to a string:

	ma.sort # => [1, 2, 3, 4]
	mixed_type_ma = MultiArray.new([1, 2, 3], ["a", "b", "c"])
	mixed_type_ma.sort
	# ArgumentError: comparison of Fixnum with String failed

The methods subject to this restriction are max, min, sort, and sort_by. Since you probably don't have complete control over the types of the data stored in your data structure, the best strategy is probably to just let a method fail if the data is incompatible. This is what Array does:

	[1, 2, 3, "a", "b", "c"].sort
	# ArgumentError: comparison of Fixnum with String failed

One more example: in this one, I'll make Module itself include Enumerable. My each implementation will iterate over the instance methods defined by a class or module. This makes it easy to find methods of a class that meet certain criteria.

	class Module
	 include Enumerable
	 def each
	 instance_methods.each { |x| yield x }
	 end
	end

	# Find all instance methods of String that modify the string in place.
	String.find_all { |method_name| method_name[-1] == ?! }
	# => ["sub!", "upcase!", "delete!", "lstrip!", "succ!", "gsub!",
	# => "squeeze!", "downcase!", "rstrip!", "slice!", "chop!", "capitalize!",
	# => "tr!", "chomp!", "next!", "swapcase!", "reverse!", "tr_s!", "strip!"]

	# Find all instance methods of Fixnum that take 2 arguments.
	sample = 0
	sample.class.find_all { |method_name| sample.method(method_name).arity == 2 }
	# => ["instance_variable_set", "between?"]