Destructuring in Clojure

Destructuring is a way to concisely bind names to the values inside a data structure. Destructuring allows us to write more concise and readable code.

Consider the following example of extracting and naming values in a vector.

This is perfectly valid, but the code extracting and naming the values in the vector obscures our intent. Destructuring allows us to more concisely extract and name important parts of complex data structures to make our code cleaner.

Rather than explicitly binding each variable, we describe where the values for the bindings can be found, based on their sequential order.

We start with a data structure my-line that looks like [[5 10] [10 20]]. In the destructuring form we describe the structure of the data as a vector containing two elements, p1 and p2, each of which are vectors themselves. This form binds the vector [5 10] to the symbol p1 and the vector [10 20] to the symbol p2. Since we want to work with the elements of p1 and p2 rather than the structures themselves, we destructure p1 and p2 within the same let statement. The vector p1 looks like this, [5 10], so to destructure it, we describe its form as a vector containing two elements, x1 and y1. This binds 5 to the symbol x1 and 10 to the symbol y1. The same is repeated for p2 binding 10 to x2 and 20 to y2. At this point, we now have everything we need to work with our data.

An even more concise version of this would recursively destructure without needing to assign bindings for p1 or p2 at all:

Clojure destructuring is broken up into two categories, sequential destructuring and associative destructuring. Sequential destructuring represents a sequential data structure as a Clojure vector within a let binding.

This type of destructuring can be used on any kind of data structure that can be traversed in linear time, including lists, vectors, seqs, strings, arrays, and anything that supports nth.

The key to sequential destructuring is that you bind the values one-by-one to the symbols in the vector. For instance the vector [x y z] will match each element one-by-one with the list '(1 2 3).

In some cases, the collection you are destructuring isn’t the exact same size as the destructuring bindings. If the vector is too small, the extra symbols will be bound to nil. In general, if the binding form does not match a value, the binding will be nil.

On the other hand, if the collection is too large, the extra values are simply ignored.

Destructuring gives you total control over the elements that you choose to bind (or not) and how you bind them.

Many times, you don’t need access to every element in a collection, only certain ones.

Say you want to print the first element on one line and the remainder on another line.

This binding works but even using destructuring it’s pretty clunky. Instead we can use & to combine the tail elements into a sequence.

You can ignore bindings that you don’t intend on using by binding them to any symbol of your choosing.

The convention for this is to use an underscore like above.

You can use :as all to bind the entire vector to the symbol all.

Let’s stop for a bit and look a little further into the types of :as and &.

Here remaining is bound to a sequence containing the remaining elements of the numbers vector while all has been bound to the original vector. What happens when we destructure a string instead?

Here all is bound to the original structure (String, vector, list, whatever it may be) and x is bound to the character \C, and remaining is the remaining list of characters.

You can combine any or all of these techniques at the same time at your discretion.

Destructuring can also be nested to get access to arbitrary levels of sequential structure. Let’s go back to our vector from the very beginning, my-line.

This vector is comprised of nested vectors that we can access directly.

When you have nested vectors, you can use :as or & at any level as well.

Associative destructuring is similar to sequential destructuring, but applied instead to associative (key-value) structures (including maps, records, vectors, etc). The associative bindings are concerned with concisely extracting values of the map by key.

Let’s first consider an example that extracts values from a map without destructuring:

Note that each line of the let binding is essentially the same - it extracts a value from the map by the name of the key, then binds it to a local with the same name.

Below is a first example of doing the same thing with associative destructuring:

The destructuring form is now a map rather than a vector, and instead of a symbol on the left side of the let, we have a map. The keys of the map are the symbols we want to bind in the let. The values of the destructuring map are the keys we will look up in the associative value. Here they are keywords (the most common case), but they could be any key value - numbers, strings, symbols, etc.

Similar to sequential destructuring, if you try to bind a key that is not present in the map, the binding value will be nil.

Associative destructuring, however, also allows you to supply a default value if the key is not present in the associative value with the :or key.

The value for :or is a map where the bound symbol (here category) is bound to the expression "Category not found". When category is not found in client, it is instead found in the :or map and bound to that value instead.

In sequential destructuring, you generally bind unneeded values with an _. Since associative destructuring doesn’t require traversing the entire structure, you can simply omit any keys you don’t plan on using from the destructuring form.

If you need access to the entire map, you can use the :as key to bind the entire incoming value, just as in sequential destructuring.

The :as and :or keywords can be combined in a single destructuring.

You might have noticed that our original example still contains redundant information (the local binding name and the key name) in the associative destructuring form. The :keys key can be used to further remove the duplication:

This example is exactly the same as the prior version - it binds name to (:name client), location to (:location client), and description to (:description client).

The :keys key is for associative values with keyword keys, but there are also :strs and :syms for string and symbol keys respectively. In all of these cases the vector contains symbols which are the local binding names.

Associative destructuring can be nested and combined with sequential destructuring as needed.

You can utilize destructuring anywhere that there is an explicit or implicit let binding.

One of the most common places to see destructuring is in pulling apart the arguments passed to a function.

Here we have the standard let x equal this, let y equal that, etc…​ Again, this is perfectly valid code, it’s just verbose.

Any time we see code that is using first, second, nth, or get to pull apart a data structure, it’s likely that destructuring can clean that up - we can start by rewriting the let:

When defining a function in clojure, destructuring can be applied on the incoming parameters, just like in a let:

We have replaced several lines of code that pulled apart the incoming point data with a concise statement about the structure of that data that also binds the data to local values.

For a more realistic example, let’s create a map containing some basic contact information for the infamous John Smith.

Now that we have John’s personal information we need to access the values within this map.

This function will associatively destructure the input using the :keys shortcut and then print out the contact information that we provided.

But what about when we want to send John a nice letter?

We have an address in there now, but we needed to nest a map into our original structure in order to accomplish this.

Macro writers may find the need to write a macro that incorporates destructuring. The most common way to do so is to produce a call to something that already does destructuring (like let, loop, fn, etc). Some examples of this in clojure.core include if-let, when-let, when-some, etc.

However, in rare cases you might want to instead resolve the destructuring yourself in a macro. In this case, use the (undocumented) clojure.core/destructure function, which implements the destructuring logic and is what let and loop actually invoke. The destructure function is designed to be invoked in a macro and expects to take a form and return a form:

The result was formatted here to give it a little more clarity. This example should also give you some insight into how destructuring works under the hood.