Lists

The list is the funda­mental data struc­ture of Racket. A list is a sequence of values. A list can contain any kind of value, including other lists. A list can contain any number of values. If a list has zero values, it’s called the empty list.

List nota­tion

Any time you put values between paren­theses, you’re making a list. By default, square and curly brackets work the same way as paren­theses, so these lists are the same:

In prac­tice, paren­theses are preferred, and square and curly brackets are reserved for special situ­a­tions where they improve read­ability, for instance the vari­ables intro­duced at the top of a let:

If you type a list in a Racket program, by default it will be inter­preted as Racket code:

To make a list of values that will be eval­u­ated as data, not code, use the list func­tion:

Alter­na­tively, you can make a special kind of list with quote, called a datum. quote can be used as a func­tion. But the idiomatic way to use it is by adding a ' prefix to any expres­sion. Below, some datums made with quote, and the equiv­a­lent list nota­tion on the right:

Caution: depending on the input, list and quote may or may not produce the same output list. For instance, Racket deems numbers, strings, and Booleans to be “self-quoting”—meaning, they’re already in datum form—so they’re not changed by quote. For these values, list and quote (and its equiv­a­lent, the ' prefix) can be used inter­change­ably:

But other values, like vari­ables and expres­sions, are not self-quoting, so list and quote produce different results:

When you use list, a subex­pres­sion like (* 6 7) is first eval­u­ated as 42 before it’s put in the list. But when you use quote, that subex­pres­sion is just treated as a sublist of datums.

For Racket newcomers, list tends to be the less confusing choice. Later, you’ll come to appre­ciate the ' short­hand when typing longer lists of self-quoting values. These two lists are the same:

A vari­able that holds a list is often named with a plural ending (like s) to signal multiple values. Following that idea, a vari­able that holds a list of lists can be named with a double-plural ending (though triple- may be pushing it):

Printing lists

Racket prints lists using a leading quota­tion mark ' followed by the simplest textual repre­sen­ta­tion of each value.

Self-quoting values are printed the same way they’re typed, so these lists:

Are printed like so:

The way a list is printed doesn’t depend on how it’s constructed, only on what’s in it. Even though the first list uses list and the second uses quote, they print the same way.

Also, a printed list of self-quoting values is iden­tical to the '-prefixed list form, so you could copy this output and paste it back into a program as code.

By contrast, values in a list that are not self-quoting:

Will be printed with a textual approx­i­ma­tion:

Textual repre­sen­ta­tions of these non-self-quoting values cannot be repur­posed as program code, as you find when you paste the last result back into the program window:

Lists with a mixture of self-quoting values and others print accord­ingly:

Finally, keep in mind that the leading quota­tion mark on a printed list and the paren­theses delim­iting its edges aren’t intrin­si­cally part of the list, any more than the quota­tion marks printed "around a string" or the leading zero printed for a number like 0.1234. These are just nota­tional conve­niences used when reducing these values to text. In DrRacket, you can change the way lists are printed with Language → Choose Language ... → Output Style.

Quasi­quote

Between list and quote is quasiquote. As the name implies, by default it works like quote, but it also allows you to inter­po­late expres­sions that are eval­u­ated normally (as they would be with list).

Like quote, though quasiquote can be invoked as a func­tion, it’s more commonly notated with a prefix, this time the back­tick `. To inter­po­late a single value, use unquote, which is usually written as a comma prefix , followed by the expres­sion:

To inter­po­late a list of multiple values, use unquote-splicing, which is usually written as a comma followed by an at sign ,@ followed by the vari­able. The unquote-splicing func­tion merges the sublist with the surrounding list:

If you use unquote with a sublist, the sublist will remain nested:

Essen­tial list func­tions

Lists are ubiq­ui­tous in Racket, thus many func­tions consume or produce lists. A handful are worth commit­ting to memory because they’re so common.

list?: test if some­thing is a list.

empty?: test if some­thing is an empty list (null? is equiv­a­lent).

length: get the number of elements in a list.

flatten: squish nested sublists into a single list.  + CS pros: “squish” = a pre-order depth-first traversal.

apply: append a list of values to the argu­ment list for a func­tion.

map: apply a func­tion to every value in a list, and get back a list of return values. The input and output lists are always the same length. If the func­tion accepts multiple values, then multiple lists must be provided, of the same length.

for-each: like map, apply a func­tion to every value of a list; unlike map, ignore the return values. This is handy when the func­tion is being used for its side effect, not for its return value.

filter: take the values from a list that match a pred­i­cate func­tion, and discard the others. The most common way of short­ening a list.

cons: insert a value at the front of a list.

append: join multiple lists into a single list.

car or first: get the first value of a list.

cdr or rest: get the tail of a list after the first value, which is always a list (though possibly empty).

car and cdr are the inverse of cons, so this iden­tity is true for every non-empty list:

For the origin of these three oddly-named func­tions, see pairs.

range: make a list of numbers.

Recur­sion

As a data struc­ture, lists are designed to coop­erate well with recur­sive-style func­tions that consume the elements of the list in sequence. The idea is that on each pass, the func­tion only trans­forms the first element of the list, and recurses on the rest until it’s empty, and the results are reassem­bled into a list with cons:

List func­tions like map and filter offer a higher-level inter­face to this same recur­sion logic.

See also recur­sion.

Random access

Because lists are made of linked pairs, they’re opti­mized for sequen­tial access, not random access. Though you can use list-ref to retrieve an arbi­trary element from a list, it works by starting at the front of the list and traversing to the requested element. For small lists, that’s no big deal. For larger lists, it can be slow. At that point, prob­ably you’ll be happier with a vector. See data struc­tures.

Further