Everything Is a Sequence

Every aggregate data structure in Clojure can be viewed as a sequence. A sequence has three core capabilities:

• You can get the first item in a sequence:

  ​	(first aseq)

  first returns nil if its argument is empty or nil.

• You can get everything after the first item—the rest of a sequence:

  ​	(rest aseq)

  rest returns an empty seq (not nil) if there are no more items.

• You can construct a new sequence by adding an item to the front of an existing sequence. This is called consing:

  ​	(cons elem aseq)

Under the hood, these three capabilities are declared in the Java interface clojure.lang.ISeq. (Keep this in mind when reading about Clojure, because the name ISeq is often used interchangeably with seq.)

The seq function will return a seq on any seq-able collection:

seq will return nil if its coll is empty or nil. The next function will return the seq of items after the first:

(next aseq) is equivalent to (seq (rest aseq)).

The seq functions work on lists:

The seq functions work on all other Clojure data structures as well. For example, you can use the seq functions on vectors:

When you apply rest or cons to a vector, the result is a seq, not a vector. In the REPL, seqs print just like lists, as you can see in the earlier output. You can check the actual returned type by using the seq? predicate:

The generality of seqs is very powerful, but sometimes you want to produce a specific implementation type. This is covered in ​Calling Structure-Specific Functions​.

You can treat maps as seqs, if you think of a map as a sequence of map entries (where each entry is a key/value pair):

You can also treat sets as seqs:

Maps and sets have a stable traversal order, but that order depends on implementation details, and you shouldn’t rely on it. Elements of a set will not necessarily come back in the order that you put them in:

If you want a reliable order, you can use this:

sorted-set will sort the values by their natural sort order:

Likewise, key/value pairs in maps won’t necessarily come back in the order you put them in:

You can create a sorted map with sorted-map:

sorted-maps won’t come back in the order you put them in either, but they will come back sorted by key:

In addition to the core capabilities of seq, two other capabilities are worth meeting immediately: conj and into.

conj adds one or more elements to a collection, and into adds all the items in one collection to another. Both conj and into add items at an efficient insertion spot for the underlying data structure. For lists, conj and into add to the front:

For vectors, conj and into add elements to the back:

Because conj (and related functions) do the efficient thing for the underlying data structure, you can often write code that is both efficient and completely decoupled from a specific underlying implementation.

The Clojure sequence library is particularly suited for large (or even infinite) sequences. Most Clojure sequences are lazy: they generate elements only when they are actually needed. Thus, Clojure’s sequence functions can process sequences too large to fit in memory.

Clojure sequences are immutable: they never change. This makes it easier to reason about programs and means that Clojure sequences are safe for concurrent access. It does, however, create a small problem for human language. English-language descriptions flow much more smoothly when describing mutable things. Consider the following two descriptions for a hypothetical sequence function triple:

• triple triples each element of a sequence.
• triple takes a sequence and returns a new sequence with each element of the original sequence tripled.

The latter version is specific and accurate. The former is much easier to read, but it might lead to the mistaken impression that a sequence is actually changing. Don’t be fooled: sequences never change. If you see the phrase “foo changes x,” mentally substitute “foo returns a changed copy of x.”