From 54d28433b31af8bbd9c0ab3af7a46a4fcab6750b Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Mon, 8 Feb 2021 21:58:36 -0500 Subject: Explicitly describe iteration order for Each and similar modifiers --- docs/spec/primitive.html | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/spec/primitive.html b/docs/spec/primitive.html index 8a7a9a70..30549201 100644 --- a/docs/spec/primitive.html +++ b/docs/spec/primitive.html @@ -108,6 +108,7 @@

Iteration modifiers

Modifiers for iteration are defined in layers 1, 2, and 4. Two 2-modifiers, ⚇ and ⎉, use a list of numbers obtained by applying the right operand to the arguments in order to control application. This list has one to three elements: if all three are given then they correspond to the monadic, left, and right arguments; if one is given then it controls all three; and if two are given then they control the left argument, and the right and monadic arguments.

+

The iteration modifiers ⌜¨⚇˘⎉ process elements or cells in index order, that is, according to lexicographic ordering of indices or according to simple numeric ordering of the indices in the Deshaped (⥊) arguments. When both arguments are mapped over independently, the left argument is mapped over "first", or as an outer loop: one part of the left argument is paired with each part of the right in turn, then the next part of the left argument, and so on.

Table (⌜) and Each (¨) map over the elements of arrays to produce result elements. They convert atom arguments to unit arrays. With one argument, the two modifiers are the same; with two, they differ in how they pair elements. Table pairs every element of the left argument with every element of the right, giving a result shape 𝕨∾○≢𝕩. Each uses leading axis agreement: it requires one argument's shape to be a prefix of the other's (if the arguments have the same rank, then the shapes must match and therefore be mutual prefixes). This causes each element of the lower-rank argument to correspond to a cell of the higher-rank one; it's repeated to pair it with each element of that cell. The result shape is the shape of the higher-rank argument.

Depth (⚇) is nearly a generalization of Each: ¨ is equivalent to ⚇¯1, except that ⚇¯1 doesn't enclose its result if all arguments are atoms. The list given by the right operand specifies how deeply to recurse into the arguments. A negative number -n means to recurse n times or until the argument is an atom, while a positive number n means to recurse until the argument has depth n or less. Recursion continues until all arguments have met the criterion for stopping. This recursion is guaranteed to stop because arrays are immutable, and form an inductive type.

Rank (⎉) applies the left operand to cells of the arguments of the specified ranks, forming a result whose cells are the results. Cells (˘) is identical to ⎉¯1, and applies to major cells of the arguments, where a value of rank less than 1 is considered its own major cell. All results must have the same shape, as with elements of the argument to Merge (>). The combined result is always an array, but results of the left operand can be atoms: an atom result will be enclosed to give a 0-cell. If a specified rank is a natural number n, Rank applies the operand to n-cells of the corresponding argument, or the entire argument if it has rank less than or equal to n. If instead it's a negative integer -n, then an effective rank of 0⌈k-n is used, so that the entire argument is used exactly when k=0. Thus an atom will always be passed unchanged to the operand; in particular, Rank does not enclose it. Like Each, Rank matches cells of its arguments according to leading axis agreement, so that a cell of one argument might be paired with multiple cells of the other.

-- cgit v1.2.3