Using the Sequence Library

The Clojure sequence library provides a rich set of functionality that can work with any sequence. If you come from an object-oriented background where nouns rule, the sequence library is truly “Revenge of the Verbs.” The functions provide a rich backbone of functionality that can take advantage of any data structure that obeys the basic first/rest/cons contract.

The following functions are grouped into four broad categories:

• Functions that create sequences
• Functions that filter sequences
• Sequence predicates
• Functions that transform sequences

These divisions are somewhat arbitrary. Since sequences are immutable, most of the sequence functions create new sequences. Some of the sequence functions both filter and transform. Nevertheless, these divisions provide a rough road map through a large library.

Creating Sequences

Clojure provides a number of functions that create sequences. range produces a sequence from a start to an end, incrementing by step each time.

Ranges include their start but not their end. If you do not specify them, start defaults to zero, end defaults to positive infinity, and step defaults to 1. Try creating some ranges at the REPL:

The repeat function repeats an element x n times:

Try to repeat some items from the REPL:

Both range and repeat represent ideas that can be extended infinitely.

iterate begins with a value x and continues forever, applying a function f to each value to calculate the next.

If you begin with 1 and iterate with inc, you can generate the whole numbers:

Since the sequence is infinite, you need another new function to help you view the sequence from the REPL.

take returns a lazy sequence of the first n items from a collection and provides one way to create a finite view onto an infinite collection.

The whole numbers are a pretty useful sequence to have around, so let’s def them for future use:

When called with a single argument, repeat returns a lazy, infinite sequence:

Try repeating at the REPL. Don’t forget to wrap the result in a take:

The cycle function takes a collection and cycles it infinitely:

Try cycling some collections at the REPL:

The interleave function takes multiple collections and produces a new collection that interleaves values from each collection until one of the collections is exhausted.

When one of the collections is exhausted, the interleave stops. So, you can mix finite and infinite collections:

Closely related to interleave is interpose, which returns a sequence with each of the elements of the input collection segregated by a separator:

You can use interpose to build delimited strings:

interpose works nicely with (apply str ...) to produce output strings:

The (apply str (interpose separator sequence)) idiom is common enough that Clojure provides a performance-optimized version as clojure.string/join:

Use clojure.string/join to comma-delimit a list of words:

For each collection type in Clojure, there is a function that takes an arbitrary number of arguments and creates a collection of that type:

hash-set has a cousin set that works a little differently: set expects a collection as its first argument:

hash-set takes a variable list of arguments:

vector also has a cousin, vec, which takes a single collection argument instead of a variable argument list:

Now that you have the basics of creating sequences, you can use other Clojure functions to filter and transform them.

Filtering Sequences

Clojure provides a number of functions that filter a sequence, returning a subsequence of the original sequence. The most basic of these is filter:

filter takes a predicate and a collection and returns a sequence of objects for which the filter returns true (when interpreted in a Boolean context). You can filter the whole-numbers from the previous section to get the odd numbers or the even numbers:

You can take from a sequence while a predicate remains true with take-while:

For example, to take all the characters in a string up to the first vowel, we can define some useful helper functions:

Then use those predicates to take the characters from the string up to the first vowel:

A couple of interesting things are happening here:

• Sets act as functions that look up a value in the set and return either the value or nil if not found. So, you can read #{aeiou} as “the function that tests to see whether its argument is a vowel.”

• complement reverses the behavior of another function. Here we create consonant? by defining it as the function that is the complement of vowel?.

The opposite of take-while is drop-while:

drop-while drops elements from the beginning of a sequence while a predicate is true and then returns the rest. You could use drop-while to drop all leading non-vowels from a string:

split-at and split-with will split a collection into two collections:

split-at takes an index, and split-with takes a predicate:

All the take-, split-, and drop- functions return lazy sequences, of course.

Sequence Predicates

Filter functions take a predicate and return a sequence. Closely related are the sequence predicates. A sequence predicate asks how some other predicate applies to every item in a sequence. For example, the every? predicate asks whether some other predicate is true for every element of a sequence.

A lower bar is set by some:

some returns the first non-false value for its predicate or returns nil if no element matched:

Notice that some does not end with a question mark. some is not a predicate, although it’s often used like one. some returns the actual value of the first match instead of true. The distinction is invisible when you pair some with even?, since even? is itself a predicate. To see a non-true match, try using some with identity to find the first logically true value in a sequence:

A common use of some is to perform a linear search to see if a sequence contains a matching element, which is typically written as a set of a single element. For example to see if a sequence contains the value 3:

Note that the value returned is the value in the sequence, which would act as a truthy value if this was used as a conditional test.

The behavior of the other predicates is obvious from their names:

Not every whole number is even:

But it would be a lie to claim that not any whole number is even:

Note that we picked questions to which we already knew the answer. In general, you have to be careful when applying predicates to infinite collections. They might run forever.

Transforming Sequences

Transformation functions transform the values in the sequence. The simplest transformation is map:

map takes a source collection coll and a function f, and it returns a new sequence by invoking f on each element in the coll. You could use map to wrap every element in a collection with an HTML tag.

map can also take more than one collection argument. f must then be a function of multiple arguments. map will call f with one argument from each collection, stopping whenever the smallest collection is exhausted:

Another common transformation is reduce:

f is a function of two arguments. reduce applies f on the first two elements in coll and then applies f to the result and the third element, and so on. reduce is useful for functions that “total up” a sequence in some way. You can use reduce to add items:

or to multiply them:

You can sort a collection with sort or sort-by:

sort sorts a collection by the natural order of its elements, where sort-by sorts a sequence by the result of calling a-fn on each element:

If you don’t want to sort by natural order, you can specify an optional comparison function comp for either sort or sort-by:

The granddaddy of all filters and transformations is the list comprehension. A list comprehension creates a list based on an existing list, using set notation. In other words, a comprehension states the properties that the result list must satisfy. In general, a list comprehension will consist of the following:

• Input list(s)
• Placeholder bindings for elements in the input lists
• Predicates on the elements
• An output form that produces output from the elements of the input lists that satisfy the predicates

Of course, Clojure generalizes the notion of list comprehension to sequence comprehension. Clojure comprehensions use the for macro. Note that the list comprehension for has nothing to do with the for loop found in imperative languages.

for takes a vector of binding-form/coll-exprs, plus optional filter-exprs, and then yields a sequence of exprs.

List comprehension is more general than functions such as map and filter and can in fact emulate most of the filtering and transformation functions described earlier.

You can rewrite the previous map example as a list comprehension:

This reads almost like English: “For [each] word in [a sequence of words], format [according to format instructions].”

Comprehensions can emulate filter using a :when clause. You can pass even? to :when to filter the even numbers:

A :while clause continues the evaluation only while its expression holds true:

The real power of for comes when you work with more than one binding expression. For example, you can express all possible positions on a chessboard in algebraic notation by binding both rank and file:

Clojure iterates over the rightmost binding expression in a sequence comprehension first and then works its way left. Because rank is listed to the right of file in the binding form, rank iterates faster. If you want files to iterate faster, you can reverse the binding order and list rank first:

In many languages, transformations, filters, and comprehensions do their work immediately. Do not assume this in Clojure. Most sequence functions do not traverse elements until you actually try to use them.