Here’s the publisher’s write-up of the book:

Want to learn about databases without the tedium? With its unique combination of Japanese-style comics and serious educational content, The Manga Guide to Databases is just the book for you.

Princess Ruruna is stressed out. With the king and queen away, she has to manage the Kingdom of Kod’s humongous fruit-selling empire. Overseas departments, scads of inventory, conflicting prices, and so many customers! It’s all such a confusing mess. But a mysterious book and a helpful fairy promise to solve her organizational problems—with the practical magic of databases.

In The Manga Guide to Databases, Tico the fairy teaches the Princess how to simplify her data management. We follow along as they design a relational database, understand the entity-relationship model, perform basic database operations, and delve into more advanced topics. Once the Princess is familiar with transactions and basic SQL statements, she can keep her data timely and accurate for the entire kingdom. Finally, Tico explains ways to make the database more efficient and secure, and they discuss methods for concurrency and replication.

Examples and exercises (with answer keys) help you learn, and an appendix of frequently used SQL statements gives the tools you need to create and maintain full-featured databases.

(Of course, it wouldn’t be a royal kingdom without some drama, so read on to find out who gets the girl—the arrogant prince or the humble servant.)

This EduManga book is a translation of a bestselling series in Japan, co-published with Ohmsha, Ltd., of Tokyo, Japan.

The book will be available on December 1st, just in time to order as a Christmas present for someone who’s into both programming and manga.

On the off-chance you hadn’t yet heard, Apple has finally dropped its much-reviled NDA for iPhone developers for released software. It was so restrictive that developers were forbidden from discussing or writing documentation on iPhone development, even with or for other iPhone developers.

In the announcement on Apple Developer Connection, they explain why they put developers under the excessively-restrictive NDA:

We put the NDA in place because the iPhone OS includes many Apple inventions and innovations that we would like to protect, so that others don’t steal our work. It has happened before. While we have filed for hundreds of patents on iPhone technology, the NDA added yet another level of protection. We put it in place as one more way to help protect the iPhone from being ripped off by others.

This sort of behaviour harkens back to the 1990s, when Apple behaved as if all third-party developers who weren’t Adobe existed on a spectrum ranging from “unwanted houseguest” to “the enemy”. Speaking as a guy with a strong technical evangelist background (note to employers: hint, hint!), this is not the way you foster developer love nor build a developer community.

Expect iPhone development tutorials and tips to start popping up all over the web and for the Pragmatic Programmers’ book iPhone SDK Development to finally see the light of day.

Last Friday marked the return of Ruby on Rails Project Night, a Toronto-based event where developers who worked on Ruby and Rails projects could do in-depth presentations on their current projects or ideas. It was on hiatus for the past couple of months (you can see this entry for the definition of “on hiatus”), but thanks to the efforts of Corina Newby, who helped put together the event at its old venue, it’s back, and judging from the attendance, it was missed. Thanks, Corina, for all your work!

James Robertson

The first speaker was also the special guest (and the reason the event was held on a Friday, as opposed to the typical Monday or Tuesday): James Robertson, whom you may know from his blog Smalltalk Tidbits, Industry Rants. He was on a “Canadian tour”, during which he was talking about the Smalltalk-based web app framework Seaside as well as Webvelocity, which puts the Smalltalk development experience within the browser.

Here’s the abstract for his presentation (from this entry from Corina’s blog):

WebVelocity is a new Smalltalk Development Environment that is oriented around Seaside for Web Development and Glorp for Object/Relatonal Mapping. Come and see how WebVelocity re-targets the Smalltalk development experience into the Web Browser and simplifies the challenge of learning a new environment for newcomers. We’ll even build an entire application using Active Record and Scaffolding during the presentation, with minimal programming. If you’re a fan of Ruby on Rails, you need to come out and see this presentation!

Here are my notes from his presentation:

- Seaside is open source, but Smalltalk ain't
- Seaside is maintained in Squeak, which you could call "the open source Smalltalk"

- Ruby on Rails is opinionated
- "Seaside is also opinated; it just has different opinions"
- When building Seaside, Avi Bryant asked "What if I took all the assumptions about web apps...
  and ignored them?"
- Some of what I show you is what happens when you blow those assumptions

- The canonical Seaside example -- the number increment/decrement button
  (now we know where that disastrous DemoCamp Seaside presentation came from!)
- Seaside uses continuations to remember state
- They enable "proper" support for the backbutton
- Session state info is keyed via a cryptographically secure key in the URL

- With Rails, you're dealing with two different worlds: templates and code
- Seaside is just one world: You don't write any HTML at all, you write all Smalltalk
- It's all in one place
- Support for debugger -- you can debug web apps as if they were desktop apps, with breakpoints and resumes
- In Seaside, the "html" argument is a "brush" that knows how to "paint" HTML
- You can debug in the middle of a page hit

- In beta: Seaside totally within the browser
- Editing code within a webpage, including tooltips and color hinting
- Every time a method is entered and it is syntactically correct, it is auto-saved -- no need to manual save!
- [Shows a Smalltalk debugger with an Ajax front end]
- "In some ways, it's even more productive than the real Smalltalk environment is"
- [Smalltalk console within the browser]
- [Auto-indenting within the browser]
- [Auto-generates a scaffolding-like page]
- The "call" method lets you write web app code very much like writing GUI stuff

Paul Doerwald

The second speaker was Paul Doerwald, who changed his topic from the more Ruby/Rails-specific “insights gained from working with ActiveRecord validation” to a more general (but still interesting) topic: Agile Documentation. He figured that it might be a better fit with James’ presentation, and it was — it was also quite interesting.

Here’s the abstract for his presentation:

“Programmers generally hate writing documentation. That’s because most documentation is kept separate from the code and becomes hard to keep up-to-date. Besides violating the DRY principle… it can lead to misleading documentation, which is generally worse than none at all.” [Subramaniam/Hunt '06]. Why do developers hate writing documentation, and why do stakeholders and managers keep requiring it? Is there agile documentation beyond inline API documentation (JavaDoc, RDoc, etc.) and comments in the code? What parts of a project deserve separate-from-code documentation? How do we identify them, capture them, and keep them relevant?

Tonight’s Toronto Ruby on Rails Project Night presentation discusses the problem of documentation, explores some key aspects to consider when writing effective documentation, and dreams of a future of testable, executable documentation, where non-code knowledge could be integrated into your code.“

And here are my notes from his talk:

- My original presentation was going to be about insights gained from ActiveRecord validation
- But I've decided to change it -- it's now on Agile Documentation
- It's my M.Sc. Thesis!
- "You'll find this talk a bit heavy on problem and not so heavy on solution"
- Think of this as an introduction -- I want to frame things and ask:
  what is Agile Documentation?

- By "documentation", I mean by the kind that's by programmers for programmers

- It's not a particularly sexy area
- Frameworks are sexy:
    - Rails is sexy
    - Django is sexy
    - CakePHP is sexy...(for PHP)
- Languages are sexy
    - Ruby is sexy
    - Objective-C is..."strangely alluring"
- Even databases are sexy! Consider CouchDB and AWS
- What's not sexy?
    - Documentation
    - Backup -- at least not until Apple's Time Machine
    - Both are viewed as a waste of time

- We're developers. We may grudgingly accept the presence of non-developer things,
  but we don't want to do them
- Documentation is hard to write
- It seems so much easier to program rather than write
- Writing -- the non code-type -- is not our core competency
- We say "Our code is the authoritative documentation!"
- Consider what DHH said in a "Signal vs. Noise" blog entry in February 2006
    - When asked "How do you document your projects?", he replied "We don't."
    - He also said:
        - "Never worked consistently or successfully"
        - "Not necessary for our work"
        - "Most Rails developers can walk in and find out"
        - "We use Ruby"
        - "Method docs only for non-obvious behaviour"
        - "Docs mean BDUF"
        - "Appropriate only for onerous enviroments with complex policies"
        - "Focus on code quality instead"

- Like backups, docs are important
- We're not the only people who'll be working on a project, especially if it's a success
- We don't want to feel like we're wasting time when we're working
- Running a documentation tool and taking its output and pasting it into a Word doc is not DRY
- Why are we writing highly-coupled docs?

- Is there such a thing as agile documentation? I'm going to say yes
- Look at the Agile Manifesto
    - "We value working software over comprehensive documentation"
    - But it doesn't say that comprehensive documentation isn't valued!

- What's the state of the Art
    - For API Documentation, it's JavaDoc
    - In Rails, the outer classes are well documented, but not the inner ones
    - The JDK is extremely well-documented
    - You could say that RSpec is a form of agile documentation
    - It's a stretch, but Domain-Specific Languages could also be agile documentation
    - After all these, I can only think of process
    - When do we do docs? At the beginning of the process? At the end?

- What could agile documentation look like? What does it feel like?
- I borrowed principle from Alastair Cockburn's "Agile Software Development:
  The Cooperative Game, 2nd ed."
- The goals set out in the book:
    - Finish the game (i.e. finish development and launch the product)
    - Set up the game for the next team
    - Think of pool: maybe you take the hard shot first to set yourself up later for the easy shot
    - Coburn calls this "residue": the stuff that one team leaves behind for the next team
    - Residue includes:
        - Code
        - Process in place
        - Documentation

- I would argue that DHH/37signals has an oral form of documentation
- It works if the company doesn't grow too quickly
- What are we really asking for when we ask for the documentation: Tacit Knowledge
    - "That which is seen but not noticed"
    - It is information that is understood and implied but not stated
    - If you've ever brought someone else onto a team, you spend a lot of time
      explaining things that are obvious to you
    - You might not explain that stuff if you're doing it on paper
    - You don't want to end up in a situtation where there's too much documentation

- What can we borrow from software engineering principles?
    - Orthogonality
        - A good thing in software development
        - Intersect at a clear and obvious point and do not influence each other at any other point
    - Cohesion
        - All attributes and methods are related to the essence of the class
        - Don't have people look in 5 different places to get the answer to a single question
    - Coupling
        - The extent to which one thing is dependent on each other

- To the future
    - 5 years ago, unit testing was unheard of in the web development world
    - Rails and similar projects have helped popularize unit testing
    - We've moved from the point to where we say "testing is awesome"
    - Testing is now a core value
    - Can we make documentation a core value?

- Agile documentation processes
    - Large companies are good at this; open source people not so good
    - Looking to Rails:
        - Documentaton conventions?
        - What if we had 5 steps for writing documentation that did 70% of the work?
    - Can we integrate documentation with code?
        - In many cases, the docs exist as a Word document
        - A step up is to use a Wiki -- support for multiple authors, versioning, linking
        - Can we put docs right in the codebase?
        - Every Rails app has a doc directory -- can we use that?
        - We test code -- is there a way to make testable documentation?
        - What if we could tag a method and class with a keyword and make that keyword appear in the docs?
          -- We could generate an alert when changes happen

Checking Out the Rich Media Institute

After the presentation, which was held in the Rich Media Institute’s basement-level lecture room, a number of us headed upstairs to check out its main floor. If you’re a techie with a creative bent, this place is like a candy store. The front part is a store full of books, t-shirts, music and other goodies that new media creators and aficionados would love, while the back is a gallery for local interactive artists’ works.

I took some photos of the place and posted them in the gallery below. Click on any of the thumbnails to see a larger version of the picture:

After “a much-needed summer hiatus” (which you can read as “the complete implosion of Toronto’s worst-run software development shop, which used to host the event”) Ruby on Rails Project Night makes its comeback this Friday, September 19th at its new home at the Rich Media Institute in Kensington Market.

Event organizer Corina Newby promises that it won’t normally be on Fridays, which should the minds of your significant others, party-going friends or World of Warcraft clans at ease. The event is being held on a Friday this time to accommodate the schedule of special guest James “Smalltalk Tidbits, Industry Rants” Robertson, who’ll be there to give us a presentation of the Smalltalk-based web application framework Seaside and the Seaside-based Smalltalk development environment WebVelocity.

Also scheduled is local Ruby on Rails developer Paul Doerwald, who’ll be doing a presentation on insights he gained from working with ActiveRecord validation.

As always, one of the greatest benefits of these gatherings is actually meeting local developers who work with or are interested in working with Ruby and Rails. It’s good for you, your software development career and the future of Accordion City as a hub for high-tech when gatherings like this take place, so be a part of it!

By the way, did I mention that the event is FREE?

Once again, the date is this Friday, September 19th at the Rich Media Institute (156 Augusta Avenue). The presentations will start at 6 p.m. and run until about 7:30. If you’re planning to attend, let Corina know at corecorina@hotmail.com.

The computer science student phase of my academic career (the less said about the previous phase, in which I was an electrical engineering student, the better) ran from 1991 to a successful conclusion in 1994.

If you are like me, you strongly connect memories with the music of the time; you could say that my computer science student phase ran from the time of Nirvana’s Nevermind and Soundgarden’s Badmotorfinger to Green Day’s Dookie and The Offspring’s Smash. Let’s just say that I often showed up to my classes and labs in a flannel shirt.

(If that last paragraph makes you think “Whoa, that was a long time ago!”, you’ll be blown away by the fact that the initial work on C ran from the time of the Beatles’ Abbey Road to Led Zeppelin’s Houses of the Holy. A fair number of you probably weren’t even born then.)

My Student Language of Choice

I don’t know what the situation was like at other schools, but at the time, computer science students at Crazy Go Nuts University were allowed to hand in programming assignments using the following languages:

• Pascal
• Turing
• C

(Remember, there was no Java back then. The Green Project, from which the language/platform sprang, was still ongoing at this time, and Java was still going by its “Oak” codename.)

The general recommendation that came from most of my professors was to use Turing. They told us that it was a kinder, gentler language than Pascal and even more so than C, which they implied was designed by dyslexic aliens. When some of us suggested that it might be better to use a language that saw actual use in the real world, many of them countered with the argument that learning principles of computing was more important than learning specific languages. We might’ve responded by pointing out that one of our professors was a co-creator of Turing and probably got a vig for every Turing installation (it was a commercial language), but that might have been an academic career-limiting move.

I ignored their recommendations and went with C. In the lab, I used good ol’ cc. At home, it was Turbo C at first, and later, when I got my first Mac (a Quadra 660AV bought with money from DJing), Think C.

I never used C in my professional career. My first job out of school took me away from a world where input and output was all printf() and scanf() to interactive CD-ROMs and Macromedia Director (now Adobe Director and 7 versions later), and after that, the languages remained pretty high level: Visual Basic, Python, Java, C#, NSBasic, PHP and Ruby, with only a slight detour through through Visual C++ and C++Builder.

My C Books Back Then

It’s almost impossible to talk about C without mentioning “K&R”, the nickname for what is considered to be the official bible of C, The C Programming Language, which was written by Brian Kernighan and Dennis Ritchie. The latest edition of the book — the second edition — is a bit long in the tooth as it was written in 1988, but for the most part, everything in this book should still apply to the current C99 standard.

I never owned a copy of the book in my student days. I signed it out when necessary from the electrical engineering/computer science library in Walter Light Hall. I did own a copy for a brief period in 2002 when my deadbeat ex-housemate left a lot of his stuff behind, but I sold it (along with most of his stuff) in order to recoup some of the money lost from his stiffing me on rent, utilities, groceries and the largest domestic phone bill I’ve ever grappled with.

The books I had while at Crazy Go Nuts University were the second edition of A Book on C and Understanding C Pointers (a book that seems to be no longer in print). I liked A Book on C enough to pick up the fourth edition on sale a couple of years ago, and someone out there has forgotten to give me back my copy of Understanding C Pointers (you know who you are!).

Back to C

I’ve decided to get back into C for a number of reasons.

I have to admit that one of those reasons is completely irrational: it’s ego. There’s certain geek cred that comes with having at least some proficiency in C. While I had those bragging rights back in school, I can’t honestly claim them now; I haven’t even written a file whose name ends in .c in over a decade. Luckily, I had a pretty good grasp of C back in school, and the noodling I’ve been doing with good old gcc suggests that I’ve still got it, which is pretty reassuring.

I’ve also been meaning to do some development with things that are programmed in C or C dialects:

• The Arduino electronics prototyping platform has its own programming language based on C. I’ve been meaning to try out hardware hacking with the folks at the local group HacklabTO.
• I’ve also been thinking about putting together some Mac OS X and iPhone apps, which require Objective-C.
• I’ve even been thinking about doing some GTK noodling, which is done in good ol’ C.

Finally, there’s the matter of just making myself a better programmer by working in C by refreshing my knowledge of the low-level stuff that C requires you to work with, and also the “brain stretch” that comes with working with a language and environment (what with going back to strong typing, compiling and make) that I haven’t worked in for some time.

I’ll be doing some C coding in my spare time, as well as noodling with the Arduino programming languane and Objective-C, and I’ll be posting my notes, observations and experiences here. As I’m fond of saying on this blog, watch this space!

The next method I’m going to cover in Enumerating Enumerable — the series of articles in which I try to do a better job of documenting Ruby’s Enumerable module than Ruby-Doc.org does — is inject, a.k.a. reduce. Not only is it one of the trickiest methods to explain, it’s also one of the cornerstones of functional programming. I thought that I’d take a little time to explain what the function does.

inject

The term inject comes from Smalltalk and isn’t terribly descriptive. I remember reading the documentation for it and being all confused until I saw some examples. I then realized that I’d seen this function before, but under two different names.

reduce

Burning Man 1999: gratuitous nudity and even more gratuitous accordion!

The second name by which I encountered this function is reduce, and it was at Burning Man 1999. I was to start a new job the week after Burning Man, and I had to learn at least some basic Python by then. So along with my camping gear, accordion and a kilo of candy for barter, I also brought my laptop (a 233Mhz Toshiba Sattelite with a whopping 96MB of RAM) and O’Reilly’s Learning Python and noodled during the downtime (early morning and afternoon) on Python 1.6. When I got to covering the reduce function, I was confused until I saw some examples, after which I realized that I’d seen that function before, but under a different name.

(You may have also heard of reduce through Google’s much-vaunted MapReduce programming model.)

fold

The first name by which I encountered this function is fold, or more specifically, “fold left” or “foldl”, and it was at the “Programming Paradigms” course I took at Crazy Go Nuts University. “Programming Paradigms” was a second-year course and had the reputation of being the most difficult course in the computer science curriculum. The intended purpose of this course was to provide students with an introduction to functional programming (these days, they use Haskell and Prolog, back then, it was Miranda). Its actual effect was to make most of the students swear off functional programming for the rest of their lives.

In spite of the trauma from this course, I ended up remembering a lot from it that I was able to apply, first to Python and now to Ruby. One of these things is a cute little trick for cememnting in your mind what fold does.

What Ruby-doc.org Says

Before I cover that cute little trick, let’s take a look at what Ruby-doc.org’s documentation has to say about Enumerable’s inject method.

One thing you’ll find at Ruby-doc.org is that as of Ruby 1.8.7 and later, inject gained a synonym: the more familiar term reduce.

As for the description of the inject/reduce method, I don’t find it terribly helpful:

Combines all elements of enum by applying a binary operation, specified by a block or a symbol that names a method or operator.

If you specify a block, then for each element in enum<i> the block is passed an accumulator value (<i>memo) and the element. If you specify a symbol instead, then each element in the collection will be passed to the named method of memo. In either case, the result becomes the new value for memo. At the end of the iteration, the final value of memo is the return value fo the method.

If you do not explicitly specify an initial value for memo, then uses the first element of collection is used as the initial value of memo.

(Yes, those stray <i> tags are part of the text of the description for inject. Hopefully they’ll fix that soon.)

This confusing text becomes a little clearer with some examples. The most typical example of inject/reduce/fold in action is the classic “compute the sum of the numbers in this range or array” problem. There are a number of approaches you can take in Ruby, all of which use inject/reduce:

(1..8).reduce(:+)
=> 36

(1..8).reduce {|sum, number| sum += number}
=> 36

(1..8).reduce(0) {|sum, number| sum += number}
=> 36

The reduce method takes some kind of operation and applies it across the enumerable to yield a single result. In this case, the operation is addition.

Explaining how that operation is applied is a little trickier, but I do just that in the next section.

Demonstrating inject / reduce / fold With a Piece of Paper and Literal Folding

To explain what’s happening in the code above, I’m going to do use a piece of paper. I’ve folded it into 8 even sections and then numbered each section, as shown in the photo below:

Think of the paper as the range (1..8). We’re now going to compute the sum of the numbers in this range, step by step, using a literal fold — that is, by folding the paper. I’m going to start folding from the left side of the paper, and when I do, I’m going to add the numbers that I’m folding into each other.

In the first fold, I’m folding the number 1 onto the number 2. Adding these two numbers yields 3, which I write on the back of the fold:

For the second fold, I fold the first number 3 onto the second number 3. The sum of these two numbers is 6, and I write that on the back of the resulting fold:

I fold again: this time, it’s the number 6 onto the number 4, the sum of which is 10. I write that number down on the resulting fold:

Next, I fold 10 onto 5, yielding the number 15:

I then fold 15 onto 6, which gives me 21:

Next comes 21 folded onto 7, which makes for a sum of 28:

And finally, 28 folded onto 8, which gives us a final total of 36.

And there you have it: a paper-based explanation of inject/reduce/fold, as well as why I often refer to the operation as “folding”.

Once again, it’s Enumerating Enumerable time! This is the latest in my series of articles where I set out to make better documentation for Ruby’s Enumerable module than Ruby-Doc.org’s. In this installment — the seventeenth in the series — I cover the group_by method.

In case you missed any of the previous articles, they’re listed and linked below:

1. all?
2. any?
3. collect / map
4. count
5. cycle
6. detect / find
7. drop
8. drop_while
9. each_cons
10. each_slice
11. each_with_index
12. entries / to_a
13. find_all / select
14. find_index
15. first
16. grep

Enumerable#group_by Quick Summary

Enumerable#group_by and Arrays

When used on an array, group_by iterates through the array, passing each element to to the block. The result value of the block is the group into which the element will be placed.

Example 1

For the first example, I’ll use some code similar to the example given in Ruby-doc.org’s writeup of group_by:

(0..15).group_by {|number| number % 3}
=> {0=>[0, 3, 6, 9, 12, 15], 1=>[1, 4, 7, 10, 13], 2=>[2, 5, 8, 11, 14]}

In the code above, the numbers 0 through 15 are passed to the block, which receives each number as the parameter number. The group that each number is placed into is determined by the result value of the block, number % 3, whose result can be one of 0, 1 or 2. This means that:

• The resulting hash will have three groups, represented by the keys 0, 1 and 2
• The key 0’s corresponding value is an array containing the numbers in the range (0..15) that are evenly divisible by 3 (i.e. the numbers for which number % 3 is 0.
• The key 1’s corresponding value is an array containing the numbers in the range (0..15) that when divided by 3 leave a remainder of 1 (i.e. the numbers for which number % 3 is 1.
• The key 2’s corresponding value is an array containing the numbers in the range (0..15) that when divided by 3 leave a remainder of 2 (i.e. the numbers for which number % 3 is 2.

Example 2

In the first example, the keys in the resulting hash are the same type as the values in the array whose contents we’re grouping. In this example, I’ll show that the keys in the resulting hash don’t have to be the same type as the values in the array.

simpsons = %w(Homer Marge Bart Lisa Abraham Herb)
=> ["Homer", "Marge", "Bart", "Lisa", "Abraham", "Herb"]

simpsons.group_by{|simpson| simpson.length}
=> {5=>["Homer", "Marge"], 4=>["Bart", "Lisa", "Herb"], 7=>["Abraham"]}

In the code above, each Simpson name is passed to the block, which receives it as the parameter simpson. The block’s result is the length of simpson, and this result is the group into which the name will go.

In the resulting hash:

• Note that the keys are integers while the names in the groups are strings.
• The key 5’s array contains those names in Simpsons that are 5
  characters in length.
• The key 4’s array contains those names in Simpsons that are 4 characters in length.
• The key 7’s array contains those names in Simpsons that are 7 characters in length.

Example 3

In the previous two examples, the keys for the resulting array were calculated from the values in the initial array. In this example, I’ll demonstrate that the keys for the groupings can be determined in a completely arbitrary fashion that has nothing to do with the values:

# Put the Simpsons into randomly determined groups
simpsons.group_by{rand(3) + 1}
=> {3=>["Homer", "Bart", "Abraham", "Herb"], 1=>["Marge", "Lisa"]}

# Let's try that again. The results are very likely to be different:
simpsons.group_by{rand(3) + 1}
=> {1=>["Homer", "Bart"], 2=>["Marge", "Lisa", "Herb"], 3=>["Abraham"]}

# One more time!
simpsons.group_by{rand(3) + 1}
=> {2=>["Homer", "Bart", "Lisa"], 3=>["Marge", "Herb"], 1=>["Abraham"]}

Enumerable#group_by and Hashes

When used on a hash, group_by passes each key/value pair in the hash to the block, which you can “catch” as either:

1. A two-element array, with the key as element 0 and its corresponding value as element 1, or
2. Two separate items, with the key as the first item and its corresponding value as the second item.

Example 1

In this example, we’ll group the cast of Family Guy by the item that they’re bringing to a potluck dinner:

potluck = {"Peter" => "lasagna",
           "Lois"  => "potato salad",
           "Chris" => "lasagna",
           "Meg"   => "brownies",
           "Stewie" => "chateaubriand",
           "Brian" => "potato salad",
           "Evil Monkey" => "potato salad"}
=> {"Peter"=>"lasagna", "Lois"=>"potato salad", "Chris"=>"lasagna", "Meg"=>"brownies",
"Stewie"=>"chateaubriand", "Brian"=>"potato salad", "Evil Monkey"=>"potato salad"}

# Here's one way to do it:
potluck.group_by{|person, bringing| bringing}
=> {"lasagna"=>[["Peter", "lasagna"], ["Chris", "lasagna"]], "potato salad"=>[["Lois", "potato salad"],
["Brian", "potato salad"], ["Evil Monkey", "potato salad"]], "brownies"=>[["Meg", "brownies"]],
"chateaubriand"=>[["Stewie", "chateaubriand"]]}

# Here's another way to do it:
potluck.group_by{|person| person[1]}
=> {"lasagna"=>[["Peter", "lasagna"], ["Chris", "lasagna"]], "potato salad"=>[["Lois", "potato salad"],
["Brian", "potato salad"], ["Evil Monkey", "potato salad"]], "brownies"=>[["Meg", "brownies"]],
"chateaubriand"=>[["Stewie", "chateaubriand"]]}

Example 2

In the previous example, the groupings were based on a calculation performed on the objects in the original hash. In this example, the groupings will be random: a random number generator will determine whose car each potluck attendee will ride to the potluck dinner:

potluck.group_by {[:peters_car, :quagmires_car, :clevelands_car][rand(3)]}
=> {:peters_car=>[["Peter", "lasagna"], ["Chris", "lasagna"], ["Evil Monkey", "potato salad"]],
:quagmires_car=>[["Lois", "potato salad"], ["Meg", "brownies"], ["Stewie", "chateaubriand"]],
:clevelands_car=>[["Brian", "potato salad"]]}

# Let's try another random grouping
potluck.group_by {[:peters_car, :quagmires_car, :clevelands_car][rand(3)]}
=> {:peters_car=>[["Peter", "lasagna"], ["Meg", "brownies"]], :quagmires_car=>[["Lois", "potato salad"],
["Stewie", "chateaubriand"], ["Brian", "potato salad"], ["Evil Monkey", "potato salad"]],
:clevelands_car=>[["Chris", "lasagna"]]}

# One more time!
potluck.group_by {[:peters_car, :quagmires_car, :clevelands_car][rand(3)]}
=> {:peters_car=>[["Peter", "lasagna"], ["Chris", "lasagna"], ["Stewie", "chateaubriand"]],
:quagmires_car=>[["Lois", "potato salad"], ["Evil Monkey", "potato salad"]], :clevelands_car=>[["Meg", "brownies"],
["Brian", "potato salad"]]}

Welcome to another installment of Enumerating Enumerable, my series of articles in I attempt to do a better job of documenting Ruby’s Enumerable module than Ruby-Doc.org. In this installment, I cover the first method.

In case you missed any of the previous articles, they’re listed and linked below:

1. all?
2. any?
3. collect / map
4. count
5. cycle
6. detect / find
7. drop
8. drop_while
9. each_cons
10. each_slice
11. each_with_index
12. entries / to_a
13. find_all / select
14. find_index

Enumerable#first Quick Summary

Enumerable#first and Arrays

When used on an array without an argument, first returns the first item in the array:

posts = ["First post!", "Second post!", "Third post!"]
=> ["First post!", "Second post!", "Third post!"]

# What's the first item in posts?
posts.first
=> "First post!"

# Here's the equivalent using array notation:
posts[0]
=> "First post!"

When used on an array with an integer argument n, first returns an array containing the first n items in the original array:

# What are the first 2 items in posts?
posts.first 2
=> ["First post!", "Second post!"]

# Note that when you provide an argument of 1,
# the result is still an array -- with just one element.
# If you want a scalar, don't use an argument.
posts.first 1
=> ["First post!"]

# Here's the equivalent using array slice notation:
posts[0..1]
=> ["First post!", "Second post!"]

posts[0...2]
=> ["First post!", "Second post!"]

When used on an empty array, first returns:

• nil if no argument n is provided
• The empty array, [], if an argument n is provided

[].first
=> nil

[].first 2
=> []

Enumerable#first and Hashes

In Ruby 1.8 and previous versions, hash order is seemingly arbitrary. Starting with Ruby 1.9, hashes retain the order in which they were defined, which makes the first method a little more applicable.

When used on a hash without an argument, first returns the first item in the hash as a two-element array, with the key as the first element and the corresponding value as the second element.

# Let's see what stages of partying our friends are in
party_stages = {"Alice" => :party_mineral,
                "Bob"   => :party_animal,
                "Carol" => :party_reptile,
                "Dave"  => :party_vegetable}
=> {"Alice"=>:party_mineral, "Bob"=>:party_animal, "Carol"=>:party_reptile, "Dave"=>:party_vegetable}

# Who's the first partier and what state is s/he in?
party_stages.first
=> ["Alice", :party_mineral]

When used on a hash with an integer argument n, first returns an array containing the first n items in the hash, with each item represented as a two-element array:

party_stages.first 2
=> [["Alice", :party_mineral], ["Bob", :party_animal]]

# Note that when you provide an argument of 1,
# the result is still an array -- with just one element.
# If you want a scalar, don't use an argument.
party_stages.first 1
=> [["Alice", :party_mineral]]

When used on an empty hash, first returns:

• nil if no argument n is provided
• The empty array, [], if an argument n is provided

{}.first
=> nil

{}.first 2
=> []

Once again, it’s Enumerating Enumerable, my series of articles in which I attempt to outdo Ruby-Doc.org’s documentation of Ruby’s Enumerable module. In this article, I cover the find_index method, which was introduced in Ruby 1.9.

In case you missed any of the previous articles, they’re listed and linked below:

1. all?
2. any?
3. collect / map
4. count
5. cycle
6. detect / find
7. drop
8. drop_while
9. each_cons
10. each_slice
11. each_with_index
12. entries / to_a
13. find_all / select

Enumerable#find_index Quick Summary

Enumerable#find_index and Arrays

When used on an array, find_index passes each item in the array to the given block and either:

• Stops when the current item causes the block to return a value that evaluates to true (that is, anything that isn’t false or nil) and returns the index of that item, or
• Returns nil if there is no item in the array that causes the block to return a value that evaluates to true.

Some examples:

# How about an array of the name of the first cosmonauts and astronauts,
# listed in the chronological order of the missions?
mission_leaders = ["Gagarin", "Shepard", "Grissom", "Titov", "Glenn", "Carpenter",
"Nikolayev", "Popovich"]
=> ["Gagarin", "Shepard", "Grissom", "Titov", "Glenn", "Carpenter", "Nikolayev",
"Popovich"]

# Yuri Gagarin was the first in space
mission_leaders.find_index{|leader| leader == "Gagarin"}
=> 0

# John Glenn was the fifth
mission_leaders.find_index{|leader| leader == "Glenn"}
=> 4

# And James Tiberius Kirk is not listed in the array
kirk_present = mission_leaders.find_index{|leader| leader == "Kirk"}
=> nil

Enumerable#find_index and Hashes

When used on a hash, find_index passes each key/value pair in the hash to the block, which you can “catch” as either:

1. A two-element array, with the key as element 0 and its corresponding value as element 1, or
2. Two separate items, with the key as the first item and its corresponding value as the second item.

As with arrays, find_index:

• Stops when the current item causes the block to return a value that evaluates to true (that is, anything that isn’t false or nil) and returns the index of that item, or
• Returns nil if there is no item in the array that causes the block to return a value that evaluates to true.

Some examples:

require 'date'
=> true

# These are the names of the first manned spaceships and their launch dates
launch_dates = {"Kedr"              => Date.new(1961, 4, 12),
                "Freedom 7"         => Date.new(1961, 5, 5),
                "Liberty Bell 7"    => Date.new(1961, 7, 21),
                "Orel"              => Date.new(1961, 8, 6),
                "Friendship 7"      => Date.new(1962, 2, 20),
                "Aurora 7"          => Date.new(1962, 5, 24),
                "Sokol"             => Date.new(1962, 8, 11),
                "Berkut"            => Date.new(1962, 8, 12)}
=> {"Kedr"=>#<Date: 4874803/2,0,2299161>, "Freedom 7"=>#<Date: 4874849/2,0,2299161>,
"Liberty Bell 7"=>#<Date: 4875003/2,0,2299161>, "Orel"=>#<Date: 4875035/2,0,2299161>,
"Friendship 7"=>#<Date: 4875431/2,0,2299161>, "Aurora 7"=>#<Date: 4875617/2,0,2299161>,
"Sokol"=>#<Date: 4875775/2,0,2299161>, "Berkut"=>#<Date: 4875777/2,0,2299161>}

# Where in the list is John Glenn's ship, the Friendship 7?
launch_dates.find_index{|ship, date| ship == "Friendship 7"}
=> 4

# Where in the list is the first mission launched in August 1962?
launch_dates.find_index{|ship, date| date.year == 1962 && date.month == 8}
=> 6

# The same thing, expressed a little differently
launch_dates.find_index{|launch| launch[1].year == 1962 && launch[1].month == 8}
=> 6

Using find_index as a Membership Test

Although Enumerable has a method for checking whether an item is a member of a collection (the include? method and its synonym, member?), find_index is a more powerful membership test for two reasons:

1. include?/member? only check membership by using the == operator, while find_index lets you define a block to set up all sorts of tests. include?/member? asks “Is there an object X in the collection equal to my object Y?” while find_index can be used to ask “Is there an object X in the collection that matches these criteria?”
2. include?/member? returns true if there is an object X in the collection that is equal to the given object Y. find_index goes one step further: not only can it be used to report the equivalent of true if there is an object X in the collection that is equal to the given object Y, it also reports its location in the collection.

A quick example of this use in action:

# Once again, the mission leaders
mission_leaders = ["Gagarin", "Shepard", "Grissom", "Titov", "Glenn", "Carpenter",
"Nikolayev", "Popovich"]
=> ["Gagarin", "Shepard", "Grissom", "Titov", "Glenn", "Carpenter", "Nikolayev",
 "Popovich"]

# Yuri Gagarin is in the list
gagarin_in_list = mission_leaders.find_index {|leader| leader == "Gagarin"}
=> 0

# Captain James T. Kirk is not
kirk_in_list = mission_leaders.find_index {|leader| leader == "Kirk"}
=> nil

# gagarin_in_list is 0, which as a non-false and non-nil value evaluates as true.
# We can use it as both a membership test *and* as his location in the list.
p "Gagarin's there. He's number #{gagarin_in_list + 1} in the list." if gagarin_in_list
"Gagarin's there. He's number 1 in the list."
=> "Gagarin's there. He's number 1 in the list."

# kirk_in_list is nil, which is one of Ruby's two "false" values.
# Let's use it with the "something OR something else" idiom that
# many Ruby programmers like.
kirk_in_list || (p "You only *think* he wasn't there.")
"You only *think* he wasn't there."
=> "You only *think* he wasn't there."

Parts that Haven’t Been Implemented Yet

Ruby-Doc.org’s documentation is generated from the comments in the C implementation of Ruby. It mentions a way of calling find_index that is just like calling include?/member?:

# What the docs say (does not work yet!)
["Alice", "Bob", "Carol"].find_index("Bob")
=> 1

# What happens with the current version of Ruby 1.9
["Alice", "Bob", "Carol"].find_index("Bob")
ArgumentError: wrong number of arguments(1 for 0)
...

Ruby 1.9 is considered to be a work in progress, so I suppose it’ll get implemented in a later release.

code_swarm - Python from Michael Ogawa on Vimeo.

The intro for the video says:

In 1991, Guido van Rossum released his Python scripting language to the public.

This video will take you through the history of the project, compressed into a fraction of the time.

You will see the names of developers fade in and out of prominence, while the files they work on swirl around them.

Red files are core code. Blue files are documents. Yellow files are modules. The histogram on the bottom tracks the size and time of commits. When a person makes a commit, their name stands out. The files they commit also stand out. Files grow in size every time they are committed. Files and people gradually fade when there is no activity.

[Thanks to The War on Folly.]

We’re at lucky number 13 — the thirteenth article in the Enumerating Enumerable series, which covers the methods of Ruby’s Enumerable module. I started this series after being disappointed with the documentation at Ruby-Doc.org.

In this article, I’m covering the find_all — a.k.a. select — method.

In case you missed any of the previous articles, they’re listed and linked below:

1. all?
2. any?
3. collect / map
4. count
5. cycle
6. detect / find
7. drop
8. drop_while
9. each_cons
10. each_slice
11. each_with_index
12. entries / to_a

Enumerable#find_all / Enumerable#select Quick Summary

Enumerable#find_all / Enumerable#select and Arrays

When used on an array, find_all and its synonym select passes each item from the array to the block, returning an array containing only those elements in the original array for which the block returns a value that doesn’t evaluate to false.

If no item in the array causes the block to return a value that doesn’t evaluate to false, find_all/select returns an empty array.

In the examples that follow (which are based on my examples for the detect/find method), I’ll be using the find_all method. select does exactly the same thing; it’s just that I prefer find_all.

# Once again,  I shall establish my "old fart" credentials
classic_rock_bands = ["AC/DC", "Black Sabbath", "Queen", \
"Ted Nugent and the Amboy Dukes", "Scorpions", "Van Halen"]
=> ["AC/DC", "Black Sabbath", "Queen", "Ted Nugent and the Amboy Dukes",
"Scorpions", "Van Halen"]

# Of the bands in the array, which ones have
# a name longer than 8 characters?
classic_rock_bands.find_all {|band| band.length > 8}
=> ["Black Sabbath", "Ted Nugent and the Amboy Dukes", "Scorpions", "Van Halen"]

# Which ones have a name exactly 5 characters long?
classic_rock_bands.find_all {|band| band.length == 5}
=> ["AC/DC", "Queen"]

# If no band in the array meets the criteria,
# find_all returns an empty array.
# Which ones have names shorter than 5 characters?
classic_rock_bands.find_all {|band| band.length < 5}
=> []

Enumerable#find_all / Enumerable#select and Hashes

When used on a hash, find_all/select passes each key/value pair in the hash to the block, which you can “catch” as either:

1. A two-element array, with the key as element 0 and its corresponding value as element 1, or
2. Two separate items, with the key as the first item and its corresponding value as the second item.

As with arrays, find_all/select passes each item from the hash to the block, returning an array containing only those items in the original array for which the block returns a value that doesn’t evaluate to false.

Note that each item in the result array is a two-element array corresponding to an item from the original hash. In this array, element 0 contains the key and element 1 contains the corresponding value.

If no item in the hash causes the block to return a value that doesn’t evaluate to false, find_all/select returns an empty array.

years_founded = {"AC/DC" => 1973, \
                 "Black Sabbath" => 1968, \
                 "Queen" => 1970, \
                 "Ted Nugent and the Amboy Dukes" => 1967, \
                 "Scorpions" => 1965, \
                 "Van Halen" => 1972}
=> {"AC/DC"=>1973, "Black Sabbath"=>1968, "Queen"=>1970,
"Ted Nugent and the Amboy Dukes"=>1967, "Scorpions"=>1965, "Van Halen"=>1972}

# Ruby 1.9 preserves hash order so that hashes keep the order in which
# you defined them, while Ruby 1.8 puts them in some mysterious order.
# All these examples are in Ruby 1.9

# Which bands were founded in 1970 or later?
years_founded.find_all {|band| band[1] >= 1970}
=> [["AC/DC", 1973], ["Queen", 1970], ["Van Halen", 1972]]

# Here's another way of phrasing it:
years_founded.find_all {|band, year_founded| year_founded >= 1970}
=> [["AC/DC", 1973], ["Queen", 1970], ["Van Halen", 1972]]

# Which bands were founded after 1980?
years_founded.find_all {|band, year_founded| year_founded > 1980}
=> []

Last.fm’s Adrian Woodhead writes:

These 3 bears sit in a prominent position and watch our developer’s every move. When things are good we have a green bear gently glowing and purring, when changes are being processed a yellow bear joins the party, and if the build gets broken the growling evil red bear makes an appearance. The developer who broke things usually goes a similar shade of red while frantically trying to fix whatever was broken while the others chortle in the background.

I’ve been meaning to get back into a little hardware hacking (something I haven’t done since I was a teen) and learn how to build computer-driven gizmos like Last.fm’s bears. In the meantime, I’ll have to satisfy myself by page-slapping the development team at b5 with these images created by Big Swinging Developer…

You Broke the Build!

“Builds on My Machine…”

Where’s the Build?

Here’s number 11 in the Enumerating Enumerable series, in which I’m trying to outdo RubyDoc.org in their documentation of Ruby’s key Enumerable module. In this article, I cover the each_with_index method.

In case you missed the earlier articles, they’re listed and linked below:

1. all?
2. any?
3. collect / map
4. count
5. cycle
6. detect / find
7. drop
8. drop_while
9. each_cons
10. each_slice

Enumerable#each_with_index Quick Summary

Enumerable#each_with_index and Arrays

When used with on an array and given a block, each_with_index iterates through the array, passing each item in the array and the number representing its order in the array to the block. Once again, I’ll use the “Justice League” example:

justice_league = ["Aquaman", "Batman", "Black Canary", \
                  "Flash", "Green Arrow", "Green Lantern", \
                  "Martian Manhunter", "Superman", \
                  "Vixen", "Wonder Woman"]
justice_league = ["Aquaman", "Batman", "Black Canary", "Flash", "Green Arrow",
"Green Lantern", "Martian Manhunter", "Superman", "Vixen", "Wonder Woman"]

justice_league.each_with_index {|member, index| puts "#{index}: #{member}"}
=> 0: Aquaman
1: Batman
2: Black Canary
3: Flash
4: Green Arrow
5: Green Lantern
6: Martian Manhunter
7: Superman
8: Vixen
9: Wonder Woman
=> ["Aquaman", "Batman", "Black Canary", "Flash", "Green Arrow", "Green Lantern",
"Martian Manhunter", "Superman", "Vixen", "Wonder Woman"]

Note that unlike the each_cons and each_slice, each_with_index doesn’t return nil, but the original array, just like each does. each_cons and each_slice are newer methods that were introduced in Ruby 1.9; perhaps Matz and company decided that it made more sense for “each” methods to return nil from now on. each and each_with_index have return the original array as they always have, since making changes to these methods might break a lot of existing Ruby code. Hooray for those little inconsistencies that creep into every programming language!

Enumerable#each_with_index and Hashes

When used with on a hash and given a block, each_with_index iterates through the hash, converting each item in the hash into a two-element array (where the first element is the key and the second element is the corresponding value), and then passing that array and the number representing its order in the original array to the block. Once again, I’ll use the “Enterprise Crew” example:

enterprise_crew = {:captain => "Picard",
                   :first_officer => "Riker",
                   :science_officer => "Data",
                   :tactical_officer => "Worf",
                   :chief_engineer => "LaForge",
                   :chief_medical_officer => "Crusher",
                   :ships_counselor => "Troi",
                   :annoying_ensign => "Crusher",
                   :attractive_ensign => "Ro",
                   :expendable_crew_member => "Smith"}
=> {:captain=>"Picard", :first_officer=>"Riker", :science_officer=>"Data",
:tactical_officer=>"Worf", :chief_engineer=>"LaForge",
:chief_medical_officer=>"Crusher", :ships_counselor=>"Troi",
:annoying_ensign=>"Crusher", :attractive_ensign=>"Ro",
:expendable_crew_member=>"Smith"}

enterprise_crew.each_with_index {|member, index| puts "#{index}: #{member}"}
=> 0: [:captain, "Picard"]
1: [:first_officer, "Riker"]
2: [:science_officer, "Data"]
3: [:tactical_officer, "Worf"]
4: [:chief_engineer, "LaForge"]
5: [:chief_medical_officer, "Crusher"]
6: [:ships_counselor, "Troi"]
7: [:annoying_ensign, "Crusher"]
8: [:attractive_ensign, "Ro"]
9: [:expendable_crew_member, "Smith"]
=> {:captain=>"Picard", :first_officer=>"Riker", :science_officer=>"Data",
:tactical_officer=>"Worf", :chief_engineer=>"LaForge",
:chief_medical_officer=>"Crusher", :ships_counselor=>"Troi",
:annoying_ensign=>"Crusher", :attractive_ensign=>"Ro",
:expendable_crew_member=>"Smith"}

Enumerable#each_with_index Oddities

Blocks with a Single Parameter

What happens if you use each_with_index with a block that has only one parameter? You’d think that the block would accept the item and index passed to it as a two-element array, with the item as the first element and the corresponding index as the second element, but that’s not the case:

# For each item in justice_league, this line will output the following:
# {second letter of member's name} : {first letter of member's name}
justice_league.each_with_index {|member| puts "#{member[1]}: #{member[0]}"}
=> q: A
a: B
l: B
l: F
r: G
r: G
a: M
u: S
i: V
o: W
=> ["Aquaman", "Batman", "Black Canary", "Flash", "Green Arrow", "Green Lantern"
, "Martian Manhunter", "Superman", "Vixen", "Wonder Woman"]

When each_with_index passes an item and its index to a block that takes only one parameter, the item goes into the paramter, and the index is discarded. Simply put, in this case, each_with_index behaves just like each.

Without a Block

What happens if you use each_with_index without a block to create an Enumerator object that spits out the next item when its next method is called? This:

hero = justice_league.each_with_index
=> #<Enumerable::Enumerator:0x159cb98>

hero.next
=> "Aquaman"

hero.next
=> "Batman"

hero.next
=> "Black Canary"

Note that calling next only yields the next item in the collection; the index information is lost. In this case, each_with_index behaves just like each.

Hampton “HAML” Catlin of Unspace (you know, the development shop that put RubyFringe together) has created a survey that he’d like as many people who code in Ruby to take. It’s quick and painless, and he’ll share the data once he’s compiled it.

Ten installments already? That’s right, this is the tenth Enumerating Enumerable article. As I’m fond of repeating, this is my little contribution to the Ruby community: a series of articles where I attempt to do a better job at documenting Ruby’s Enumerable module than Ruby-Doc.org does, with pretty pictures and more in-depth examples!

In this article, I’m going to cover each_slice, which got introduced in Ruby 1.9.

If you missed any of the earlier articles, I’ve listed them all below:

1. all?
2. any?
3. collect / map
4. count
5. cycle
6. detect / find
7. drop
8. drop_while
9. each_cons

Enumerable#each_slice Quick Summary

Enumerable#each_slice and Arrays

When used on an array with a block, each_slice takes a numeric argument n and splits the array into slices of length n (if the number of elements in the array isn’t evenly divisible by n, the remaining elements are put into the last slice). each_slice then iterates through the set of slices, passing each slice to the block. After the final iteration, each_slice returns nil.

Since this is yet another case when an showing an example makes things very clear, I’ll do just that, using the same example data I used in the article on each_cons:

justice_league = ["Aquaman", "Batman", "Black Canary",
                  "Flash", "Green Arrow", "Green Lantern",
                  "Martian Manhunter", "Superman",
                  "Vixen", "Wonder Woman"]
justice_league = ["Aquaman", "Batman", "Black Canary", "Flash", "Green Arrow",
"Green Lantern", "Martian Manhunter", "Superman", "Vixen", "Wonder Woman"]

justice_league.each_slice(3) {|team| p team}
=> ["Aquaman", "Batman", "Black Canary"]
["Flash", "Green Arrow", "Green Lantern"]
["Martian Manhunter", "Superman", "Vixen"]
["Wonder Woman"]
=> nil

When used on an array without a block, each_slice takes a numeric argument n and returns an Enumerator that outputs slices of the array when its next method is called. Here’s an example:

teams_of_3 = justice_league.each_slice(3)
=> #<Enumerable::Enumerator:0x007fc73baa9830>

teams_of_3.next
=> ["Aquaman", "Batman", "Black Canary"]

teams_of_3.next
=> ["Flash", "Green Arrow", "Green Lantern"]

teams_of_3.next
=> ["Martian Manhunter", "Superman", "Vixen"]

teams_of_3.next
=> ["Wonder Woman"]

teams_of_3.next
=> StopIteration: iteration reached at end...
# (I'm skipping the rest of the error message)

teams_of_3.rewind
=> #<Enumerable::Enumerator:0x007fc73baa9830>

teams_of_3.next
=> ["Aquaman", "Batman", "Black Canary"]

Enumerable#each_slice and Hashes

When used on an hash with a block, each_slice takes a numeric argument n and splits the hash into arrays of length n (if the number of elements in the array isn’t evenly divisible by n, the remaining elements are put into the last slice). Within these arrays, each hash element is represented as a two-element array, with the first element being the key and the second element being the corresponding value.

each_slice then iterates through the set of arrays, passing each array to the block. After the final iteration, each_slice returns nil.

Here’s an example, using the same example data I used in the article on each_cons:

enterprise_crew = {:captain => "Picard",
                   :first_officer => "Riker",
                   :science_officer => "Data",
                   :tactical_officer => "Worf",
                   :chief_engineer => "LaForge",
                   :chief_medical_officer => "Crusher",
                   :ships_counselor => "Troi",
                   :annoying_ensign => "Crusher",
                   :attractive_ensign => "Ro",
                   :expendable_crew_member => "Smith"}
=> {:captain=>"Picard", :first_officer=>"Riker", :science_officer=>"Data",
:tactical_officer=>"Worf", :chief_engineer=>"LaForge",
:chief_medical_officer=>"Crusher", :ships_counselor=>"Troi",
:annoying_ensign=>"Crusher", :attractive_ensign=>"Ro",
:expendable_crew_member=>"Smith"}
=> nil

enterprise_crew.each_slice(3) {|team| p team}
=> [[:captain, "Picard"], [:first_officer, "Riker"], [:science_officer, "Data"]]
[[:tactical_officer, "Worf"], [:chief_engineer, "LaForge"],[:chief_medical_officer, "Crusher"]]
[[:ships_counselor, "Troi"], [:annoying_ensign, "Crusher"], [:attractive_ensign,  "Ro"]]
[[:expendable_crew_member, "Smith"]]
=> nil

When used on a hash without a block, each_slice takes a numeric argument n and returns an Enumerator that outputs arrays when its next method is called. Here’s an example:

away_teams_of_3 = enterprise_crew.each_slice(3)
=> #<Enumerable::Enumerator:0x007fc73ba44c50>

away_teams_of_3.next
=> [[:captain, "Picard"], [:first_officer, "Riker"], [:science_officer, "Data"]]

away_teams_of_3.next
=> [[:tactical_officer, "Worf"], [:chief_engineer, "LaForge"], [:chief_medical_officer, "Crusher"]]

away_teams_of_3.next
=> [[:ships_counselor, "Troi"], [:annoying_ensign, "Crusher"], [:attractive_ensign, "Ro"]]

away_teams_of_3.next
=> [[:expendable_crew_member, "Smith"]]

away_teams_of_3.next
=> StopIteration: iteration reached at end...
# (I'm skipping the rest of the error message)

away_teams_of_3.rewind
=> #

away_teams_of_3.next
=> [[:captain, "Picard"], [:first_officer, "Riker"], [:science_officer, "Data"]]

Welcome to the ninth installment of Enumerating Enumerable, the series of articles where I attempt to do a better job at documenting Ruby’s Enumerable module than Ruby-Doc.org does.

I’m going through the Enumerable’s methods in alphabetical order, and we’ve reached the methods that are variations on each In this article, I’m going to cover each_cons, which got introduced in Ruby 1.9.

If you missed any of the earlier articles, I’ve listed them all below:

1. all?
2. any?
3. collect / map
4. count
5. cycle
6. detect / find
7. drop
8. drop_while

Enumerable#each_cons Quick Summary

Enumerable#each_cons and Arrays

When used on an array and given a block and a number n as an argument, each_cons is like an each that goes through each element in the array and outputs an n-sized array slice of the original array starting at the current element.

each_cons is one of those methods that’s really tough to describe. This is one of those cases where a demonstrating trumps describing…

justice_league = ["Aquaman", "Batman", "Black Canary", \
                  "Flash", "Green Arrow", "Green Lantern", \
                  "Martian Manhunter", "Superman", \
                  "Vixen", "Wonder Woman"]
=> justice_league = ["Aquaman", "Batman", "Black Canary", "Flash", "Green Arrow",
"Green Lantern", "Martian Manhunter", "Superman", "Vixen", "Wonder Woman"]

justice_league.each_cons(3) {|team| p team}
=> ["Aquaman", "Batman", "Black Canary"]
["Batman", "Black Canary", "Flash"]
["Black Canary", "Flash", "Green Arrow"]
["Flash", "Green Arrow", "Green Lantern"]
["Green Arrow", "Green Lantern", "Martian Manhunter"]
["Green Lantern", "Martian Manhunter", "Superman"]
["Martian Manhunter", "Superman", "Vixen"]
["Superman", "Vixen", "Wonder Woman"]
=> nil

Note that in this case, each_cons returns nil.

each_cons can also be used without providing a block. In this case, you’re using it to create an Enumerator object that you can then use to spit out array slices when you call its next method:

# Let's create an enumerator that we can use to give us three-person
# superhero teams
teams_of_3 = justice_league.each_cons(3)
=> #

# Let's get the first team of 3
teams_of_3.next
=> ["Aquaman", "Batman", "Black Canary"]

# Now the next one...
teams_of_3.next
=> ["Batman", "Black Canary", "Flash"]

teams_of_3.next
=> ["Black Canary", "Flash", "Green Arrow"]

teams_of_3.next
=> ["Flash", "Green Arrow", "Green Lantern"]

# Let's go back to the first team of 3
teams_of_3.rewind
=> #

teams_of_3.next
=> ["Aquaman", "Batman", "Black Canary"]

Enumerable#each_cons and Hashes

When used on a hash and given a block and a number n as an argument, each_cons is like an each that goes through each element in the array and outputs an n-sized array slice of the hash starting at the current element. Note that in the process, hash elements are converted into two-element arrays where the first element contains the key and the second element contains the corresponding value.

Again, examples speak louder than descriptions:

enterprise_crew = {:captain => "Picard",
                   :first_officer => "Riker",
                   :science_officer => "Data",
                   :tactical_officer => "Worf",
                   :chief_engineer => "LaForge",
                   :chief_medical_officer => "Crusher",
                   :ships_counselor => "Troi",
                   :annoying_ensign => "Crusher",
                   :attractive_ensign => "Ro",
                   :expendable_crew_member => "Smith"}
=> {:captain=>"Picard", :first_officer=>"Riker", :science_officer=>"Data", :tact
ical_officer=>"Worf", :chief_engineer=>"LaForge", :chief_medical_officer=>"Crush
er", :ships_counselor=>"Troi", :annoying_ensign=>"Crusher", :attractive_ensign=>
"Ro", :expendable_crew_member=>"Smith"}

enterprise_crew.each_cons(3) {|team| p team}
=> [[:captain, "Picard"], [:first_officer, "Riker"], [:science_officer, "Data"]]
[[:first_officer, "Riker"], [:science_officer, "Data"], [:tactical_officer, "Worf"]]
[[:science_officer, "Data"], [:tactical_officer, "Worf"], [:chief_engineer, "LaForge"]]
[[:tactical_officer, "Worf"], [:chief_engineer, "LaForge"], [:chief_medical_officer, "Crusher"]]
[[:chief_engineer, "LaForge"], [:chief_medical_officer, "Crusher"], [:ships_counselor, "Troi"]]
[[:chief_medical_officer, "Crusher"], [:ships_counselor, "Troi"], [:annoying_ensign, "Crusher"]]
[[:ships_counselor, "Troi"], [:annoying_ensign, "Crusher"], [:attractive_ensig