# Data Structures
These functions operate on various data structures in Keithlisp.

## `cons`
```
(cons car cdr)
```
`cons` allocates and returns a new cons with the given `car` and `cdr`.

## `car`
```
(car cons)
```
`car` returns the car portion of `cons`, or nil if the argument is not a
cons.

## `cdr`
```
(cdr cons)
```
`cdr` returns the cdr portion of `cons`, or nil if the argument is not a
cons.

## `rplaca`
```
(rplaca cons value)
```
`rplaca` changes the car portion of `cons` to `value`. It returns the
same `cons` it was given.

## `rplacd`
```
(rplacd cons value)
```
`rplacd` changes the cdr portion of `cons` to `value`. It returns the
same `cons` it was given.

## `list`
```
(list &rest elements)
```
`list` allocates and returns a new list containing `elements`.

## `length`
```
(length list)
```
`length` returns the length of `list`, or nil if it is not a valid list.
**If `list` is circular, `length` will go into an infinite loop.**

## `nth`
```
(nth index list)
```
`nth` returns the `index`th element in `list`. `index` must be an int.

If `index` is negative, `nth` will add `(length list)` to it. **This
will fail if `list` is circular.**

## `nthcdr`
```
(nthcdr index list)
```
`nthcdr` returns the cdr of the `index`th cons in `list`. `index` must
be an int.

If `index` is negative, `nthcdr` will add `(length list)` to it. **This
will fail if `list` is circular.**

## `append`
```
(append &rest lists)
```
`append` constructs a new list containing all the elements of `lists`
appended together. It makes a shallow copy of each of its arguments.

## `push`
```
(push list item)
```
`push` pushes `item` onto `list` and returns the new head of `list`.

## `assoc`
```
(assoc alist key)
```
`assoc` returns the first cons in `alist` whose car is
[`eq`](stdlib_comparison.md#eq) to `key`, or nil if no matching cons
was found.

## `rassoc`
```
(rassoc alist value)
```
`rassoc` returns the first cons in `alist` whose cdr is
[`eq`](stdlib_comparison.md#eq) to `value`, or nil if no matching cons
was found.

## `alist-put`
```
(alist-put alist key value)
```
`alist-put` creates a new cons mapping `key` to `value`, and attempts to
update `alist` with it in-place. If `alist` already contains a cons
whose car is [`eq`](stdlib_comparison.md#eq) to `key`, the cons is
replaced in-place with the new one. Otherwise, `alist-put` pushes the
new cons onto `alist` and returns the new head of `alist`, in the same
manner as [`push`](stdlib_data.md#push).