From c7ef3aabb54791b597d4095011ff048c2a13f6ac Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Sat, 7 Aug 2021 20:57:51 -0400 Subject: Document use of fill elements for merge of empty --- docs/doc/couple.html | 2 +- docs/doc/fill.html | 3 ++- docs/doc/types.html | 2 +- 3 files changed, 4 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/doc/couple.html b/docs/doc/couple.html index 164c0fd5..1923e9d1 100644 --- a/docs/doc/couple.html +++ b/docs/doc/couple.html @@ -65,7 +65,7 @@ ∾ ⥊ ⥊¨ a "ABrstABuvwABxyzCDrstCDuvwCDxyz" -

The way this happens, and the constraint that all inner arrays have the same shape, is closely connected to the concept of an array, and like Table ⌜, Merge might be considered a fundamental way to build up multidimensional arrays from lists. In both cases rank-0 or unit arrays are somewhat special. They are the identity value of a function with Table, and can be produced by Merge inverse, >⁼ on a list, which forces either the outer or inner shape to be empty (BQN chooses >⁼ to be <, but only on an array, as > cannot produce non-arrays). Merge has another catch as well: it cannot produce arrays with a 0 in the shape, except at the end, unless fills can be specified.

+

The way this happens, and the constraint that all inner arrays have the same shape, is closely connected to the concept of an array, and like Table ⌜, Merge might be considered a fundamental way to build up multidimensional arrays from lists. In both cases rank-0 or unit arrays are somewhat special. They are the identity value of a function with Table, and can be produced by Merge inverse, >⁼ on a list, which forces either the outer or inner shape to be empty (BQN chooses >⁼ to be <, but only on an array, as > cannot produce non-arrays). Merge has another catch as well: it cannot produce arrays with a 0 in the shape, except at the end, without relying on a fill element.

↗️
    ⊢ e ← ⟨⟩¨ ↕3
 ⟨ ⟨⟩ ⟨⟩ ⟨⟩ ⟩
     ≢ > e
diff --git a/docs/doc/fill.html b/docs/doc/fill.html
index 843e80e8..e77872c4 100644
--- a/docs/doc/fill.html
+++ b/docs/doc/fill.html
@@ -6,7 +6,7 @@
 
BQN / main / doc

 
Fill elements

 
A few array operations need an array element to use when no existing element applies. BQN tries to maintain a "default" element for every array, known as a fill element, for this purpose. If it's known, the fill element is a nested array structure where each atom is either 0 or ' '. If no fill is known, a function that requests it results in an error.

-
Fills are used by Take (↑) when a value in 𝕨 is larger than the corresponding length in 𝕩, by the two Nudge functions (»«) when 𝕩 is non-empty, and by Reshape (⥊) when 𝕨 contains ↑. Except for these specific cases, the fill value an array has can't affect the program. The result of Match (≡) doesn't depend on fills, and any attempt to compute a fill can't cause side effects.

+
Fills are used by Take (↑) when a value in 𝕨 is larger than the corresponding length in 𝕩, by the two Nudge functions (»«) when 𝕩 is non-empty, by Merge (>) when 𝕩 is empty, and by Reshape (⥊) when 𝕨 contains ↑. Except for these specific cases, the fill value an array has can't affect the program. The result of Match (≡) doesn't depend on fills, and any attempt to compute a fill can't cause side effects.

 
Using fills

 
For the examples in this section we'll use the fact that an all-number array usually has 0 as a fill while a string has ' ' (BQN maintains fills alongside array values rather than deriving them from arrays, so it's possible to construct arrays where this isn't true, but this probably wouldn't happen in ordinary code).

 
Take (↑) and Nudge (»«) in either direction use the fill for padding, to extend the array past its boundary. For example, 𝕨↑𝕩 will add elements to one side when a number in |𝕨 is larger than the corresponding length in ≢𝕩.

@@ -26,6 +26,7 @@
     »⟨⟩   # Fill not needed
 ⟨⟩
+

If the argument to Merge is empty then its result will be as well, since the shape ≢𝕩 is a prefix of ≢>𝕩. However, the remainder of the result shape is determined by the elements of 𝕩, so if there are none then Merge uses the fill element to decide what the result shape should be.

Reshape (⥊) uses the fill when 𝕨 contains ↑ and the product of the rest of 𝕨 doesn't evenly divide the number of elements in 𝕩.

↗️
    ↑‿8 ⥊ "completepart"
 ┌─          
diff --git a/docs/doc/types.html b/docs/doc/types.html
index bcc119f6..8d3c4e39 100644
--- a/docs/doc/types.html
+++ b/docs/doc/types.html
@@ -59,7 +59,7 @@
 
Arrays

 
Full documentation here.

 
A BQN array is a multidimensional arrangement of data. This means it has a certain shape, which is a finite list of natural numbers giving the length along each axis, and it contains an element for each possible index, which is a choice of one natural number that's less than each axis length in the shape. The total number of elements, or bound, is then the product of all the lengths in the shape. The shape may have any length including zero, and this shape is known as the array's rank. An array of rank 0, which always contains exactly one element, is called a unit, while an array of rank 1 is called a list and an array of rank 2 is called a table.

-
Each array—empty or nonempty—has an inferred property called a fill. The fill either indicates what element should be used to pad an array, or that such an element is not known and an error should result. Fills can be used by Take (↑), the two Nudge functions (»«), and Reshape (⥊).

+
Each array—empty or nonempty—has an inferred property called a fill. The fill either indicates what element should be used to pad an array, or that such an element is not known and an error should result. Fills can be used by Take (↑), the two Nudge functions (»«), Merge (>), and Reshape (⥊).

 
Arrays are value types (or immutable), so that there is no way to "change" the shape or elements of an array. An array with different properties is a different array. As a consequence, arrays are an inductive type, and it's not possible for an array to contain itself, or contain an array that contains itself, and so on. However, it is possible for an array to contain a function or other operation that has access to the array through a variable, and in this sense an array can "know about" itself.

 
Different elements of an array should not influence each other. While some APLs force numbers placed in the same array to a common representation, which may have different precision properties, BQN values must not change behavior when placed in an array. However, this doesn't preclude changing the storage type of an array for better performance: for example, in a BQN implementation using 64-bit floats, an array whose elements are all integers that fit in 32-bit int range might be represented as an array of 32-bit ints.

 
Operation types

-- 
cgit v1.2.3