Commentary on search functions

1 files changed, 16 insertions, 0 deletions

diff --git a/docs/spec/primitive.html b/docs/spec/primitive.html
index c8db181e..4e9ef995 100644
--- a/docs/spec/primitive.html
+++ b/docs/spec/primitive.html
@@ -119,3 +119,19 @@
 <p><strong>Join To</strong> (<code><span class='Function'>∾</span></code>) combines its two arguments along an existing initial axis, unless both arguments are units, in which case it creates an axis and is identical to Couple (<code><span class='Function'>≍</span></code>). The arguments must differ in rank by at most 1, and the result rank is equal to the maximum of 1 and the higher argument rank. Each argument with rank less than the result, and each major cell of an argument with rank equal to it, becomes a major cell of the result, with cells from the left argument placed before those from the right. <strong>Join</strong> (<code><span class='Function'>∾</span></code>) generalizes the equal-rank subset of this behavior to an array of values instead of just two. The argument must be an array (unlike Merge), and its elements must all the same rank, which is at least the argument rank. Atom elements are treated as unit arrays. Then &quot;outer&quot; argument axes are matched up with leading &quot;inner&quot; element axes, and elements are joined along these axes. In order to allow this, the length of an element along a particular axis must depend only on the position along the corresponding axis in the argument. An empty argument to Join is return unchanged, as though the element rank is equal to the argument rank.</p>
 <p><strong>Deshape</strong> (<code><span class='Function'>⥊</span></code>) differs from the provided function (which returns the element list of an array) only in that it accepts an atom, returning a one-element list containing it. <strong>Reshape</strong> (<code><span class='Function'>⥊</span></code>) is extended in numerous ways. It accepts any list of natural numbers (including as a unit array or atom) for the left argument and any right argument; <code><span class='Value'>𝕩</span></code> is deshaped first so that it is treated as a list of elements. These elements are repeated cyclically to fill the result array in ravel order. If <code><span class='Value'>𝕩</span></code> is empty but the result is not, then the result consists of fill elements for <code><span class='Value'>𝕩</span></code>. Furthermore, at most one element of <code><span class='Value'>𝕨</span></code> can be a &quot;length code&quot;: one of the primitives <code><span class='Modifier2'>∘</span><span class='Function'>⌊⌽↑</span></code>. In this case, a target length is computed from the number of elements in <code><span class='Value'>𝕩</span></code> divided by the product of the other elements of <code><span class='Value'>𝕨</span></code> (which must not be zero). If the target length is an integer then it is used directly for the length code. Otherwise, an error is given if the length code is <code><span class='Modifier2'>∘</span></code>, and the target length is rounded down if the code is <code><span class='Function'>⌊</span></code> and up if it's <code><span class='Function'>⌽</span></code> or <code><span class='Function'>↑</span></code>. With code <code><span class='Function'>⌽</span></code>, elements are repeated cyclically as usual, but with code <code><span class='Function'>↑</span></code>, the extra elements after each argument element is used are fill values for <code><span class='Value'>𝕩</span></code>.</p>
 <p><strong>Transpose</strong> (<code><span class='Function'>⍉</span></code>) reorders axes of its argument to place the first axis last; if the argument has one or fewer axes then it's returned unchanged. <strong>Reorder Axes</strong> (<code><span class='Function'>⍉</span></code>) requires the left argument to be a list or unit of natural numbers, with length at most the rank of the right argument. This list is extended to match the right argument rank exactly by repeatedly appending the least unused natural number (for example, given <code><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>0</span></code>, <code><span class='Number'>2</span></code> is appended). After extension, it specifies a result axis for each axis of the right argument. There must be no gaps in the list: that is, with the result rank equal to one plus the greatest value present, every result axis must appear at least once. Now each argument axis is &quot;sent to&quot; the specified result axis: in terms of indices, <code><span class='Value'>i</span><span class='Function'>⊑</span><span class='Value'>𝕨</span><span class='Function'>⍉</span><span class='Value'>𝕩</span></code> is <code><span class='Paren'>(</span><span class='Value'>𝕨</span><span class='Function'>⊏</span><span class='Value'>i</span><span class='Paren'>)</span><span class='Function'>⊑</span><span class='Value'>𝕩</span></code> if <code><span class='Value'>𝕨</span></code> is complete. If multiple argument axes correspond to the same result axis, then a diagonal is taken, and it's as long as the shortest of those argument axes. While Transpose does not enclose an atom right argument, Reorder Axes does, so that its result is always an array.</p>
+<h3 id="searching">Searching</h3>
+<p><strong>Match</strong> (<code><span class='Function'>≡</span></code>) indicates whether two values are considered equivalent. It always returns 0 or 1, and never causes an error. If both arguments are atoms then it is identical to <code><span class='Function'>=</span></code>, and if one is an atom and the other an array then it returns 0. If both arguments are arrays then it returns 1 only if they have the same shape and all pairs of corresponding elements match. Fill elements aren't taken into account, so that arrays that match might still differ in behavior. <strong>Not Match</strong> simply returns the complement of Match, <code><span class='Function'>¬≡</span></code>.</p>
+<p>Monadic search functions compare the major cells of <code><span class='Value'>𝕩</span></code> to each other. <code><span class='Value'>𝕩</span></code> must have rank at least 1. Except for Unique (<code><span class='Function'>⍷</span></code>), the result is a list of numbers with the same length as <code><span class='Value'>𝕩</span></code>.</p>
+<ul>
+<li><strong>Unique Mask</strong> (<code><span class='Function'>∊</span></code>) returns 1 for a cell if it doesn't match any earlier cell and 0 if it does.</li>
+<li><strong>Deduplicate</strong> (<code><span class='Function'>⍷</span></code>) filters major cells to remove duplicates, retaining the ordering given by the first appearance of each unique cell.</li>
+<li><strong>Classify</strong> (<code><span class='Function'>⊐</span></code>) returns, for each cell, the smallest index of a cell that matches it (it's necessarily less than or equal to <code><span class='Function'>↕≠</span><span class='Value'>𝕩</span></code> element-wise, since each cell matches itself).</li>
+<li><strong>Occurrence Count</strong> (<code><span class='Function'>⊒</span></code>) returns the number of earlier cells matching each cell.</li>
+</ul>
+<p>Dyadic search functions check whether major cells of the <em>principal argument</em> (which must have rank at least 1) match cells of the <em>non-principal argument</em> of the same rank. The rank of the non-principal argument can't be less than the major cell rank (rank minus one) of the principal argument. However, the non-principal argument can be an atom, in which case it will be automatically enclosed. The principal argument is <code><span class='Value'>𝕨</span></code> for <code><span class='Function'>⊐</span></code> and <code><span class='Function'>⊒</span></code> and <code><span class='Value'>𝕩</span></code> for <code><span class='Function'>∊</span></code>. The result is an array containing one number for each cell of the non-principal argument. The value of this number depends on the function:</p>
+<ul>
+<li><strong>Member of</strong> (<code><span class='Function'>∊</span></code>) indicates whether any cell of the principal argument matches the cell in question.</li>
+<li><strong>Index of</strong> (<code><span class='Function'>⊐</span></code>) gives the smallest index of a principal argument cell that matches the cell, or <code><span class='Function'>≠</span><span class='Value'>𝕨</span></code> if there is no such cell.</li>
+<li><strong>Progressive Index of</strong> (<code><span class='Function'>⊒</span></code>) processes non-principal cells in ravel order, and gives the smallest index of a principal argument cell that matches the cell that hasn't already been included in the result. Again <code><span class='Function'>≠</span><span class='Value'>𝕨</span></code> is returned for a given cell if there is no valid cell.</li>
+</ul>
+<p><strong>Find</strong> (<code><span class='Function'>⍷</span></code>) indicates positions where <code><span class='Value'>𝕨</span></code> appears as a contiguous subarray of a <code><span class='Function'>=</span><span class='Value'>𝕨</span></code>-cell of <code><span class='Value'>𝕩</span></code>. It has one result element for each such subarray of <code><span class='Value'>𝕩</span></code>, whose value is 1 if that subarray matches <code><span class='Value'>𝕩</span></code> and 0 otherwise.</p>