> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lionlang.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# array module: list operations in Lion

> Lion's array module covers construction, access, length, concatenation, membership, and higher-order functions map, flat-map, and reduce.

The `array` module is how you build and transform lists in Lion. Because every Lion expression is valid JSON, arrays play a dual role: they are both executable expressions and data. The `array/make` function lets you treat an array as data — collecting its arguments into a list — without triggering the evaluator's call semantics.

## Construction and access

### `array/make`

Collects its arguments into an array. This is the canonical way to produce a literal list in a Lion program.

```json theme={null}
["array/make", 1, 2, 3]
```

Result: `[1, 2, 3]`

***

### `array/head`

Returns the first element of an array. Throws when the array is empty.

```json theme={null}
["array/head", ["array/make", 1, 2, 3]]
```

Result: `1`

***

### `array/tail`

Returns all elements after the first. Throws when the array is empty.

```json theme={null}
["array/tail", ["array/make", 1, 2, 3]]
```

Result: `[2, 3]`

***

### `array/length`

Returns the number of elements in an array.

```json theme={null}
["array/length", ["array/make", 1, 2, 3]]
```

Result: `3`

## Combining arrays

### `array/concat`

Concatenates two arrays and returns the combined list.

```json theme={null}
["array/concat", ["array/make", 1, 2], ["array/make", 3, 4]]
```

Result: `[1, 2, 3, 4]`

***

### `array/includes?`

Returns `true` when the array contains the given value. Uses Effect's `Equal.equals` for comparison, which falls back to referential equality (`===`) for plain JavaScript values.

```json theme={null}
["array/includes?", ["array/make", 1, 2, 3], 2]
```

Result: `true`

## Higher-order functions

All three higher-order functions accept a Lion lambda as their function argument, so they integrate with the Lion evaluator rather than requiring plain JavaScript functions.

### `array/map`

Applies a function to every element and returns the transformed array.

```json theme={null}
["array/map",
  ["array/make", 1, 2, 3],
  ["lambda", ["x"], ["number/add", "x", 1]]]
```

Result: `[2, 3, 4]`

***

### `array/flat-map`

Applies a function to every element and flattens the resulting arrays by one level.

```json theme={null}
["array/flat-map",
  ["array/make", 1, 2],
  ["lambda", ["x"], ["array/make", "x", "x"]]]
```

Result: `[1, 1, 2, 2]`

***

### `array/reduce`

Folds a list into a single value. Arguments are: the array, the initial accumulator, and a two-argument function that receives the accumulator and the current element.

```json theme={null}
["array/reduce",
  ["array/make", 1, 2, 3],
  0,
  ["lambda", ["acc", "x"], ["number/add", "acc", "x"]]]
```

Result: `6`

<Note>
  `array/map`, `array/flat-map`, and `array/reduce` run each callback through the Lion evaluator. This means you can use any Lion expression — including nested function calls and `begin` blocks — inside a lambda passed to these functions.
</Note>

<Tip>
  Combine `array/reduce` with `array/concat` to flatten nested structures, or use `array/flat-map` when each element maps to a variable-length list.
</Tip>