> For the complete documentation index, see [llms.txt](https://osl.mistium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://osl.mistium.com/methods/arrays.md).

# Arrays

Arrays in OSL are **1-indexed** - the first element is at index 1. Index `0` and out-of-range indices return `null`; negative indices count from the end (`arr[-1]` is the last element). Writes follow the same rules: assigning to index `0` or past the end is silently ignored, while a negative index writes from the end (`arr[-1] = x` replaces the last element).

```javascript
arr = [10, 20, 30, 40, 50]
log arr[1]    // 10
log arr[-1]   // 50
log arr.len   // 5
```

## Creating arrays

```javascript
arr = [1, 2, 3]          // literal
arr = 1 to 5             // range → [1, 2, 3, 4, 5]
arr = -2 to 2            // [-2, -1, 0, 1, 2]
arr = (1 to 3).fill("x") // ["x", "x", "x"]
arr = [1, 2] ++ [3, 4]   // concatenate → [1, 2, 3, 4]
```

## In this section

* [**Transforming**](/methods/arrays/transforming.md) - `map`, `filter`, `sort`, `sortBy`, `reverse`, `deDupe`, `fill`, `concat`.
* [**Adding & Removing**](/methods/arrays/mutating.md) - `append`, `prepend`, `insert`, `swap`, `pop`, `shift`, `delete`, `trim`.
* [**Searching & Testing**](/methods/arrays/searching.md) - `contains`, `index`, `lastIndex`, `some`, `every`, `first`, `last`, `randomOf`.
* [**Aggregating**](/methods/arrays/aggregating.md) - `sum`, `product`, `average`, `max`, `min`, `join`.
* [**Slicing & Converting**](/methods/arrays/converting.md) - `left`, `right`, `clone`, `getKeys`, `toSet`, `toEntriesObj`.

## Custom array methods

You can attach your own methods to all arrays via a prototype, using `self` for the receiver:

```javascript
Array.double = def() -> (
  return self.map(x -> x * 2)
)

log [1, 2, 3].double()  // [2, 4, 6]
```

A custom method may reuse a built-in name — from its definition onward it overrides the built-in.

## Notes

* Methods that modify in place (`append`, `prepend`, `insert`, `swap`) return the modified array.
* Equality in `contains` / `index` is strict: `[1].contains("1")` is `false`.