# Operations with data

Data in RPL is generally represented using lists, such as `{ {1 2 } 3 "A"}`.
Numerical data can be represented using arrays, such as `[1 2 3 4]`. In the
DB48X implementation of RPL, arrays and list can have any number of dimensions,
and are not necessarily rectangular, although some operations (e.g. matrix
operations using arrays as input) can impose stricter constraints.


## →List

Build a list from elements on the stack. Level 1 of the stack contains the
number of elements in the list. The elements are on the stack, the first element
being deepest in the stack. This is the opposite of [List→](#fromlist).

`A` `B` ... `Count` ▶ `{ A B ... }`

## List→

Expand a list on the stack and return the number of elements. After executing
the command, level 1 contains the number of elements, and a corresponding number
of stack levels contain individual elements of the list, the first element being
at the deepest level in the stack. This is the opposite of [→List](#tolist). The
[Obj→](#explode) command performs the same operation when applied to a list.

`{ A B ... }` ▶ `A` `B` ... `Count`

## Head

Return the first element of a list, or an `Invalid dimension` error if the list
is empty.

`{ A B ... }` ▶ `A`

## Tail

Return all but the first element of a list, or an `Invalid dimension` error if
the list is empty.

`{ A B ... }` ▶ `{ B ... }`

## Map

Apply an operation on all elements in a list or array. The operation on the
first level of the stack should take one argument and return a single value.

`{ A B ... }` `F` ▶ `{ F(A) F(B) ... }`


```rpl
{ 1 2 A 42.2 [ 1 2 3 ]} « →STR » MAP
@ Expecting { "1" "2" "A" "42.2" "[ 1 2 3 ]" }
```

Unlike on HP calculators, `Map` does not apply recursively to inner lists by default.

```rpl
{ 1 2 { 3 4 } } « →STR » MAP
@ Expecting { "1" "2" "{ 3 4 }" }
```

This can be changed by setting `ListRecursionDepth` to `0`.

```rpl
0 ListRecursionDepth
{ 1 2 { 3 4 } }  « →STR » MAP
@ Expecting { "1" "2" { "3" "4" } }
```

`Map` can also be constrained to a given depth.

```rpl
2 ListRecursionDepth
{ 1 2 { 3 { 4 { 5 } } } }  « →STR » MAP
@ Expecting { "1" "2" { "3" "{ 4 { 5 } }" } }
'ListRecursionDepth' Purge
```

## Reduce

Apply a cumulative pairwise operation on all elements in a list or array.
The operation on the first level of the stack should take two arguments and
combine them into a single value. The result is the repeated application of that
operation to all elements.

`{ A B ... }` `F` ▶ `F(F(A, B), ...)`

For example, to sum all the elements in a list as text, one can use:

```rpl
{ X Y Z T 12 { Hello World } } « →STR + » REDUCE
@ Expecting "XYZT12{ Hello World }"
```

Reduce obeys the `ListRecursionDepth` setting:

```rpl
0 ListRecursionDepth
{ X Y Z T 12 { Hello World } } « →STR + » REDUCE
@ Expecting "XYZT12HelloWorld"
'ListRecursionDepth' Purge
```


## Filter

Filter elements in a list of array based on a predicate. The predicate given on
level 1 of the stack takes a value as argument, and returns a truth values. The
resulting list is built with all elements where the predicate is true.

`{ A B ... }` `P` ▶ `{ A ... }` if `P(A)` is true and `P(B)` is false.

For example, to filter all odd numbers in an array, one can use:

```rpl
[ 1 2 3 4 5 6 42 ] « 2 MOD 0 = » FILTER
@ Expecting [ 2 4 6 42 ]
```

`Filter` obeys the `ListRecursionDepth` setting:

```rpl
0 ListRecursionDepth
{ 1 2 3 4 { 5 6 { 42 } } } « 2 MOD 0 = » FILTER
@ Expecting { 2 4 { 6 { 42 } } }
'ListRecursionDepth' Purge
```


## Get

Get an element from composite data, such as list, an array or a text.
Elements are numbered starting at 1. The index can itself be a list, which is
interpreted as successive indices in the data.

For example,
`{ A B C } 2 GET` returns `B`,
`"ABC" 3 GET` returns `"C"`,
`[ [ 1 2 ] [ 4 5 ] [ 5 6 ] ] { 2 2 } GET` returns `5`.

When the data is a name, data is feched directly from the given named variable.

`Data` `Index` ▶ `Element`


## Put

Put an element into composite data, such as list, an array or a text.
This performs the opposite operation compared to `Get`.

Elements are numbered starting at 1. The index can itself be a list, which is
interpreted as successive indices in the data.

For example,
`{ A B C } 2 'X' PUT` returns `{ A X C }`,
`"ABC" 2 "Hello" PUT` returns `"AHelloC"`,
`[ [ 1 2 ] [ 4 5 ] [ 5 6 ] ] { 2 2 } 7 PUT` returns `[ [ 1 2 ] [4 7 ] [5 6] ]`.

When the data is a name, data is feched directly from the given named variable.

`Data` `Index` ▶ `Element`


## Sort

Sort elements in a list or array, sorting by increasing values when comparing
numers, text or symbols.

```rpl
{ 27 42 2.2 "DEF" "ABC" } SORT
@ Expecting { 2.2 27 42 "ABC" "DEF" }
```

This may be a little slower than `QuickSort`, but is useful to sort
lists or arrays of numerical values or text values.

Expressions are compared by evaluated value but preserved as is:

```rpl
{ 1 '2/3+0.21' 0 } Sort
@ Expecting { 0 '²/₃+0.21' 1 }
```

## QuickSort

Sort elements in a list or array using the memory representation of objects.
This guarantees a consistent sorting order, but one that does not necessarily
preserve numerical or textual properties, unlike `Sort`. Comparisons are,
however, significantly faster than `Sort`.

## ReverseSort

Sort a list or array by value, in reverse order compared to `Sort`.

## ReverseQuickSort

Sort a list or array using the memory representation of objects, in reverse
order compared to `QuickSort`.

## ReverseList

Reverse the order of elements in a list

## Unique

Remove duplicate consecutive values.

```rpl
{ 1 2 3 2 2 3 3 1 1 1 1 2 3 } Unique
@ Expecting { 1 2 3 2 3 1 2 3 }
```

To guarantee uniqueness across all the values, the list should be sorted first.

```rpl
{ 1 2 3 2 2 3 3 1 1 1 1 2 3 } Sort Unique
@ Expecting { 1 2 3 }
```

Like for `Sort`, expressions are evaluated but preserved in the result:

```rpl
{ '1+2' '1-2' '2+3' '2-1' '2/(1+1)' '3+2' } Sort Unique
@ Expecting { '1-2' '2÷(1+1)' '1+2' '3+2' }
```

## QuickUnique

Remove duplicate consecutive values that match exactly in memory

```rpl
{ '1+2' '1-2' '2+3' '2-1' '1-2' '2-1' '2/(1+1)' '3+2' } QuickSort QuickUnique
@ Expecting { '1+2' '1-2' '2-1' '2+3' '3+2' '2÷(1+1)' }
```

## ADDROT
Add elements to a list, keep only the last N elements


## SEQ
Assemble a list from results of sequential procedure

## ListSum

Return the sum of a list or array.

The `ListSum` command calculates the sum of all elements in a list or array.
It uses the `+` operation to add all elements together.
The result is a single value representing the sum of all elements.

In the following example, values `1`, `3` and `5` are added, which gives `9`.
Then the vector `[ 1 2 3 ]` is added to `9`, which gives another vector with
value `[ 10 11 12 ]`. Finally, this vector is added to the `"ABC"` text,
resulting in a text containing `"[ 10 11 12 ]ABC|`:

```rpl
{ 1 3 5 [ 1 2 3 ] "ABC" } ΣList
@ Expecting "[ 10 11 12 ]ABC"
```

## ListProduct

Return the product of a list or array.

The `ListProduct` command calculates the product of all elements in a list or array.
It uses the `×` operation to multiply all elements together.
The result is a single value representing the product of all elements.

In the following example, we multiply values `1`, `3`, `6`, `42` and
finally the complex value `2+3ⅈ`:

```rpl
[ 1 3 6 42 2+3ⅈ ] ∏List
@ Expecting 1 512+2 268ⅈ
```

## ListDifferences

Return the differences between successive elements in a list or array.

The `ListDifferences` command calculates the differences between consecutive
elements in a list or array.
It uses the `-` operation to subtract each element from the previous one.
The result is a list with one fewer element than the input, containing the
pairwise differences.

For example to compute the increase in value between successive elements in a
vector, you can use:

```rpl
[ 1 3 4 7 9 ] ∆List
@ Expecting [ 2 1 3 2 ]
```

Note that on HP calculators, this command only works with lists and not with vectors. On DB48x, it works both with list and arrays.
    Matrices are seen as arrays of vectors, as illustrated below:

```rpl
[[ 1 2 3 ]
 [ 4 5 6 ]
 [ 7 9 0 ]] ∆List
@ Expecting [[ 3 3 3 ] [ 3 4 -6 ]]
```
