Clojure Cookbook

The book is composed of the following chapters:

Seeing that REPL-driven development is in vogue at present, it follows that this be a REPL-driven book. REPLs (read-eval-print loops) are interactive prompts that evaluate expressions and print their results. The Bash prompt, irb, and the python prompt are examples of REPLs. Nearly every recipe in this book is designed to be run at a Clojure REPL.

While Clojure REPLs are traditionally displayed as user=> ..., this book aims for readers to be able to copy and paste all of the examples in a recipe and see the indicated results. As such, samples omit user=> and comment out any output to make things easier. This is especially helpful if you’re following along on a computer: you can blindly copy and paste code samples without worrying about trying to run noncode.

When an example is only relevant in the context of a REPL, we will retain the traditional REPL style (with user=>). What follows is an example of each, a REPL-only sample and its simplified version.

Console sessions (e.g., shell commands) are denoted by monospace font, with lines beginning with a dollar sign ($) indicating a shell prompt. Output is printed without a leading $:

A backslash (\) at the end of a command indicates to the console that the command continues on the next line.

The following typographic conventions are used in this book:

The names of libraries follow one of two conventions: libraries with proper names are displayed in plain text (e.g., "Hiccup" or "Swing"), while libraries with names meant to mimic code symbols are displayed in constant-width text (e.g., core.async or clj-commons-exec).

First, a huge thanks to Luke. It was Luke who originally pitched the idea for the book, and I’m very grateful that he extended an invitation for me to join him in authoring it. They say the best way to learn something is to write a book on it—this couldn’t be any closer to the truth. Working on the book has really rounded out my Clojure skills and taken them to the next level.

And, most importantly, I have to thank my family for putting up with me through the process of writing the book. Getting this thing off the ground has been a Herculean task and I couldn’t have done it without the love and support of my wife Jackie and daughter Elody. If it hadn’t been for the hundreds upon hundreds of hours of evenings, weekends, and vacation time I usurped from them, I wouldn’t have been able to write this book.

Most of all, I’d like to thank my coauthor Ryan, who worked incredibly hard to make the book happen.

Also, all of my coworkers at Cognitect provided lots of thoughts and ideas, and most importantly were a sounding board for the many questions that arose during the writing and editing process. Many thanks for that, as well as for providing the opportunity to write code in Clojure all day, every day.

Almost every programming language knows how to work with and deal in strings. Clojure is no exception, and despite a few differences, Clojure provides the same general capabilities as most other languages. Here are a few key differences we think you should know about.

First, Clojure strings are backed by Java’s UTF-16 strings. You don’t need to add comments to files to indicate string encoding or worry about losing characters in translation. Your Clojure programs are ready to communicate in the world beyond A–Z.

Second, unlike languages like Perl or Ruby that have extensive string libraries, Clojure has a rather Spartan built-in string manipulation library. This may seem odd at first, but Clojure prefers simple and composable tools; all of the plethora of collection-modifying functions in Clojure are perfectly capable of accepting strings—they’re collections too! For this reason, Clojure’s string library is unexpectedly small. You’ll find that small set of very string-specific functions in the clojure.string namespace.

Clojure also embraces its host platform (the JVM) and does not duplicate functionality already adequately performed by Java’s java.lang.String class. Using Java interop in Clojure is not a failure—the language is designed to make it straightforward, and using the built-in string methods is usually just as easy as invoking a Clojure function.

We suggest you "require as" the clojure.string namespace when you need it. Blindly :use-ing a namespace is always annoying,
[By using use, you introduce numerous new symbols into your project’s namespaces without leaving any clues as to where they came from. This is often confusing and frustrating for maintainers of the code base. We highly suggest you avoid use.]
and often results in collisions/confusion. Prefixing everything with clojure.string is kind of odd, so we prefer to alias it to str or s:

The veneer between Clojure and Java is a little thicker over the numeric types. This isn’t necessarily a bad thing, though. While Java’s numeric types can be extremely fast or arbitrarily precise, numerics overall don’t have the prettiest set of interfaces to work with. Clojure unifies the various numeric types of Java into one coherent package, with clear escape hatches at every turn.

The recipes on numeric types in this chapter will show you how to work with these hatches, showing you how to be as fast or precise or expressive as you desire.

Dates and times have a long and varied history in the Java ecosystem. Do you want a Date, Time, DateTime, or Calendar? Who knows. And why are these APIs all so wonky? The recipes in this chapter should hopefully illuminate how and when to use the appropriate built-in types and when to look to an external library when built-ins aren’t sufficient (or are just too darned difficult to use).

You need to change the capitalization of a string.

Use clojure.string/capitalize to capitalize the first character in a string:

When you need to change the case of all characters in a string, use clojure.string/lower-case or clojure.string/upper-case:

Capitalization functions only affect letters. While the functions capitalize, lower-case, and upper-case may modify letters, characters like punctuation marks or digits will remain untouched:

Clojure uses UTF-16 for all strings, and as such its definition of what a letter is is liberal enough to include accented characters. Take the phrase "Hurry up, computer!" which includes the letter e with both acute (é) and circumflex (ê) accents when translated to French. Since these special characters are considered letters, it is possible for capitalization functions to change case appropriately:

You need to clean up the whitespace in a string.

Use the clojure.string/trim function to remove all of the whitespace at the beginning and end of a string:

To manage whitespace inside a string, you need to get more creative. Use clojure.string/replace to fix whitespace inside a string:

What constitutes whitespace in Clojure? The answer depends on the function: some are more liberal than others, but you can safely assume that a space ( ), tab (\t), newline (\n), carriage return (\r), line feed (\f), and vertical tab (\x0B) will be treated as whitespace. This set of characters is the set matched by \s in Java’s regular expression implementation.

Unlike Ruby and other languages that include string manipulation functions in the core namespace, Clojure excludes its clojure.string namespace from clojure.core, making it unavailable for naked use. A common technique is to require clojure.string as a shorthand like str or string to make code more terse:

You might not always want to remove whitespace from both ends of a string. For cases where you want to remove whitespace from just the left- or righthand side of a string, use clojure.string/triml or clojure.string/trimr, respectively:

You have multiple strings, values, or collections that you need to combine into one string.

Use the str function to concatenate strings and/or values:

Use apply with str to concatenate a collection of values into a single string:

Clojure’s str is like a good Unix tool: it has one job, and it does it well. When provided with one or more arguments, str invokes Java’s .toString() method on its argument, tacking each result onto the next. When provided nil or invoked without arguments, str will return the identity value for strings, the empty string.

When it comes to string concatenation, Clojure takes a fairly hands-off approach. There is nothing string-specific about (apply str ...). It is merely the higher-order function apply being used to emulate calling str with a variable number of arguments.

This apply:

is functionally equivalent to:

Since Clojure injects little opinion into joining strings, you’re free to inject your own with the plethora of manipulating functions Clojure provides. For example, take constructing a comma-separated value (CSV) from a header and a number of rows. This example is particularly well suited for apply, as you can prefix the header without having to insert it onto the front of your rows collection:

apply and interpose can be a lot of ceremony when you’re not doing anything too fancy. It is often easier to use the clojure.string/join function for simple string joins. The join function takes a collection and an optional separator. With a separator, join returns a string with each item of the collection separated by the provided separator. Without, it returns each item squashed together, similar to what (apply str coll) would return:

You need to work with the individual characters in a string.

Use seq on a string to expose the sequence of characters representing it:

You don’t need to call seq every time you want to get at a string’s characters, though. Any function taking a sequence will naturally coerce a string into a sequence of characters:

In computer science, "string" means "sequence of characters," and Clojure treats strings exactly as such. Because Clojure strings are sequences under the covers, you may substitute a string anywhere a collection is expected. When you do so, the string will be interpreted as a collection of characters. There’s nothing special about (seq string). The seq function is merely returning a seq of the collection of characters that make up the string.

More often than not, after you’ve done some work on the characters within a string, you’ll want to transform that collection back into a string. Use apply with str on a collection of characters to collapse them into a string:

You need to convert characters to their respective Unicode code points (as integer values), or vice versa.

Use the int function to convert a character to its integer value:

Use the char function to return a character corresponding to the code point specified by the integer:

Clojure inherits the JVM’s robust Unicode support. All strings are UTF-16 strings, and all characters are Unicode characters. Conveniently, the first 256 Unicode code points are identical to ASCII, which makes standard ASCII text easy to work with. However, Clojure (like Java) does not actually privilege ASCII in any way; the 1:1 correspondence between characters and integers indicating code points continues all the way up through the Unicode space.

For example, the expression (map char (range 0x0410 0x042F)) prints out all the Cyrillic capital letters, which happen to lie on that range on the Unicode spectrum:

The char and int functions are useful primarily for coercing a number into an instance of either java.lang.Integer or java.lang.Character. Both Integers and Characters are, ultimately, encoded as numbers, although Characters support additional text-related methods and cannot be used in mathematic expressions without first being converted to a true numeric type.

You need to insert values into a string, formatting how those values appear in the string.

The quickest method for formatting values into a string is the str function:

With str, however, values are inserted blindly, appearing in their default .toString() appearance. Not only that, but it can sometimes be difficult to look at a str form and interpret what the intended output is.

For greater control over how values are printed, use the format function:

When it comes to inserting values into a string, you have two very different options. You can use str, which is great for a quick fix but lacks control over how values are presented. Or you can use format, which exposes fine-grained control over how values are displayed but requires knowledge of C and Java-style formatting strings. Ultimately, you should use only as much tooling/complexity as is necessary for the task at hand: stick to str when the default formatting for a value will suffice, and use format when you need more control over how values display.

You need to test a string to see if parts of it match a pattern.

To check for the presence of a pattern inside a string, invoke re-find with a desired pattern and the string to test. Express the desired pattern using a regular expression literal (like "foo" or "\d+"):

re-find is quite handy for quickly testing a string for the presence of a pattern. It takes a regular expression pattern and a string, then returns either the first match of that pattern or nil.

If your criterion is more stringent and you require that the entire string match a pattern, use re-matches. Unlike re-find, which matches any portion of a string, re-matches matches if and only if the entire string matches the pattern:

You need to extract portions of a string matching a given pattern.

Use re-seq with a regular expression pattern and a string to retrieve a sequence of successive matches:

Regular expressions with matching groups (parentheses) will return a vector for each total match:

Provided a simple pattern (one without matching groups), re-seq will return a flat sequence of matches. Fully expressing the power of Clojure, this is a lazy sequence. Calling re-seq on a gigantic string will not scan the entire string right away; you’re free to consume those values incrementally, or defer evaluation to some other constituent part of your application further down the road.

When given a regular expression containing matching groups, re-seq will do something a little different. Don’t worry, the resulting sequence is still lazy—but instead of flat strings, its values will be vectors. The first value of the vector will always be the whole match, grouped or not; subsequent values will be the strings captured by matching group parentheses. These captured values will appear in the order in which their opening parentheses appeared, despite any nesting. Take a look at this example:

If all you’re looking for is a single match from a string, then use re-find. It behaves almost identically to re-seq, but returns only the first match as a singular value, instead of a sequence of match values.

Apart from re-seq, there is another way to iterate over the matches in a string. You could do this by repeatedly calling re-find on a re-matcher, but we don’t suggest this approach. Why? Because it isn’t very idiomatic Clojure. Mutating a re-matcher object with repeated calls to re-find is just wrong; it completely violates the principle of pure functions. We highly suggest you prefer re-seq over re-matcher and re-find unless you have a really good reason not to.

You need to modify portions of a string that match some well-defined pattern.

The versatile clojure.string/replace is the function you should reach for when you need to selectively replace portions of a string.

For simple patterns, use replace with a normal string as its matcher:

Plain string replacement will only get you so far. When you need to replace a pattern with some variability to it, you’ll need to reach for the big guns: regular expressions. Use Clojure’s regular expression literals (#"...") to specify a pattern as a regular expression:

As far as string functions go, replace is one of the more powerful and most complex ones. The majority of this complexity arises from the varying match and replacement types it can operate with.

When passed a string match, replace expects a string replacement. Any occurrences of match in the supplied string will be replaced directly with replacement.

When passed a character match (such as \c or \n), replace expects a character replacement. Like string/string, the character/character mode of replace replaces items directly.

When passed a regular expression for a match, replace gets much more interesting. One possible replacement for a regex match is a string, like in the linkify-comment example; this string interprets special character combinations like $1 or $2 as variables to be replaced by matching groups in the match. In the linkify-comment example, any contiguous digits (\d+) following a number sign (#) are captured in parentheses and are available as $1 in the replacement.

When passing a regex match, you can also provide a function for replacement instead of a string. In Clojure, the world is your oyster when you can pass a function as an argument. You can capture your replacement in a reusable (and testable) function, pass in different functions depending on the circumstances, or even pass a map that dictates replacements:

If you’ve not used regular expressions before, then you’re in for a treat. Regexes are a powerful tool for modifying strings with unbounded flexibility. As with any powerful new tool, it’s easy to overdo it. Because of their terse and compact syntax, it’s very easy to produce regexes that are both difficult to interpret and at a high risk of being incorrect. You should use regular expressions sparingly and only if you fully understand their syntax.

Jeffrey Friedl’s Mastering Regular Expressions, 3rd ed. (O’Reilly) is a fantastic book for learning and mastering regular expression syntax.

You need to split a string into a number of parts.

Use clojure.string/split to tokenize a string into a vector of tokens. split takes two arguments, a string to tokenize and a regular expression to split on:

In addition to just naively splitting on a regular expression, split allows you to control how many (or how few) times to split the provided string. You can control this with the optional limit argument. The most obvious effect of limit is to limit the number of values returned in the resulting collection. That said, limit doesn’t always work like you would expect, and even the absence of this argument carries a meaning.

Without limit, the split function will return every possible delimitation but exclude any trailing empty matches:

If you want absolutely every match, including trailing empty ones, then you can specify -1 as the limit:

Specifying some other positive number as a limit will cause split to return at maximum limit substrings:

You need to pluralize a word given some quantity, such as "0 eggs" or "1 chicken."

When you need to perform Ruby on Rails–style pluralization, use Roman Scherer’s inflections library.

To follow along with this recipe, start a REPL using lein-try:
[If you haven’t already installed lein-try, follow the instructions in [sec_lein_try].]

Use inflections.core/pluralize with a count to attempt to pluralize that word if the count is not one:

If you have a special or nonstandard pluralization, you can provide your own pluralization as an optional third argument to pluralize:

When it comes to user-facing text, inflection is key. Humanizing the output of your programs or websites goes a long way to building a trustworthy and professional image. Ruby on Rails set the gold standard for friendly and humanized text with its ActiveSupport::Inflections class. Inflections#pluralize is one such inflection, but Inflections is chock-full of cutesy-sounding methods ending in "ize" that change the inflection of strings. inflections provides nearly all of these capabilities in a Clojure context.

Two interesting functions in the inflections library are plural and singular. These functions work a bit like the upper-case and lower-case of pluralization; plural transforms words into their plural form, and singular coerces words to their singular form. These transformations are based on a number of rules in inflections.plural.

You can add your own rules for pluralization with inflections.core/plural!:

The library also has support for inflections like camelize, parameterize, and ordinalize:

You have a string, a symbol, or a keyword and you’d like to convert it into a different one of these string-like data types.

To convert from a string to a symbol, use the symbol function:

To convert from a symbol to a string, use str:

When you have a keyword and want a string, you can use name, or str if you want the leading colon:

To convert from a symbol or string to a keyword, use keyword:

You’ll need an intermediate step, through name, to go from keyword to symbol:

The primary conversion functions here are str, keyword, and symbol—each named for the data type it returns. One of these, symbol, is a bit more strict in terms of the input it allows: it must take a string, which is why you need the extra step in the keyword-to-symbol conversion.

There is another class of differences among these types: namely, that keywords and symbols may be namespaced, signified by a slash (/) in the middle. For these kinds of keywords and symbols, the name function may or may not be sufficient to convert to a string, depending on your use case:

Very often, you actually want both parts. You could collect them separately and concatenate the strings with a / in the middle, but there’s an easier way. Java has a rich set of performant methods for dealing with immutable strings. You can take the leading-colon string and lop off the first character with java.lang.String.substring(int):

See the java.lang.String API documentation for more string methods.

You can convert namespaced symbols to keywords just as easily as their non-namespaced counterparts, but again, converting in the other direction (keyword to symbol) takes an extra step:

And finally, both the keyword and symbol functions have two-argument versions that allow you to pass in the namespace and name separately. Sometimes this is nicer—for example, when you already have one or both of the values bound in a def, let, or other binding:

These three string-like data types are all great for different situations, and how to choose among them is another topic. But it’s quite common to need to convert among them, so keyword, symbol, str, namespace, and name are handy to have in your tool belt.

You need to work precisely with numbers, especially those that are very large or very small, without the imprecision implied by using floating-point representations such as double values.

First, know that Clojure supports exponents as literal numbers, allowing you to succinctly express large/small numbers:

Integer values passing the upper bound of a size-bounded type (like long) will raise an integer overflow error. Use the "quote" versions of numeric operations like - or * to allow promotion to Big types:

Clojure has a number of numeric types: integer and long, double, and BigInteger and BigDecimal. The bounded types (int, long, and double) all seamlessly transition as needed while inside the total bounds of those types. Exceeding those bounds causes one of two things to happen. For integers, an integer overflow error is raised. For floating-point numbers, the result will become Infinity. With integers, you can avoid this error by using quote versions of +, -, *, and /. These operations support arbitrary precision and will promote integers to BigInteger if necessary.

Floating-point values are a little more tricky. The quote versions of numeric operations won’t help here; you’ll need to infect your operations with the BigDecimal type. In Clojure, the BigInteger and BigDecimal types are what you would call "contagious." Once a "big" number is introduced to an operation, it infects all of the follow-on results. You could do something like multiplying a number by a BigDecimal 1, but it’s much easier to use the bigdec or bigint functions to promote a value manually:

Contagion doesn’t only occur with Big types; it also pops up in the integer-to–floating-point boundary. Floating-point numbers are contagious to integers. Arithmetic involving any floating-point values will always return a floating-point value.

You need to manipulate fractional numbers with absolute precision.

When manipulating integers (or other rationals), you can expect to maintain precision, including recurring fractions like 1/3 (0.333…):

Use rationalize on doubles to coerce them to rationals to avoid losing precision:

Clojure does its best to help you retain accuracy when working with numbers, especially integers. When dividing integers, Clojure maintains accuracy by expressing the quotient as an accurate ratio of integers instead of a lossy double. This accuracy isn’t without a cost, though; operations on rational numbers are much slower than operations on simpler types. As is discussed in [sec_primitives_math_arbitrary_precision], accuracy is always a trade-off for performance, and is something you need to consider given the problem at hand.

When operating on both doubles and rationals at the same time, care is advised; on account of the way type contagion works in Clojure, performing an operation over both types will cause the rational number to be coerced to a double. This transition isn’t necessarily inaccurate for a single operation, but the change in type introduces the possibility for inaccuracy to creep in.

To maintain accuracy when working with doubles, use the rationalize function. This function returns the rational value of any number. Calling rationalize on any values that might possibly be doubles will allow you to maintain absolute accuracy (at the cost of performance).

You need to parse numbers out of strings.

For "normal”-sized large or precise numbers, use Integer/parseInt or Double/parseDouble to parse them:

What is a "normal”-sized number? For Integer/parseInt, normal is anything below Integer/MAX_VALUE (2147483647); and for Double/parseDouble, it’s anything below Double/MAX_VALUE (around 1.79 × 10^308).functions

When the numbers you are parsing are either abnormally large or abnormally precise, you’ll need to parse them with BigInteger or BigDecimal to avoid losing precision. The versatile bigint and bigdec functions can coerce strings (or any other numerical types, for that matter) into infinite-precision containers:

You need to truncate or round a decimal number to a lower-precision number.

If the integer portion of a number is all you are concerned with, use int to coerce the number to an integer. Of course, this completely discards any decimal places without performing any rounding:

If you still value some level of precision, then rounding is probably what you’re after. You can use Math/round to perform simple rounding:

If you want to perform an unbalanced rounding, such as unconditionally "rounding up" or "rounding down," then you should use Math/ceil or Math/floor, respectively:

You’ll notice these functions return decimal numbers. Wrap calls to ceil or floor in int to return an integer.

One of the simplest ways to "round" numbers is truncation. int will do this for you, coercing floating-point numbers to integers by simply chopping off any trailing decimal places. This isn’t necessarily mathematically correct, but it is certainly convenient if it is accurate enough for the problem at hand.

Math/round is the next step up in rounding technology. As with many other primitive manipulation functions in Clojure, the language prefers not to reinvent the wheel. Math/round is a Java function that rounds by adding 1/2 to a number before dropping decimal places similarly to int.

For more advanced rounding, such as controlling the number of decimal places or complex rounding modes, you may need to resort to using the with-precision function. You likely already know BigDecimal numbers are backed by Java classes, but you might not have known that Java exposes a number of knobs for tweaking BigDecimal calculations; with-precision exposes these knobs.

with-precision is a macro that accepts a BigDecimal precision mode and any number of expressions, executing those expressions in a BigDecimal context tuned to that precision. So what does precision look like? Well, it’s a little strange. The most basic precision is simply a positive integer "scale" value. This value specifies the number of decimal places to work with. More complex precisions involve a :rounding value, specified as a key/value pair like :rounding FLOOR (this is a macro of course, so why not?). When not specified, the default rounding mode is HALF_UP, but any of the values CEILING, FLOOR, HALF_UP, HALF_DOWN, HALF_EVEN, UP, DOWN, or UNNECESSARY are allowed (see the RoundingMode documentation for more detailed descriptions of each mode):

One notable "gotcha" with with-precision is that it only changes the behavior of BigDecimal arithmetic, leaving regular arithmetic unchanged. You’ll have to introduce BigDecimal values into your expressions with literal values (3M), or by means of the bigdec function:

You need to test for equality with some tolerance for minute differences. This is especially a problem when comparing floating-point numbers, which are susceptible to "drift" through repeated operations.

Clojure has no built-in functions for fault-tolerant equality, or "fuzzy comparison," as it is often called. It’s trivial to implement your own fuzzy= function:

fuzzy= works like most other fuzzy comparison algorithms do: first it finds the absolute difference between the two operands; and second, it tests whether that difference falls beneath the given tolerance. Of course, there’s nothing dictating that the tolerance needs to be some minute fractional number. If you were comparing large numbers and wanted to ignore variations under a thousand, you could set the tolerance to 1000.

Even with fuzzy=, you still need to take care when comparing floating-point values, especially for values differing by numbers very close to your tolerance. At differences bordering the supplied tolerance, you may find the results a bit strange:

As odd as this is, this isn’t unexpected. The IEEE 754 specification for floating-point values is a purposefully limited format, a trade-off between accuracy and performance. If absolute precision is what you’re after, then you should be using BigDecimal or BigInt. See [sec_primitives_math_arbitrary_precision], for more information on those two types.

The fuzzy= function, as written, has a number of interesting side effects. First and foremost, having tolerance as the first argument makes it use partial to produce partially applied equals functions tuned to a specific tolerance:

What if you wanted to sort using fuzzy comparison? The sort function takes as an optional argument a predicate or comparator. Let’s write a function fuzzy-comparator that returns a comparator with a given tolerance:

You need to implement mathematical functions that require trigonometry.

All of the trigonometric functions are accessible via java.lang.Math, which is available as Math. Use them like you would any other namespaced function:

Trigonometric functions operate on values measured in radians. If you have values measured in degrees, such as latitude or longitude, then you’ll need to convert them to radians first. Use Math/toRadians to convert degrees to radians:

It may be surprising to some that Clojure doesn’t have its own internal math namespace, but why reinvent the wheel? Despite its tainted reputation, Java can perform, especially when it comes to math. Clojure’s Java interop forms and typing sugar make doing math using java.lang.Math almost pleasant.

java.lang.Math isn’t only for trigonometry. It also contains a number of functions useful for dealing with exponentiation, logarithms, and roots. A full list of methods is available in the java.lang.Math javadoc.

You need to enter numbers into a Clojure REPL or code in a different base (such as hexadecimal or binary).

Specify the base or radix of a literal number by prefixing it with the radix number (e.g., 2, 16, etc.) and the letter r. Any base from 2 to 36 is valid (there are, of course, 10 digits and 26 letters available):

To output integers, use the Java method Integer/toString:

Unlike the ordering of most Clojure functions, this method takes an integer first and the optional base second, making it hard to partially apply without wrapping it in another function. You can write a small wrapper around Integer/toString to accomplish this:

You need to calculate simple statistics like mean, median, mode, and standard deviation on a collection of numbers.

Find the mean (average) of a collection by dividing its total by the count of the collection:

Find the median (middle value) of a collection by sorting its values and getting its middle value. There are, of course, special considerations for collections of even length. In these cases, the median is considering the mean of the two middle values:

Find the mode (most frequently occurring value) of a collection by using frequencies to tally occurrences. Then massage that tally to retrieve the discrete list of modes:

Both mean and median are fairly easy to reproduce in Clojure, but mode requires a bit more effort. mode is a little different than mean or median in that it generally only makes sense for nonnumeric data. Calculating the modes of a collection is a little more involved and ultimately requires a good deal of processing compared to its numeric cousins.

Here is a breakdown of how mode works:

The standard deviation measures how much, on average, the individual values in a population deviate from the mean: the higher the standard deviation is, the farther away the individual values will be (on average). standard-deviation is a bit more mathematical than mean, median, and mode. Follow along the execution of this function step by step:

You need to perform bitwise operations on numbers.

Bitwise operations aren’t quite as commonly used in high-level languages (like Clojure) as they are in systems languages like C or C++, but the techniques learned in those systems languages can still be useful. Clojure exposes a number of bitwise operations in its core namespace, all prefixed with bit-. One place bitwise operations really shine is in compressing a large number of binary flags into a single value:

Clojure provides a full complement of bitwise operations in its core library. This includes the logic operations and and or, their negations, and shifts, to name a few. When working with bitwise operations, it can often be necessary to view the binary representation of an integer. Java’s Integer/toBinaryString can conveniently print out a binary representation of a number.

Interestingly enough, core also includes a bit-set and a bit-test. These two operations set or test an individual bit position in an integer. Instead of working in multiples of two, as is necessary for operations like bit-and, you can operate by the index of the flag you’re interested in. This drastically simplifies the preceding example:

You need to generate a random number.

Clojure makes available a number of pseudorandom number generating functions for your disposal.

For generating random floating-point numbers from 0.0 up to (but not including) 1.0, use rand:

For generating random integers, use rand-int:

In addition to generating a number from 0.0 to 1.0, rand also accepts an optional argument that specifies the exclusive maximum value. For example, (rand 5) would return a floating-point number ranging from 0.0 (inclusive) to 5.0 (exclusive).

(rand-int 5), on the other hand, would return a random integer between 0 (inclusive) and 5 (exclusive). At first blush, rand-int might seem like an ideal way to select a random element from a vector or list. This is a lot of ceremony, though. Use rand-nth instead to get a random element from any sequential collection (i.e., the collection responds to nth):

This won’t work for sets or hash maps, however. If you want to retrieve a random element from a nonsequential collection like a set, use seq to transform that collection into a sequence before calling rand-nth on it:

If you’re trying to randomly sort a collection, use shuffle to receive a random permutation of your collection:

You need to manipulate values that represent currency.

Use the Money library for representing, manipulating, and storing values in monetary units.

To follow along with this recipe, add [clojurewerkz/money "1.4.0"] to your project’s dependencies, or start a REPL using lein-try:

The clojurewerkz.money.amounts namespace contains functions for creating, modifying, and comparing units of currency:

Working with currency is serious business. Never trust built-in numerical types with handling currency, especially floating-point values. These types are simply not meant to capture and manipulate currency with the semantics and precision required. In particular, floating-point values of the IEEE 754 standard carry a certain imprecision by design:

You should always use a library custom-tailored for dealing with money. The Money library wraps the trusted and battle-tested Java library Joda-Money. Money provides a large amount of functionality beyond arithmetic, including rounding and currency conversion:

The round function takes four arguments. The first three are an amount of currency, a scale factor, and a rounding mode. The scaling factor is a somewhat peculiar argument. It might be familiar to you if you’ve ever done scaling with BigDecimal, which shares identical factors. A scale of -1 scales to the tens place, 0 scales to the ones place, and so on and so forth. Further details can be found in the javadoc for the rounded method of Joda-Money’s Money class. The final argument is a rounding mode, of which there are quite a few. :ceiling and :floor round toward positive or negative infinity. :up and :down round toward or away from zero. Finally :half-up, :half-down, and :half-even round toward the nearest neighbor, preferring up, down, or the most even neighbor.

clojurewerkz.money.amounts/convert-to is a much less complicated function. convert-to takes an amount of currency, a target currency, a conversion factor, and a rounding mode. Money doesn’t provide its own conversion factor, since conversion rates change so often, so you’ll need to seek out a reputable source for them. Unfortunately, we can’t help you with this one.

Money also provides support for a number of different persistence and serialization mediums, including Cheshire for converting to/from JSON and Monger for persisting currency values to MongoDB.

You need to generate a unique ID.

Use Java’s java.util.UUID/randomUUID to generate a universally unique ID (UUID):

Oftentimes when building systems, you want to assign unique IDs to objects and records. IDs are usually simple integers that monotonically increase with time. This isn’t without its problems, though.

You can’t mingle IDs of objects from different origins; and worse, they reveal information about the amount and input volume of your data.

This is where UUIDs come in. UUIDs, or universally unique identifiers, are 128-bit random numbers almost certainly unique across the entire universe. A bold claim, of course—see RFC 4122 for more detailed information on UUIDs, how they’re generated, and the math behind them.

You may have noticed Clojure prints UUIDs with a #uuid in front of them. This is a reader literal tag. It acts as a shortcut for the Clojure reader to read and initialize UUID objects. Reader literals are a lot like string or number literals like "Hi" or 42, but they can capture more complex data types.

This makes it possible for formats like edn (extensible data notation) to communicate in a common lingo about things like UUIDs without resorting to string interning and accompanying custom parsing logic.

You need to obtain the current date or time.

Use Java’s java.util.Date constructor to create a Date instance representing the present time and date:

If you’re more interested in the current Unix timestamp, use System/currentTimeMillis:

It doesn’t make much sense for Clojure to reimplement or wrap the JVM’s backing time and date functionality. As such, the norm is to use Clojure’s Java interop forms to instantiate a Date object representing "now."

#inst "2013-04-06T14:33:51.234-00:00" doesn’t look very much like Java, does it? That’s because Clojure’s "instant" reader literal uses java.util.Date as its backing implementation. You can learn more about the #inst reader literal in [sec_primitives_dates_reader_literal].

Using System/currentTimeMillis can be useful for performing a one-off benchmark, but given the high-quality tools out there that do this already, currentTimeMillis is of limited utility; you may want to try Hugo Duncan’s Criterium library if benchmarking is what you’re after. Additionally, you shouldn’t try to use currentTimeMillis as some sort of unique value—UUIDs do a much better job of this.

If you decide you would rather use clj-time to work with dates, it provides the function clj-time.core/now to get the current DateTime:

Use clj-time.local/local-now to retrieve a DateTime instance for the present scoped to your machine’s local time zone:

You need to represent instances of time in a readable and serializable form.

Use Clojure’s #inst literals in source to represent fixed points in time:

When communicating with other Clojure processes (or anything else that speaks edn), use clojure.edn/read to reify instant literal strings into Date objects:

In the preceding example, remote-server-receive-date emulates a communication channel upon which you may receive edn data.

Since Clojure 1.4, instants in time have been represented via the #inst reader literal. This means dates are no longer represented by code that must be evaluated, but instead have a textual representation that is both consistent and serializable. This standard allows any process capable of communicating in extensible data notation to speak clearly about instants of time. See the edn implementations list for a list of languages that speak edn; the list includes Clojure, Ruby, and JavaScript so far, with many more implementations in the works.

It’s also possible to vary how the reader evaluates #inst literals by changing the binding of *data-readers*. By varying the binding of *data-readers*, it is possible to read #inst literals as java.util.Calendar or java.sql.Timestamp, if you so desire:

You need to parse dates from a string.

Working directly with Java’s date and time classes is like pulling teeth. We suggest using clj-time, a Clojure wrapper over the excellent Joda-Time library.

Before starting, add [clj-time "0.6.0"] to your project’s dependencies or start a REPL using lein-try:

Use clj-time.format/formatter to create custom date/time representations capable of parsing candidate strings. Use the clj-time.format/parse function with those formatters to parse strings into DateTime objects:

The formatter function is a powerful little function that takes a date/time format string and returns an object capable of parsing date/time strings in that format. This format string can include any number of symbols representing portions of a time or date. Some example symbols include year ("yy" or "yyyy"), day ("dd"), or even a literal string like "on". The full list of these symbols is available in the Joda-Time DateTimeFormat javadoc.

More often than not, the dates and times you’re parsing may be strange, but not so strange that no one has seen them before. For this, clj-time includes a large number of built-in formatters. Use clj-time.format/show-formatters to print out a list of built-in formats and a sample date/time in each format. Once you’ve picked a suitable format, use clj-time.format/formatters with its keyword to receive the appropriate DateTimeFormatter.

By default, formatter always parses strings into DateTime objects with a UTC time zone. formatter optionally takes a time zone as its second argument. You can use clj-time.core/time-zone-for-offset or clj-time.core/time-zone-for-id to receive a DateTimeZone object to pass to formatter.

You need to print dates or times in a particular format.

While it is possible to format Java date–like instances (Date, Calendar, and Timestamp) with clojure.core/format, you should use clj-time to format dates.

Before starting, add [clj-time "0.6.0"] to your project’s dependencies or start a REPL using lein-try:

To output a date/time as a string, use clj-time.format/unparse with a DateTimeFormatter. There are a number of built-in formatters available via clj-time.format/formatters, or you can build your own with clj-time.format/formatter:

It is certainly possible to format pure Java dates and times; however, in our experience, it isn’t worth the hassle—the syntax is ugly, and the workflow is verbose. clj-time and its backing library Joda-Time have a track record for making it easy to work with dates and times on the JVM.

The formatter function is quite the gem. Not only does it produce a "format" capable of printing or unparseing a date, but it is also capable of parsing strings back into dates. In other words, DateTimeFormatter is capable of round-tripping from string to Date and back again. Much of how formatter and formatters work is covered in [sec_primitives_dates_parsing_dates].

One format symbol used less frequently in parsing is the textual day of the week (i.e., "Tuesday" or "Tue"). Use "E" in your format string to output the abbreviated day of the week, and "EEEE" for the full-length day of the week:

If you need to format native Java date/time instances, you can use the functions in the clj-time.coerce namespace to coerce any number of Java date/time instances into Joda-Time instances:

Similarly, you can use clj-time.coerce to coerce instances from Joda-Time instances into other formats:

You need to compare one date to another, or you need to sort a sequence of dates.

You can compare Java Dates using the compare function:

Why not just compare dates using Clojure’s built-in comparison operators (<=, >, etc.)? The problem with these operators is that they utilize clojure.lang.Numbers and attempt to coerce their arguments to numerical types.

Since regular comparison won’t work, it’s necessary to use the compare function. The compare function takes two arguments and returns a number indicating that the first argument was either less than (-1), equal to (0), or greater than (+1) the second argument.

Clojure’s sort functions use compare under the hood, so no extra work is required to sort a collection of dates:

If you’ve been doing more complex work with dates and times and have Joda-Time objects in hand, then all of this still applies. If you wish to compare Joda-Time objects to Java time objects, however, you will have to coerce them to one uniform type using the functions in clj-time.coerce.

You need to calculate the difference between two points in time.

Since Java date and time classes have poor support for time zones and leap years, use the clj-time library for calculating the length of a time interval.

Before starting, add [clj-time "0.6.0"] to your project’s dependencies or start a REPL using lein-try:

Use interval along with the numerous in-<unit> helper functions in the clj-time.core namespace to calculate the difference between times:

Calculating the length of an interval is one of the more complex operations you can perform with times. Time on Earth is a complex beast, complicated by constructs like leap time and time zones; clj-time is the only library we’re aware of that is capable of wrangling this complexity.

The clj-time.core/interval function takes two dates and returns a representation of that discrete interval of time. From there, the clj-time.core namespace includes a myriad of in-<unit> functions that can present that time interval in different units. These helpers run the gamut in scale from in-msecs to in-years, covering nearly every scale useful for nonspecialized applications.

One area clj-time lacks support is for leap seconds. Joda-Time’s official FAQ explains why the feature is missing. We’re not aware of any Clojure library that can reason about time at this granularity. If this concerns you, then you’re likely one of few people even capable of doing it right. Good luck to you.

You need to generate a lazy sequence covering a range of dates and/or times.

This problem has no easy solution in Java, nor does it have one in Clojure—third-party libraries included. It is possible to use clj-time to get close, though. By composing clj-time's Interval and periodic-seq functionality, you can create a function time-range that mimics range's capabilities, but for DateTimes:

This is how you can use the time-range function:

While there is no ready-made, out-of-the-box time-range solution in Clojure, it is trivial to construct such a function with purely lazy semantics. The basis for our lazy time-range function is an infinite sequence of values with a fixed starting time:

Invoking periodic-seq with start and step returns an infinite lazy sequence of values beginning at start, each subsequent value one step later than the last.

Having a lazy infinite sequence is one thing, but we need a lazy way to stop acquiring values when end is reached. The below-end? function created in let uses clj-time.core/interval to construct an interval from start to end and clj-time.core/within? to test if a time t falls within that interval. This function is passed as the predicate to take-while, which will lazily consume values until below-end? fails.

All together, time-range returns a lazy sequence of DateTime objects that stretches from a start time to an end time, stepped appropriately by the provided step value.

Imagine trying to build something similar in a language without first-class laziness.

You would like to generate a lazy sequence of dates (or times) beginning with a specific date and time. Further, unlike in [sec_primitives_dates_ranges], you would like to do this using only built-in types.

You can use Java’s java.util.GregorianCalendar class coupled with Clojure’s repeatedly function to generate a lazy sequence of Gregorian calendar dates. You can then use java.text.SimpleDateFormat to format the dates, with a huge variety of output formats available.

This example creates an infinite lazy sequence of Gregorian calendar dates,
["Gregorian" is the formal name for the style of calendar we all know and love. Read more on Wikipedia.]
beginning on January 1, 1970 and each spanning a single day. The core take and drop functions are then used to select the last two days of February (be careful not to evaluate the infinite sequence itself in the REPL):

Clojure has no date type of its own; by default, it relies on its ability to easily interoperate with Java (but see the clj-time library for alternatives to Java’s date, time, and calendar classes).

This solution is based on the core repeatedly function, which creates a lazy sequence by repeatedly calling the argument function it is given and returning a sequence of the function’s results. Because you do not provide the optional, limiting argument to repeatedly, the result sequences produced are infinite. Consequently, in the REPL environment, you must be careful to evaluate your result sequences in contexts (such as take and drop) that limit the values produced.

Since the function given to repeatedly is a function of no arguments, it is presumed to achieve its goals by side effects (making it an impure function). Here, the impurity occurs as the argument function creates a Gregorian calendar date and repeatedly increments it by a single java.util.Calendar day unit. For each call of the function, it returns a copy of the Gregorian calendar object (to avoid mysterious and unintended side effects, it is advisable to avoid returning the mutated object directly).

The date values in the result sequence are of type java.util.GregorianCalendar, but the print function of the REPL displays them as an #inst reader literal. You can verify that the sequence elements are Gregorian calendar objects by mapping the class (or type) function onto the sequence:

You can generalize the solution to a function that takes a starting year argument but defaults to some convenient year if the argument is not provided:

Using the java.text.SimpleDateFormat class, you can then format the dates in a wide variety of different formats:

To put it all together, create a function that generates an infinite lazy sequence of formatted Gregorian date strings. For convenience, the function takes optional starting year and date format string arguments:

To test the function, select the last Sunday of the year by finding all of the Sundays in a year:

You need to calculate a time relative to some other time, à la Ruby on Rails' 2.days.from_now.

Because relative time is such a complex beast, we suggest using clj-time for calculating relative dates and times.

Before starting, add [clj-time "0.6.0"] to your project’s dependencies or start a REPL using lein-try:

If you’ve used the Ruby on Rails framework, then you’re likely accustomed to statements like 1.day.from_now, 3.days.ago, or some_date - 2.years. You’ll be pleased to know that clj-time exposes similar functionality:

The clj-time.core functions from-now and ago are just syntactic sugar over plus and minus:

Despite how difficult dates and times can sometimes be in Java, clj-time manages to expose a joyful syntax for adding to and subtracting from dates.

The functions plus, minus, from-now, and ago all take a period of time and adjust a DateTime by that amount (be that time "now," as in from-now or ago, or some provided time).

clj-time.core includes a number of useful period helpers ranging from millis to years that produce a time period at a given scale.

Depending on your use case, it’s even possible to arrange operation, time period, and time in such a manner that they almost read like a sentence.

Take (-> 1 t/years t/from-now), for example. In this case, the threading macro -> threads each value as an argument to the next, producing (t/from-now (t/years 1)).

It’s up to you to arrange your function calls as you see fit, but know that it is quite possible to produce readable deep-nested calls like this.

You need to gracefully handle times and dates in a number of time zones.

The JVM’s built-in time and date classes don’t work well with the notion of time zones. For one, Date treats every value as UTC, and Calendar is cumbersome to work with in Clojure (or Java, for that matter). Use clj-time to properly deal with time zones.

Before starting, add [clj-time "0.6.0"] to your project’s dependencies or start a REPL using lein-try:

Unlike Java built-ins, clj-time knows a lot about time zones. Joda-Time, the library clj-time wraps, bundles the internationally recognized tz database. This database captures the IDs and time offsets for nearly every location on the planet.

The tz database also captures information about daylight saving time. For example, Los Angeles is UTC-08:00 in the winter and UTC-07:00 during the summer. This is accurately reflected when using clj-time:

The clj-time.core/from-time-zone function takes any DateTime and modifies its time zone to the desired time zone. This is useful in cases where you receive a date, time, and time zone separately and want to combine them into an accurate DateTime instance.

The clj-time.core/to-time-zone function has the same signature as from-time-zone; it returns a DateTime for the exact same point in time, but from the perspective of another time zone. This is useful for presenting time and date information from disparate sources to a user in her preferred time zone.

Sometimes you may only want to deal with machine-local time. The clj-time.local namespace provides a number of functions to that end, including local-now, for getting a time in the local time zone, and to-local-date-time, which shifts the perspective of a time to the local time zone.

You need to get a Date object from a Unix timestamp.

When dealing with data from outside systems, you’ll find that many systems express timestamps in Unix time format. You may encounter this when dealing with certain datastores, parsing out data from timestamps in log files, or working with any number of other systems that have to deal with dates and times across multiple different time zones and cultures.

Fortunately, with Clojure’s ability for nice interoperability with Java, you have an easy solution at hand:

This is how you can use the from-unix-time function:

To get a Java Date object from a Unix time object, all you need to do is construct a new java.util.Date object using Clojure’s Java interop functionality.

If you are already using or wish to use the clj-time library, you can use clj-time to obtain a DateTime object from a Unix timestamp:

And using the datetime-from-unix-time function, you can see you get a DateTime object back with the correct time:

You may not need to worry about dates and times being expressed as seconds very often, but when you do, isn’t it nice to know how easy it can be to get those timestamps into a date format used by the rest of the system?

You need to get a Unix timestamp representation for a Date object.

Many systems express timestamps in Unix time format, and when you have to interact with these systems, you have to give them date and time information in the format they desire.

Fortunately, with Clojure’s ability for nice interoperability with Java, you have an easy solution at hand:

This is how you can use the to-unix-time function:

When you have a java.util.Date object, you can use the Java interop provided by Clojure as an easy way to get the time represented as a Unix time. Java’s Date objects have a method called getTime that returns the date as a Unix time.

If you are already using or wish to use the clj-time library, you can use clj-time to obtain a Unix time–formatted DateTime object if you have a DateTime object:

And using the datetime-to-unix-time function, you can see you get a Unix time format for a DateTime object:

Thanks to clj-time.coerce, all that is needed is to use the function to-long to get a Joda-Time DateTime object into a Unix time format.

Your system may never need to interact with other systems that expect timestamps expressed in Unix time, but if you are designing a system that does, Clojure makes it very easy to express a Date or DateTime in Unix time format.

Immutability means that a Clojure data structure, once created, can never change. You can only "modify" an immutable data structure by creating a new data structure that is a copy of the old, with the desired changes in place.

Immutability also means that Clojure data structures, however deeply nested, are simple values, just like the number 3 or the character \z. It doesn’t make sense to speak of "changing" the value of 3— it just is. If you "change" it by, say, incrementing it, you don’t modify 3 itself. Instead, you end up with an entirely new and different value, 4. Clojure extends this notion of value to all data structures. In Clojure, any action that in another language would perform any kind of update on a data structure will instead return an entirely new one. You can continue to pass around and use both the old and the new versions with confidence, knowing that nothing you can do will cause any unintended changes elsewhere in your program.

This feature is extremely important in concurrent and parallel programming, where unexpected mutation is the source of a large class of bugs. With immutable data, any number of threads can read from the same data without any worrying about locks or race conditions—it’s always safe to read something that can’t change. "Clone" operations are not only free, but unnecessary.

But, you may ask, how can that possibly be efficient? Surely it is impractical to do a full copy of an object every time you need to add something?

Yes, it would be, except for the feature of persistence. Persistence means that Clojure’s data structures, although logically immutable, can still share pieces of their internal structure for efficiency in both time and space. Essentially, updated versions of immutable data only need to store the deltas from pervious versions, rather than doing a full deep copy.

To make it performant, all of this uses some extremely clever algorithms, of course. See the book Purely Functional Data Structures by Chris Okasaki (Cambridge University Press) for a detailed description of how they work.

From vectors, maps, sets, and lists to strings and streams, every last one of Clojure’s collections behaves in a similar, predictable fashion. They are simple tools for a more civilized age. This is on account of Clojure’s sequence abstraction.

The array of collection-manipulating functions in Clojure are all implemented in terms of one simple abstraction: every collection can be treated as a sequence of values. By implementing first, rest, and cons, any data structure—even ones you build yourself—can participate in the ISeq interface.

Then, you can use Clojure’s huge library of functions that can operate on sequences, with any of the data structures. All of functional programming’s most beloved functions (map, reduce, filter, etc.) will work interchangeably on any data structure. In essence, the sequence abstraction allows all the expressiveness of traditional list-based LISP programming without forcing you to actually use lists. Instead, use whatever type is most efficient for the task, knowing that you can consume them all in the same way when it makes sense to do so.

You want to create a list data structure in your source code.

There are two basic ways to specifically construct a list (a clojure.lang.PersistentList).

You can use parentheses in combination with a single quote to indicate that the list should only be read as a data structure, not immediately evaluated:

Or, more commonly, you can use the list function, which takes a variadic number of arguments and constructs a list from them:

Typically, between these two approaches, using the list function is the better choice. The problem with constructing quoted lists is that the quote also prevents evaluation of everything inside the list, which means that symbols will be returned as literal symbols, instead of resolving variables or calling functions. list, however, will evaluate its arguments in the normal way before constructing the list and is usually what is desired for nonmacro code:

That said, '() is the idiomatic way to create an empty list—it is more terse, and the concern about evaluating its contents is irrelevant when it’s empty.

You have an existing sequential data structure that you would like to convert into a list as its concrete data type.

The easiest solution is: don’t. Having a concrete list provides little or no advantage over simply using the sequence abstraction directly on your existing data, and for large data structures, conversion can be expensive.

If you do know that you need an explicit conversion of the concrete data structure, there are two ways to do it.

First, you could use the apply function to call the list function, passing it your existing data structure as its arguments:

Alternatively, you could use the into function to repeatedly conjoin elements from your original data onto a list. Note, however, that this approach has the effect of reversing the order of the original collection:

These two approaches are both viable choices. However, what actually happens in each case is very different.

When using apply, you are actually invoking the list function with however many arguments are in the data structure. This may sound strange, particularly if the data structure contains millions of items. What does it mean to invoke a function with a million arguments? How does that even work, given that the JVM limits methods to 255 arguments (see the JVM class file specification)?

As it turns out, functions with variadic arguments (such as list) are handled in a somewhat special way: the argument list is passed in as a sequence. apply knows this and passes this sequence view of the original structure directly through to the receiving function. This is why it works; there is never actually a JVM method invocation with a million arguments.

into works quite differently: it takes two arguments, the first being a data structure and the second being a sequence. It then repeatedly conjoins items from the sequence onto the data structure provided using the conj function (discussed in greater detail elsewhere). This is why the sequence is reversed; items are always pulled from the front of the sequence, but conj on a list prepends the element being added. Therefore, the first element in the input sequence will end up being the last item in the list, and so on.

So why ever choose into over apply, given that it reverses the order? Speed. into utilizes Clojure transients, which provide a considerable performance improvement. On the author’s machine, converting a million-item vector to a list using apply took an average of 750 milliseconds, while using into took about half that time, for an average of 350 milliseconds. Of course, the list was in reverse order, and reversing either the input or the output negates the speed advantage. In the end, into is only advantageous in situations where a reversed order is acceptable.

You want to add an item to a list; or, putting it in functional terms, you want to derive from an existing list a new list that contains an additional item.

Use the conj function. conj is used to add an item or items to a logical collection and is polymorphic, meaning it works on multiple concrete data types, including lists:

You can also add multiple items at once:

The behavior of conj may vary slightly depending on the concrete type. It always "adds" an item to an immutable collection by returning a new collection containing the new item, but may add the item to different places in the collection depending on what is most efficient for the particular type.

In the case of lists, conj will always add the item at the beginning of the list, since a linked list data structure supports constant-time insertion only at the beginning.

You want to obtain a list without a particular item in it, removing an item from the original list.

Removing the first item from a list is easily accomplished using one of two functions, rest or pop. Both work identically when used on a nonempty list:

rest is actually a sequence function, used to obtain the tail of a sequence. Since Clojure lists implement the sequence interface directly, using rest on a list will always return another (possibly empty) list.

pop is similar to conj in that it operates on concrete data structures rather than the sequence interface. Like conj, it is polymorphic; also like conj, the position it removes the item from depends on what’s most efficient for the concrete type.

When used on an empty list, the behavior does differ; pop will throw an exception, while rest will return an empty list:

Lists do not support removing items except at the first position. If you need to remove an item in the middle or at the end of a list, you’ll have to do so using the sequence manipulation functions, then convert the result back into a concrete list (if you absolutely need it to be a list, for some reason).

You want to test if a value is a list.

The list? function may seem like the obvious choice, but in most cases, it’s better to use the more general seq? function as your test.

The list? function specifically tests if the argument implements clojure.lang.IPersistentList, but in most cases, you really want to know if the value is a seq (implements clojure.lang.ISeq), which is a more general abstraction than a list.

Not everything that prints as a list (in parentheses) actually satisfies the list? test. In practice, you’ll often receive Cons and LazySeq values when manipulating lists. By focusing on the fundamental seq abstraction, you don’t need to worry about the details of those concrete implementations:

It’s almost always better to use seq? instead of list?.

You want to create a vector data structure, either as a literal or from an existing data structure.

By far, the easiest way to create a vector is using the literal vector notation of square brackets. However, it is also possible to use the vector function, which creates a vector of its arguments:

To construct a vector from an existing data structure, you can use the vec function, which takes any collection and returns a vector containing the same items:

Alternatively, you can use the into function, which takes two collections and repeatedly invokes conj on the first with items from the second:

There is rarely any reason to use the vector function over the literal vector syntax. Unlike lists, vectors are not evaluated as function calls (or anything else) in Clojure, so quoting is not a concern as it is with list literals.

Oddly enough, when constructing a vector from an existing collection, using the into approach is currently about 30% more performant on large collections compared to vec due to its use of transients to speed things up. If you’re converting large collections and speed matters, consider using into. Otherwise, vec is usually more readable.

You want to add an item to a vector, yielding a new vector containing the item.

When used on a vector, the conj function returns a vector with one or more items appended to the end:

Vectors do not support adding new items anywhere aside from the end. If you need to insert an item in the middle, you will have to use a sequence manipulation function and convert back to a vector (if necessary) when you’re done.

Since vectors are associative (mapping integer indexes to values), you can also use the assoc function with an index equal to the current length of the vector (one greater than the maximum index) to append an item:

However, this approach is somewhat more fragile than conj. If the index you provide is too small, you might simply "overwrite" an earlier value in the vector; and if it’s greater than the vector’s current length, it will throw an IndexOutOfBoundsException.

Still, this technique is worth remembering. If you have code that is assoc-ing to a vector already, you can use this technique to produce new vectors with updated values.

You want to remove an item from a vector, obtaining a new vector without the item.

To efficiently remove an item from the end of a vector, use the pop function, which takes a vector and returns a new vector without the last item:

Although there is no operation designed specifically to remove items from the beginning of a vector, as pop does from the end, there is a function, subvec, that can be used to efficiently remove any number of items from the beginning or end of a vector. Given a vector, a start index, and an (optional) end index, it will return a vector from the start (inclusive) to end (exclusive) indexes.

The following example drops a single item from the beginning of a vector. You can use subvec like so:

Or, to remove items from the beginning and the end of a vector, pass an end index to subvec as well:

Because subvec exploits the internal representation of a vector to create a subvector that shares the internal structure of the original, it is extremely efficient and runs in constant time. It is the only way to efficiently remove items from the beginning of a vector.

While it is certainly also possible to use a function like rest or drop on a vector, these are technically sequence operations, not vector operations. The value they return is only guaranteed to be a sequence, not a concrete vector, and as such will not support the same features or performance guarantees that vectors do.

Of course, you can convert any sequence back into a concrete vector using vec or into [], but this can be an expensive operation for large vectors.

You have a vector, and you want to retrieve the value the vector contains at a particular location (index).

There are several ways to do this.

Which technique should you use? All work equally well, but the choice does emphasize the way in which you’re looking at your vector. nth focuses on its sequential nature, whereas get emphasizes its indexed, associative quality. Using the vector as a function is also consistent with the way all associative collections in Clojure act as functions of their keys.

Ultimately, when making a choice like this, you should consider:

Given a vector, you would like to obtain a new vector with a different value at a particular index.

Use assoc to set the value at a particular index: