Clojure Course - Function Signatures

Clojure Course

Part 5 - Function Signatures

So far we have seen functions that can take one, two or three arguments. Clojure is dynamically typed, so we cannot specify the types, only the names of the parameters, when declaring functions.

But we do make some assumptions about this. The number and order of the arguments is also important. For example, when we check the ClojureDocs of the filter function, the following two forms are listed:

(filter pred)
(filter pred coll)

This hints that we have to provide a predicate function and optionally a collection to use filter. The first form is also known as a transducer, an advanced concept that is used for building data pipelines.

Now we are going to explore some of the rules that govern the function signatures.

Variadic Functions

If we recall the + function (addition), we can figure out that it can be called with any number of arguments, even with zero arguments, and it will still work:

[(+)
 (+ 42)
 (+ -4 3)
 (+ 1 1 1 1 1 1 1)]

This type of function, that can take a variable number of arguments, is called a variadic function. Note that this is different from taking a collection as a single argument.

To create something like this, we use the & (ampersand) character before the last parameter.

(defn important [& words]
  (println "First word:" (first words))
  (println "And the rest:" (rest words)))

(do
  (important "SoloLearn" "is" "a" "cool" "place")
  (important))

As we can see, all the arguments passed after the function name, are captured in a sequence, the symbol words in the example above. It is common to use first and rest on the variadic parameter, potentially to call the same function recursively, with one less argument. The important function works even when called without arguments.

Note: first and rest work fine even when we use them on empty collections - they return nil and an empty sequence, respectively.

We can also capture other symbols before the variable parameter. This way we make it clear, what is the purpose of each parameter. In the next example, we use the first two numbers to perform an exponentiation, then multiply the result with the rest of the arguments.

(defn calculate [base exponent & nums]
  (map #(* % (Math/pow base exponent)) nums))

(do
  (println (calculate 7 2 1 2 3 4 5))
  (println (calculate 42)))

In this scenario we get a warning, if we try to call the function with less than 2 arguments.

Multi Arity Functions

Sometimes we want the function to present different behaviour when we pass different number of arguments. Arity of a function literally means how many parameters a function has. We can define multiple different implementations, based on the number of arguments, the following way:

(defn greet
  ([]
   (println "What's up, Doc?"))
  ([name]
   (println "Greetings," name))
  ([greeting name]
   (println (str greeting ", dear " name))))

(do
  (greet)                 ; no argument
  (greet "Citizen")       ; one argument
  (greet "Mr Tony Stark") ; one argument
  (greet "Good morning" "Sunshine")
  (greet "See you later" "Alligator"))

After the function name, we declare 3 different function bodies, each enclosed in a separate list, starting with the parameters. The number of parameters in each variant must be different. When calling the function, only one appropriate function body is executed, based on the actual number of arguments.

Sequential Destructuring

We can represent a point on the Euclidean plane by its two coordinates x and y. We could write a function, that calculates the distance from Origin, a couple of different ways:


; Two separate arguments
(defn distance1 [x y] (Math/sqrt (+ (* x x) (* y y))))

; A single vector
(defn distance2 [point]
  (let [x (first point) 
        y (second point)]
    (Math/sqrt (+ (* x x) (* y y)))))

; A vector destructured to two separate symbols
(defn distance3 [[x y]] (Math/sqrt (+ (* x x) (* y y))))

(do
  (println (distance1 3 4))    ; two values
  (println (distance2 [3 4]))  ; one vector
  (println (distance3 [3 4]))) ; one vector

In the first example we need to pass two separate values. It is simple, but does not really express the idea accurately, that the two values belong together and represent a point.
We fix this in the second version, by passing the two values as a vector [3 4], but this presents another challenge in the function body that we need to separate x and y with a let binding.
So the perfect solution is offered by argument destructuring as shown in the third example. With the function signature defn distance3 [[x y]] we express that the function expects a single collection as argument, which should have two values, and those will be assigned to the symbols x and y respectively, in the function body. The code is simple again, and the data structure explains the problem domain better.

Notice that x and y are enclosed in two pairs of brackets!

This is a very powerful technique to process even nested collections, and we can also use it inside let bindings. We can take the previous example one step further, to write a function that calculates the length of a line, as defined by two points. Here we destructure the 4 coordinates from a single collection of two vectors:

(defn line-length
  "The distance between any two points"
  [[[x1 y1] [x2 y2]]]
  (let [x (- x1 x2)
        y (- y1 y2)]
    (Math/sqrt (+ (* x x) (* y y)))))

(line-length [[1 7] [4 4]])

A single collection, containing 2 vectors with 2 values each, represents a line accurately in a single argument.

Some more advanced destructuring:

Using the :as keyword we can capture all the elements of a collection, even if we have already named some or all elements with unique symbols.
We can capture "remaining" elements using the & sign (as with variadic functions).

(def polyline [[-2 3] [4 0] [7 2] [5 -1]])
(let [[[x y :as p1] & points] polyline]
  (str "The first point is " p1
       " (x=" x ", y=" y ") "
       "and the rest: " points))

Associative Destructuring

So far we have seen destructuring dependent on the number and position of the elements within the collection. So the previous method works best with lists and vectors. But we can also do this with key-value pairs.

The next example shows how we can extract some values from an associative map, destructuring the map to symbols in a let binding.


(def smurfs {:boss  "Papa Smurf"
             :idol  "Smurfette"
             :home  "Smurf Village"
             :enemy "Gargamel"
             :food  "smurfberries"})
(let [{leader :boss villain :enemy} smurfs]
  (str leader " fights against " villain))

As we can observe, we use the syntax let [{symbol :keyword} map] to pull one value from the map and bind it to a symbol.

Of course we can do the same in function parameters. And another trick is to list the keywords we want to capture from the map, using the :keys keyword followed by a vector.

(defn who-am-i
  "Identify a fairy tale character"
  [{:keys [name job]}]
  (str name " works as a " job))

(who-am-i {:name "Geppetto" :son "Pinocchio" :job "woodcarver"})

Note: in the original map, we had keywords :name and :job (starting with a colon), but after destructuring, the values are bound to symbols name and job.

Other fun tricks include providing default values when a key doesn't exist in the map, and destructuring nested maps. You can check the Destructuring Guide for more details.

Next time we will look at the very exciting topic of concurrent and parallel programming, so stay tuned! :)

[Clojure] 05 Function Signatures