# Reshape

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Reshape (`⍴`) produces an array with shape given by the left argument and elements from the right argument. Elements are copied from the right argument to the result in ravel order, truncating if the result has smaller bound than the right argument and repeating cyclically if it has larger bound. If the right argument is empty, fills are used for the result elements.

## Description

The left argument of Reshape must be a valid shape, or vector of nonnegative integers, after scalar rank extension (that is, a scalar is treated as a one-element vector). The right argument may be any array. The result array is an array of the given shape, and its elements in ravel order are taken from the right argument in ravel order. If the right argument's ravel is too short, they are repeated starting at the beginning again as many times as necessary.

## Examples

Reshape can be used to produce an array with a given shape and ravel:

```      3 4 ⍴ ⍳12
1  2  3  4
5  6  7  8
9 10 11 12```

It appears to exhibit a form of scalar or singleton extension:

```      3 4 ⍴ 12
12 12 12 12
12 12 12 12
12 12 12 12```

In fact it repeats an argument of any length, singleton or otherwise. This repetition applies with a vector result, or a higher rank.

```      12 ⍴ 'abcde'
abcdeabcdeab
3 4 ⍴ 'abcde'
abcd
eabc
deab```

## APL model

Since Reshape itself is the fundamental way to create a multi-dimensional array in APL, the function as a whole cannot be modelled in terms of more fundamental primitives. However, we may express it in terms of a stricter reshaping function `shape`, which forms an array from its shape and ravel vectors, requiring both to have rank 1 and the number of elements in the ravel to be the product of the shape. `shape` is identical to Reshape on its domain, but it has a strictly smaller domain than Reshape. The extensions required to implement Reshape are that a scalar left argument must be allowed, and that the right argument must be converted to a vector with the appropriate length, truncating or repeating its elements.

```Reshape ← {
(1/⍺) shape (×/⍺) {(0=≢⍵)∨⍺≤≢⍵:⍺↑⍵ ⋄ ⍺∇,⍨⍵} ,⍵
}```

The above implementation performs truncation and fill element generation using Take, after extending the ravelled right argument by catenating it with itself until it is long enough. An implementation using indices instead of structural manipulation is also possible:

```Reshape ← {
⎕IO←0
(1/⍺) shape ((,⍵),(⊂⊃⍵))[(1⌈×/⍴⍵)|⍳×/⍺]
}```
Works in: Dyalog APL

Here the right argument is converted to a ravel vector by ravelling and appending the prototype, then indexing to produce a vector of the correct length. The indices used are the ravel indices of the result, but they are made to wrap around using Residue.

## Documentation

J function Shape: Dictionary, NuVoc