# Lists
Lists are Deft's persistent immutable vectors: the literal `@{ ... }`
builds one, and every operation here returns a new list rather than
mutating the original. These bare functions are compiled into every
runtime and need no import. The transforming verbs (`map`, `filter`,
`reduce`, and friends) live on Sequence Functions;
for the collection model as a whole, see
Collections.
## Functions
| Function | Purpose |
|---|---|
| `len xs` | Length — works on lists, maps, sets, and strings (codepoints) |
| `first xs`, `last xs` | First / last element (`nil` when empty) |
| `rest xs` | All but the first element |
| `nth xs i` | Element at index `i`; negative counts from the end |
| `slice xs start end` | Sub-list or substring; `$xs(a..b)` is sugar |
| `reverse xs` | Reversed list (or string) |
| `range end` / `range start end ?step` | Numeric list, `start` inclusive to `end` exclusive |
| `in? xs v` | Membership test |
| `append xs v` | New list with `v` appended (maps assoc/merge; strings concatenate) |
| `flatten xs` | Concatenate nested lists one level deep |
| `sort xs` / `sort xs cmp` | Ascending sort, or a comparator |
| `unique xs` | De-duplicate, preserving first occurrence |
| `take xs n`, `drop xs n` | First / remaining N elements (lazy) |
| `zip as bs` | Pair up two lists |
| `from-entries pairs` | Build a map from `@{ key value }` pairs |
| `set-nth xs i v`, `insert-nth xs i v`, `remove-nth xs i` | Index operations |
Index rules: `nth`, `slice`, `set-nth`, and `remove-nth` accept
negative indices (counting from the end). Out-of-range `nth` returns
`nil`; `set-nth` and `remove-nth` return the list unchanged;
`insert-nth` clamps its index to `[0, len]`.
`take` and `drop` return lazy sequences when given a collection; the
one-argument forms `[take n]` and `[drop n]` return transducers (see
Lazy Sequences and
Transducers).
`in?` is a normal function, not an operator — write `[in? $xs $v]`.
`sort` without a comparator uses value ordering; with one, the
comparator is called with two elements and returns a boolean.
To grow a local list in place, use `$xs << $v` (the mutating sibling of
`append`); `<<` also concatenates onto string locals — see
Collections for the full append semantics
and Syntax and Style for when each
form is preferred.
## Examples
def xs @{ 10 20 30 } $xs(len) # => 3 $xs(first) # => 10 $xs(last) # => 30 $xs(rest) # => @{ 20 30 } $xs(nth 1) # => 20 $xs(1..3) # => @{ 20 30 } — range slice $xs(reverse) # => @{ 30 20 10 }
Construction and structural transforms:
[range 5] # => @{ 0 1 2 3 4 } [range 1 7 2] # => @{ 1 3 5 } — with step [append $xs 40] # => @{ 10 20 30 40 } [flatten @{ @{ 1 2 } @{ 3 4 } }] # => @{ 1 2 3 4 } [sort @{ 3 1 2 }] # => @{ 1 2 3 } [sort @{ 3 1 2 } {|a b| ($a > $b)}] # descending, comparator form [unique @{ 1 1 2 3 3 }] # => @{ 1 2 3 }
Taking, dropping, pairing, and rebuilding a map:
[take $xs 2] # => @{ 10 20 } [drop $xs 2] # => @{ 30 } [zip @{ :a :b } @{ 1 2 }] # => @{ @{ :a 1 } @{ :b 2 } } [from-entries [zip @{ :a :b } @{ 1 2 }]] # => %{ :a 1 :b 2 }
Index operations and membership return new lists:
[set-nth $xs 0 99] # => @{ 99 20 30 } [insert-nth $xs 1 15] # => @{ 10 15 20 30 } [remove-nth $xs 1] # => @{ 10 30 } [in? $xs 20] # => true
Accumulate into a local with `<<` (mutates in place), or keep the pure
form with `append`:
def out @{} for x in @{ 1 2 3 } { $out << ($x * 2) } $out # => @{ 2 4 6 } [append $xs 99] # $xs is still @{ 10 20 30 }
## See Also
- Collections — literals, persistence, `<<`
- Lazy Sequences — `take`/`drop` and forcing
- Sequence Functions — `map`, `filter`, `reduce`
- Maps — `from-entries`, `keys`, `values`
- Arrays, Sets — the mutable and set-shaped collections