More advanced custom function tutorial (#1108)

* Start writing a custom function example for GREET() * Export FunctionArgumentType enum * Move custom function tests from square-plugin-example.spec.ts to custom-functions.spec.ts * Add unit tests for custom functions implemented with runFunction * WIP * Update the code snippets in the custom functions guide to match the new demo (GREET) * Add info about unit tests to the custom functions guide * Rewrite custom function options section in custom functions guide * Export ArraySize class * Update custom-functions guide after changes in the demo * Structural changes in the custom-functions guide * Move SimpleRangeValue from ./src/interpreter to ./src so that the typedoc documentation is generated for it * Describe DOUBLE_RANGE function in the custom-functions guide * Use ArraySize in the example of arraySizeMethod in the custom-functiosn guide * Add changelog entry * Add the description for the arraySizeMethod option * Rephrase a few sentences in the custom-functions guide * Improve the description of returnNumberType option in the custom-functions guide * Add default values to the custom function options description * Add possible values to the argumentType description in the custom-fucntions guide * Reduce content duplication on custom function name translations * Minor improvements to custom-functions guide * grammarly fixes * Reformat table * Improve the description of the vectorization feature * code review fixes * Change translations object to be standalone instead of a static property in the custom functions guide * Use FunctionArgumentType enum in custom functions guide * Fix typo
handsontable · Dec 20, 2022 · 1696cbc · 1696cbc
1 parent aa3f7c0
commit 1696cbc
Show file tree

Hide file tree

Showing 70 changed files with 1,210 additions and 1,036 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Expanded the HyperFormula public API by adding the code entities that are necessary to implement a complex custom function: `ArraySize`, `ImplementedFunctions`, `FunctionMetadata`, `FunctionArgumentType`. [#779](https://github.com/handsontable/hyperformula/issues/779)
+
 ## [2.2.0] - 2022-11-17
 
 ### Added

diff --git a/docs/guide/arrays.md b/docs/guide/arrays.md
@@ -72,7 +72,7 @@ ISEVEN(A2:A5*10)
 
 Thanks to HyperFormula's built-in array features, you can:
 * [Operate on arrays](#operating-on-arrays) just like on [scalars](#about-arrays)
-* [Pass arrays to functions](#passing-arrays-to-scalar-functions) that accept [scalars](#about-arrays)
+* [Pass arrays to functions](#passing-arrays-to-scalar-functions-vectorization) that accept [scalars](#about-arrays)
 * [Broadcast](#broadcasting) smaller input arrays across larger output areas
 
 You can also:
@@ -83,7 +83,7 @@ You can also:
 
 You can operate on arrays just like on single values.
 
-When the [array arithmetic mode](#enabling-the-array-arithmetic-mode) is enabled, each output array value is the result of your operation on the corresponding input array value.
+When the [array arithmetic mode](#array-arithmetic-mode) is enabled, each output array value is the result of your operation on the corresponding input array value.
 
 ```
 =ARRAYFORMULA(A2:A5*B2:B5)
@@ -95,22 +95,23 @@ When the [array arithmetic mode](#enabling-the-array-arithmetic-mode) is enabled
 // =A5*B5
 ```
 
-### Passing arrays to scalar functions
-You can pass arrays to functions that would normally accept [scalars](#about-arrays) (thanks to HyperFormula's **vectorization** feature).
+### Passing arrays to scalar functions (vectorization)
 
-When the [array arithmetic mode](#enabling-the-array-arithmetic-mode) is enabled, and you pass an array to a [scalar](#about-arrays) function, that function produces an array on the output as well.
+When the [array arithmetic mode](#array-arithmetic-mode) is enabled, HyperFormula automatically _vectorizes_ most functions.
+
+As a consequence of that, you can pass arrays to functions that would normally accept [scalars](#about-arrays). The result would also be an array.
 
 ```
-=ARRAYFORMULA(ISEVEN(A2:A5*10))
+=ARRAYFORMULA(ISEVEN(A2:A5))
 
 // calculates:
-// =ISEVEN(A2*10)
-// =ISEVEN(A3*10)
-// =ISEVEN(A4*10)
-// =ISEVEN(A5*10)
+// =ISEVEN(A2)
+// =ISEVEN(A3)
+// =ISEVEN(A4)
+// =ISEVEN(A5)
 ```
 
-#### Broadcasting
+### Broadcasting
 
 If an input array has a dimension of `1`, it's automatically repeated ("broadcast") on that dimension to match the size of the output.
 
@@ -126,15 +127,15 @@ If an input array has a dimension of `1`, it's automatically repeated ("broadcas
 
 ### Filtering an array
 
-When the [array arithmetic mode](#enabling-the-array-arithmetic-mode) is enabled, you can filter an array, based on boolean arrays, using the `FILTER` function:
+When the [array arithmetic mode](#array-arithmetic-mode) is enabled, you can filter an array, based on boolean arrays, using the `FILTER` function:
 
 | Syntax                                               | Example                                         |
 |:-----------------------------------------------------|:------------------------------------------------|
 | `FILTER(your_array, BoolArray1[, BoolArray2[, ...]]` | `=ARRAYFORMULA(FILTER(A2:A5*10), {1, 0, 0, 1})` |
 
 ### Constraining an array's size
 
-When the [array arithmetic mode](#enabling-the-array-arithmetic-mode) is enabled, you can constrain the size of the output array, using the `ARRAY_CONSTRAIN` function:
+When the [array arithmetic mode](#array-arithmetic-mode) is enabled, you can constrain the size of the output array, using the `ARRAY_CONSTRAIN` function:
 
 | Syntax                                     | Example                                       |
 |:-------------------------------------------|:----------------------------------------------|
@@ -148,17 +149,17 @@ If your specified output array size is larger or equal to the input array size,
 
 ### With the array arithmetic mode enabled
 
-When the [array arithmetic mode](#enabling-the-array-arithmetic-mode) is enabled, and you pass an array to a [scalar](#about-arrays) function, the following rules apply:
+When the [array arithmetic mode](#array-arithmetic-mode) is enabled, and you pass an array to a [scalar](#about-arrays) function, the following rules apply:
 * Array dimensions need to be consistent (e.g. every row needs to be of the same length).
 * If an input array value is missing (due to a difference in dimensions), the corresponding output array value is `#N/A`.
 * If a cell evaluates to an array, the array values are spilled into neighboring cells (unless the neighboring cells are already filled).<br>This behavior doesn't apply to ranges, which return the `#VALUE!` error in this case.
 * If one of input array dimensions is `1` (`1`x`n` or `n`x`1`), the array is repeated, to match the output array dimensions.
 
 ### With the array arithmetic mode disabled
 
-When the [array arithmetic mode](#enabling-the-array-arithmetic-mode) is disabled, and you pass an array to a [scalar](#about-arrays) function, the array is reduced to 1 element (usually the array's top-left value).
+When the [array arithmetic mode](#array-arithmetic-mode) is disabled, and you pass an array to a [scalar](#about-arrays) function, the array is reduced to 1 element (usually the array's top-left value).
 
-When the [array arithmetic mode](#enabling-the-array-arithmetic-mode) is disabled, and you operate on a range of width/height equal to `1`, the behavior depends on your array formula's location:
+When the [array arithmetic mode](#array-arithmetic-mode) is disabled, and you operate on a range of width/height equal to `1`, the behavior depends on your array formula's location:
 
 | Your array formula's location                     | Behavior                               |
 |:--------------------------------------------------|:---------------------------------------|