# Chapter 5: Building Arrays

This chapter is about building arrays. First we look at building arrays from lists, and then at joining arrays together in various ways to make larger arrays.

Recall from Chapter 02 what we mean by the word "items". The items of a list of numbers are the numbers. The items of a table are its rows. The items of a 3-dimensional array are its planes.

## 5.1 Building Arrays by Shaping Lists

### 5.1.1 Review

Recall from Chapter 02 that `x $ y` produces an array of the items of the list `y`, with shape `x`, that is, with dimensions given by the list `x`. For example:

`2 2 $ 0 1 2 3` | `2 3 $ 'ABCDEF'`

    0 1
    2 3

    ABC
    DEF

If the list `y` contains fewer than the number of items needed, then `y` is re-used in cyclical fashion to make up the number of items needed. This means that an array can be built to show some simple patterning, such as all elements being the same, for example.

`2 3 $ 'ABCD'` | `2 2 $ 1` | `3 3 $ 1 0 0 0`

    ABC
    DAB

    1 1
    1 1

    1 0 0
    0 1 0
    0 0 1

The "Shape" verb, dyadic `$`, has a companion verb, "ShapeOf" (monadic `$`), which yields the list-of-dimensions, that is, shape, of its argument. To illustrate:

`A =: 2 3 $ 'ABCDEF'` | `$ A` | `a =: 'pqr'` | `$ a`

    ABC
    DEF

    2 3

    pqr

    3

For any array `A`, its list-of-dimensions `$ A` is a 1-dimensional list (the shape). Hence `$ $ A` is a list of 1 item (the rank). Hence `$ $ $ A` is always a list containing just the number `1`.

`A` | `$ A` | `$ $ A` | `$ $ $ A`

    ABC
    DEF

    2 3

    2

    1

### 5.1.2 Empty Arrays

An array can be of length zero in any of its dimensions. A zero length, or empty, list can be built by writing `0` for its list of dimensions, and any value (doesn't matter what) for the value of the item(s).

`E =: 0 $ 99` | `$ E`

    0

If `E` is empty, then it has no items, and so, after appending an item to it, the result will have one item.

`E` | `$ E` | `w =: E ,98` | `$ w`

    0

    98

    1

Similarly, if `ET` is an empty table with no rows, and say, 3 columns, then after adding a row, the result will have one row.

`ET =: 0 3 $ 'x'` | `$ ET` | `$ ET , 'pqr'`

    0 3

    1 3

### 5.1.3 Building a Scalar

Suppose we need to build a scalar. A scalar has no dimensions, that is, its dimension-list is empty. We can give an empty list as the left argument of `$` to make a scalar:

`S =: (0$0) $ 17` | `$ S` | `$ $ S`

    17

    0

### 5.1.4 Shape More Generally

We said that `(x $ y)` produces an `x`-shaped array of the items of `y`. If `y` is a table, then an item of `y` is a row, that is, a list. In general the shape of `(x$y)` will be not just `x`, but rather `x` followed by the shape of an item of `y`.

In the following example, the "shape of an item of `y`" is `4`, the length of a row of `y`.

`x =: 2` | `y =: 3 4 $ 'A'` | `z =: x $ y` | `$ z`

    2

    AAAA
    AAAA
    AAAA

    AAAA
    AAAA

    2 4

The next sections look at building new arrays by joining together arrays we already have.

## 5.2 Appending, or Joining End-to-End

Recall that any array can be regarded as a list of items, so that for example the items of a table are its rows. The verb , (comma) is called "Append". The expression `(x,y)` is a list of the items of `x` followed by the items of `y`.

       B =: 2 3 $ 'UVWXYZ'
       b =:   3 $ 'uvw'

`a` | `b` | `a , b` | `A` | `B` | `A , B`

    pqr

    uvw

    pqruvw

    ABC
    DEF

    UVW
    XYZ

    ABC
    DEF
    UVW
    XYZ

In the example of `(A,B)` above. the items of `A` are lists of length 3, and so are the items of `B`. Hence items of `A` are compatible with, that is, have the same rank and length as items of `B`. What if they do not? In this case the "Append" verb will helpfully try to stretch one argument to fit the other, by bringing them to the same rank, padding to length, and replicating scalars as necessary. This is shown the following examples.

### 5.2.1 Bringing To Same Rank

Suppose we want to append a row to a table. For example, consider appending the 3-character list `b` (above) to the 2 by 3 table `A` (above) to form a new row.

`A` | `b` | `A , b`

    ABC
    DEF

    uvw

    ABC
    DEF
    uvw

Notice that we want the two items of `A` to be followed by the single item of `b`, but `b` is not a 1-item affair. We could do it by reshaping `b` into a 1 by 3 table, that is, by raising the rank of `b`. However, this is not necessary, because, as we see, the "Append" verb has automatically stretched the low-rank argument into a 1-item array, by supplying leading dimension(s) of 1 as necessary.

`A` | `b` | `A , (1 3 $ b)` | `A , b` | `b , A`

    ABC
    DEF

    uvw

    ABC
    DEF
    uvw

    ABC
    DEF
    uvw

    uvw
    ABC
    DEF

### 5.2.2 Padding To Length

When the items of one argument are shorter than the items of the other, they will be padded out to length. Characters arrays are padded with the blank character, numerical arrays with zero.

`A` | `A , 'XY'` | `(2 3 $ 1) , 9 9`

    ABC
    DEF

    ABC
    DEF
    XY

    1 1 1
    1 1 1
    9 9 0

### 5.2.3 Replicating Scalars

A scalar argument of "Append" is replicated as necessary to match the other argument. In the following example, notice how the scalar `'*'` is replicated, but the vector `(1 $ '*')` is padded.

`A` | `A , '*'` | `A , 1 $ '*'`

    ABC
    DEF

    ABC
    DEF
    ***

    ABC
    DEF
    *

## 5.3 Stitching, or Joining Side-to-Side

The dyadic verb `,.` (comma dot) is called "Stitch". In the expression `(x ,. y)` each item of `x` has the corresponding item of `y` appended to produce an item of the result.

`a` | `b` | `a ,. b` | `A` | `B` | `A ,. B`

    pqr

    uvw

    pu
    qv
    rw

    ABC
    DEF

    UVW
    XYZ

    ABCUVW
    DEFXYZ

## 5.4 Laminating, or Joining Face-to-Face

The verb `,:` (comma colon) is called "Laminate". The result of `(x ,: y)` is always an array with two items, of which the first is `x` and the second is `y`

`a` | `b` | `a ,: b`

    pqr

    uvw

    pqr
    uvw

If `x` and `y` are tables, then we can imagine the result as one table laid on top of the other to form a 3-dimensional array, of length 2 along its first dimension.

`A` | `B` | `A ,: B` | `$ A ,: B`

    ABC
    DEF

    UVW
    XYZ

    ABC
    DEF

    UVW
    XYZ

    2 2 3

## 5.5 Linking

The verb ; (semicolon) is called "Link". It is convenient for building lists of boxes.

`'good' ; 'morning'` | `5 ; 12 ; 1995`

    +----+-------+
    |good|morning|
    +----+-------+

    +-+--+----+
    |5|12|1995|
    +-+--+----+

Notice how the example of `5;12;1995` shows that `(x;y)` is not invariably just `(< x),(< y)` . Since "Link" is intended for building lists of boxes, it recognises when its right argument is already a list of boxes. If we define a verb which does produce `(< x),(< y)`

       foo =: 4 : '(< x.) , (< y.)'

we can compare these two:

`1 ; 2 ; 3` | `1 foo 2 foo 3`

    +-+-+-+
    |1|2|3|
    +-+-+-+

    +-+-----+
    |1|+-+-+|
    | ||2|3||
    | |+-+-+|
    +-+-----+

## 5.6 Unbuilding Arrays

We have looked at four dyadic verbs: "Append" `(,)`, "Stitch" `(,.)`, "Laminate" `(,:)` and "Link" `(;)`. Each of these has a monadic case, which we now look at.

### 5.6.1 Razing

Monadic `;` is called "Raze". It unboxes elements of the argument and assembles them into a list.

`B =: 2 2 $ 1;2;3;4` | `; B` | `$ ; B`

    +-+-+
    |1|2|
    +-+-+
    |3|4|
    +-+-+

    1 2 3 4

    4

### 5.6.2 Ravelling

Monadic `,` is called "Ravel". It assembles elements of the argument into a list.

`B` | `, B` | `$ , B`

    +-+-+
    |1|2|
    +-+-+
    |3|4|
    +-+-+

    +-+-+-+-+
    |1|2|3|4|
    +-+-+-+-+

    4

### 5.6.3 Ravelling Items

Monadic `,.` is called "Ravel Items". It separately ravels each item of the argument to form a table.

`k =: 2 2 3 $ i. 12` | `,. k`

    0  1  2
    3  4  5

    6  7  8
    9 10 11

    0 1 2 3  4  5
    6 7 8 9 10 11

"Ravel Items" is useful for making a 1-column table out of a list.

`b` | `,. b`

    uvw

    u
    v
    w

### 5.6.4 Itemizing

Monadic `,:` is called "Itemize". It makes a 1-item array out of any array, by adding a leading dimension of `1`.

`A` | `,: A` | `$ ,: A`

    ABC
    DEF

    ABC
    DEF

    1 2 3

## 5.7 Arrays Large and Small

As we have seen, an array can be built with the `$` verb.

       3 2 $ 1 2 3 4 5 6
    1 2
    3 4
    5 6

For small arrays, where the contents can be listed on a single line, there are alternatives to using `$`, which avoid the need to give the dimensions explicitly.

`> 1 2 ; 3 4 ; 5 6` | `1 2 , 3 4 ,: 5 6`

    1 2
    3 4
    5 6

    1 2
    3 4
    5 6

To build large tables, a convenient method is as follows. First, here is a "utility" verb (that is, a verb which is useful for present purposes, but we don't need to study its definition now.)

       ArrayMaker =: ". ;. _2

The purpose of `ArrayMaker` is to build a numeric table row by row from the lines of a script.

       table =: ArrayMaker 0 : 0
    1 2 3
    4 5 6
    7 8 9
    )

`table` | `$ table`

    1 2 3
    4 5 6
    7 8 9

    3 3

(See Chapter 17 for an explanation of how `ArrayMaker` works). Arrays of boxes can also be entered from a script in the same way:

       X =:  ArrayMaker  0 : 0
    'hello' ; 1 2 3 ; 8
    'Waldo' ; 4 5 6 ; 9
    )

`X` | `$ X`

    +-----+-----+-+
    |hello|1 2 3|8|
    +-----+-----+-+
    |Waldo|4 5 6|9|
    +-----+-----+-+

    2 3

We have reached the end of Chapter 5.

NEXT
Table of Contents
Index

Copyright © Roger Stokes 2003. This material may be freely reproduced, provided that this copyright notice is also reproduced.

last updated 1 Apr 2004