# Vocabulary/semi

 ; y Raze

Rank Infinity -- operates on x and y as a whole -- WHY IS THIS IMPORTANT?

Removes one level of boxing from a noun. Cells of the contents of each box then become the items of the result.

The shape of y is immaterial. If the contents of the boxes in y are atoms or lists, the result is to run the contents together into one list.

```   ]y=: 'alpha' ; 'bravo' ; 'charlie'
+-----+-----+-------+
|alpha|bravo|charlie|
+-----+-----+-------+

;y
alphabravocharlie
```

### Common uses

1. To remove a level of boxing that was added to produce a ragged array.

In this use (;y) does for a ragged array what (,y) does for a rectangular array.

Example: you want to give each member of each team a jersey. The first player on each team gets number 0, the next 1, etc. (The teams have different-colored jerseys so it's OK to duplicate numbers). Teams have different numbers of players, given by the list n. What numbers will be assigned?

This is a job for a ragged array: a list for each team, but different lengths.

In J, you have to do this with a list of boxed lists

```   n =. 5 4 5 2
]jerseys =: <@i."0 n
+---------+-------+---------+---+
|0 1 2 3 4|0 1 2 3|0 1 2 3 4|0 1|
+---------+-------+---------+---+
```

Suppose you want the list of all jersey numbers. That's what ;y gives you:

```   ;jerseys
0 1 2 3 4 0 1 2 3 0 1 2 3 4 0 1
```

If you simply opened the array, you would get a table with fill:

```   >jerseys
0 1 2 3 4
0 1 2 3 0
0 1 2 3 4
0 1 0 0 0
```

### Related Primitives

Append (,), Append Items (,.), Laminate (,:)

### Details

; y collects the contents of y into a single array. The operation of ; y resembles collecting cell results into the result of a verb, but with important differences:

 Differences between collection and ; y Collection ; y The frame of the arguments becomes part of the shape of the result The shape of y is immaterial; cells of the contents of y are assembled along a single axis The full results of the verb executions are organized into an array Cells of the contents are put into an array All results smaller than the largest are padded with framing fill, which cannot be changed Array cells smaller than the result cell-size are padded with verb fill, which can be specified by !.f Atomic results are padded just like arrays Atomic contents are replicated to the shape of the result cell

The steps are:

#### Find The Type And Precision Of The Result

Any values to be joined must have the same type. The precision of the result is determined in the same way as for collection.

#### Find The Rank Of An Item Of The Result

The rank of an item of the result is the maximum of the item ranks of the contents.

Thus, if all the contents are atoms or lists, the items of the result will be atoms; but if any contents has higher rank, the rank of an item of the result is one less than the maximum rank of the contents.

#### Bring Array Contents To A Common Rank

Once the rank of the result items is known, each array contents is brought up to one more than the result rank, by adding as many leading axes of length 1 as needed.

After this step, all the array contents can be thought of as a list of items with the result-item rank (but not necessarily the correct shape).

Atomic contents have not been modified and are still atoms.

The contents after this step are called the extended contents.

#### Find The Shape Of An Item Of The Result

The shape of an item of the result is the maximum of the shapes of the items of the extended contents, where the maximum is taken over each axis separately.

Note: the result items may be nonempty, even though each contents is empty.

#### Bring Items To A Common Shape: Fill And Atomic Extension

Each item of each of the extended contents is brought up to the shape of an item of the result. An Atomic contents is replicated to the shape of an item of the result and then has one additional leading axis of length 1 added, to bring the contents to the common rank. Each item of Array contents is filled by extending each axis as needed, adding verb fill atoms which are the value specified by !.f if that was supplied, or otherwise the framing fill appropriate for the result type.

Atomic contents are always replicated, never filled.

The contents after this step are called the filled contents.

#### Assembly Into The Final Result

The filled contents are all arrays of the same rank, with items of the same shape. These items are arranged along a single axis to produce the final result, which is always an array.

#### Illustrative Examples

```   \$ ; <'a'                   NB. The result is always an array
1

\$ ; 'ab';'c'               NB. Items are atoms
3

\$ ; (2\$0);''               NB. Items are atoms; 0-atom operand does not contribute to result
2

\$ ; (2\$0);(0 2\$' ')        NB. Items are lists (because of 0 2\$0), so 2\$0 is extended to 1 2\$0
1 2

; (2\$0);(0 2\$' ')          NB. The 0 2\$' ' affected the shape, but contributed no items
0 0

; (i. 2 2 2);(0 2\$' ')     NB. Items are 2x2 tables; 0 2\$' ' was filled to become 1 2 2\$0
0 1
2 3

4 5
6 7

0 0
0 0
; (i. 3 3 3);(' ')         NB.  The character cannot be replicated to match the integer
|domain error

; (0\$0);(0 2\$0)            NB. Empties join to make nonempty! (0\$0)=>(1 0\$0); items are 2-element lists; so (1 0\$0) is filled.
0 0
\$ ; (0\$0);(0 2\$0)          NB. (0 2\$0) does not need fill, so it is 0 lists and does not contribute to the result
1 2

; (i. 2 3);4               NB. Atomic replication
0 1 2
3 4 5
4 4 4

; (i. 3 2);(i. 3);9        NB. Items are 3-atom lists.  The items of (i. 3 2) are filled; 9 is replicated
0 1 0
2 3 0
4 5 0
0 1 2
9 9 9

;!.100 (i. 3 2);(i. 3);9   NB. Fill can be changed, but not replication
0 1 100
2 3 100
4 5 100
0 1   2
9 9   9
```

### Oddities

1. If all contents are empty, but the result is nonempty, and a fill is specified of a different type from the contents, the result is erroneous.

```   ;!.'a' (0 2\$4);''
24929 0
;!.2 (0 2\$a:);''
--- J hangs ---
```

### Use These Combinations

Combinations using ; y that have exceptionally good performance include:

 What it does Type; Precisions; Ranks Syntax Variants; Restrictions Benefits; Bug Warnings Extract multiple substrings into a list Boolean list, byte list x ;@:(<;.0) y or [: ; <;.0 avoids boxing, avoids creating subarrays Razed selections x (;@{) y also x ([: ; {) y Concatenated results on intervals ;@:(<@u;.n) y n e. _2 _1 1 2; also [: ; (<@:u;.n); also <@u;.n Bug Warning: This is computed as <@:u even if <@u is coded x is a Boolean list (not an atom or an integer list with values 0 or 1) x ;@:(<@u;.n) y Concatenated running totals on intervals (running total, but total is reset at start of each interval) ;@:(<@(f/\);.n) y x ;@:(<@(f/\);.n) y (f is any verb) n e. _2 _1 1 2; also [: ; (f... also <@:(f/\); also <@:

Rank Infinity -- operates on x and y as a whole -- WHY IS THIS IMPORTANT?

Links x and y to build up a list of boxed items.

If y is already boxed and not empty, does not box it again.

This makes it less clumsy to build a list of more than 2 boxed items.

```   ]z=: 'alpha' ; 'bravo' ; 'charlie'
+-----+-----+-------+
|alpha|bravo|charlie|
+-----+-----+-------+
```

### Common uses

1. Combine nouns of different types into a single noun.

```   ]score =: 'Gauss',100   NB. Can't join dissimilar types
|domain error
]score =: 'Gauss';100   NB. but boxing them makes it OK
+-----+---+
|Gauss|100|
+-----+---+
```

2. Use boxing to create a ragged two-dimensional array where rows have different lengths:

```   0 2 ,: 4 2 5 7   NB. Joining unequal lengths produces fill
0 2 0 0
4 2 5 7
0 2 ; 4 2 5 7    NB. Boxing preserves individual lengths
+---+-------+
|0 2|4 2 5 7|
+---+-------+
```

3. Collect the arguments to a verb into a single noun that can be passed as a single argument. The linked argument is typically broken apart at the beginning of the verb using a multiple assignment.

```   NB. Verb to compute payroll.  y is a list of (name;hourly rate;hours worked)
payroll =: verb define"1
'name rate hours' =. y   NB. Multiple assignment breaks up boxed list
'Pay for ' , name , ' = ' , ": rate * hours
)
payroll 'Fred';30;40   NB. Join the 3 arguments into 1 noun
Pay for Fred = 1200
```

### Related Primitives

Append (,)

1. x ; y boxes y only if it is empty or not boxed. This makes it easier to create long lists of boxes:

```   1;2;3;4
+-+-+-+-+
|1|2|3|4|
+-+-+-+-+
1;(2;3);4
+-+-----+-+
|1|+-+-+|4|
| ||2|3|| |
| |+-+-+| |
+-+-----+-+
```

Usually you want to box the rightmost value in a sequence of ;s, even if it is boxed already. For example

```   (<1);(<2);(<3)   NB. Probably NOT what was intended
+---+---+-+
|+-+|+-+|3|
||1|||2|| |
|+-+|+-+| |
+---+---+-+
```

It is a good habit to follow the rightmost ; in a sequence with < to solve this problem

```   (<1);(<2);<(<3)
+---+---+---+
|+-+|+-+|+-+|
||1|||2|||3||
|+-+|+-+|+-+|
+---+---+---+
```

Another solution, if you are joining only 2 arguments, is to use ,&< instead

```   (<1);(<2)
+---+-+
|+-+|2|
||1|| |
|+-+| |
+---+-+
(<1) ,&< (<2)
+---+---+
|+-+|+-+|
||1|||2||
|+-+|+-+|
+---+---+
```

### Use These Combinations

Combinations using x ; y that have exceptionally good performance include:

 What it does Type; Precisions; Ranks Syntax Variants; Restrictions Benefits; Bug Warnings Box items of list ;/ y linear time (like <"_1 y)