Add TOROW and TOCOL functions (HF-388, HF-387)

CHANGELOG.md

@@ -7,6 +7,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+### Added
+
+- Added the `TAKE` dynamic-array function. [#1722](https://github.com/handsontable/hyperformula/pull/1722)
+- Added the `DROP` dynamic-array function. [#1796](https://github.com/handsontable/hyperformula/pull/1796)
+- Added the `TOROW` and `TOCOL` dynamic-array functions. [#1828](https://github.com/handsontable/hyperformula/pull/1828)
+
 ### Fixed
 
 - Fixed the `AVERAGEIF` function returning a division-by-zero error when the calculated average was `0`. [#1733](https://github.com/handsontable/hyperformula/pull/1733)

docs/guide/known-limitations.md

@@ -61,6 +61,10 @@ a circular reference.
 
 * Ordering (including mixed types, empty cells, and text collation) follows HyperFormula's own comparison rules, which honor the `caseSensitive` and `accentSensitive` configuration options. Numbers sort before text, and text before logical values.
 
+### TOROW and TOCOL functions
+
+* When formulas on two sheets flatten each other's whole columns below the first row and skip blank cells, for example `=TOCOL(Sheet2!A:A, 1)` in cell B5 of Sheet1 and `=TOCOL(Sheet1!A:A, 1)` in cell B5 of Sheet2, the space reserved for each result counts toward the size of the other sheet. Both sheets get taller than their data, and taller again each time one of these formulas is entered again. The results stay correct. TOROW behaves the same way with whole rows right of the first column.
+
 ### OFFSET function
 
 HyperFormula resolves the OFFSET function at parse time rather than during evaluation. The parser inspects the arguments and rewrites the expression into a plain cell reference or range. This keeps the dependency graph accurate but imposes several restrictions.

docs/guide/list-of-differences.md

@@ -46,6 +46,8 @@ See a full list of differences between HyperFormula, Microsoft Excel, and Google
 | Ranges created with `:`                            | A1:A2<br><br>A$1:$A$2<br><br>A:C<br><br>1:2<br><br>Sheet1!A1:A2           | Allowed ranges consist of two addresses (A1:B5), columns (A:C) or rows (3:5).<br>They cannot be mixed or contain named expressions.                                                                                                                                                                                                                          | Everything allowed.                                                                                                            | Same as Google Sheets.                                                                                                         |
 | Formatting inside the TEXT function                | TEXT(A1,"dd-mm-yy")<br><br>TEXT(A1,"###.###”)                             | To support all date, time and currency formats, set [`stringifyDateTime`](compatibility-with-microsoft-excel.md#date-and-time-formats) and [`stringifyCurrency`](currency-handling.md) configuration options.                                                                                                                                                                                                                                                                                                  | A wide variety of options for string formatting is supported.                                                                  | Same as Google Sheets.                                                                                                         |
 | Cell references inside inline arrays               | ={A1, A2}                                                                 | The array's value is calculated but not updated when the cells' values change.                                                                                                                                                                                                                                                                               | The array's value is calculated and updated when the cells' values change.                                                     | ERROR: invalid array                                                                                                           |
+| Errors in array results                            | =DROP(Data!A1:C3, NA())                                                   | The error fills the whole area reserved for the array (here 3x3), because the array's size is predicted before the formula is evaluated.                                                                                                                                                                                                                     | No such function.                                                                                                              | A single N/A error.                                                                                                            |
+| Array size that depends on cell values             | =DROP(Data!A1:C3, Counts!A1) in A1,<br>where Counts!A1 = 1 and A3 holds a value | Returns SPILL: the whole source (3x3) is reserved, because the count is read after the array's size is set.                                                                                                                                                                                                                                                  | No such function.                                                                                                              | Spills the two remaining rows into A1:C2.                                                                                      |
 | SPLIT function                                     | =SPLIT("Lorem ipsum dolor", 0)                                            | This function works differently from Google Sheets version but should be sufficient to achieve the same functionality in most scenarios. Read SPLIT function description on [the Built-in Functions page](built-in-functions.md#text).                                                                                                                       | Different syntax and return value.                                                                                             | No such function.                                                                                                              |
 | DATEVALUE function                                 | =DATEVALUE("25/02/1991")                                                  | Type of the returned value: `CellValueDetailedType.NUMBER_DATE` (compliant with the [OpenDocument](https://docs.oasis-open.org/office/OpenDocument/v1.3/os/part4-formula/OpenDocument-v1.3-os-part4-formula.html) standard)                                                                                                                                  | Cell auto-formatted as **regular number**                                                                                      | Cell auto-formatted as **regular number**                                                                                      |
 | TIMEVALUE function                                 | =TIMEVALUE("14:31")                                                       | Type of the returned value: `CellValueDetailedType.NUMBER_TIME` (compliant with the [OpenDocument](https://docs.oasis-open.org/office/OpenDocument/v1.3/os/part4-formula/OpenDocument-v1.3-os-part4-formula.html) standard)                                                                                                                                  | Cell auto-formatted as **regular number**                                                                                      | Cell auto-formatted as **regular number**                                                                                      |
@@ -116,6 +118,28 @@ To remove the differences, create [custom implementations](custom-functions.md)
 | NORMSDIST     | =NORMSDIST(0, TRUE())                                          |          0.5 |  Wrong number |    Wrong number |
 | ADDRESS       | =ADDRESS(1,1,4, TRUE(), "")                                    |          !A1 |         ''!A1 |             !A1 |
 | SEQUENCE      | =SEQUENCE(0)                                                   |        VALUE |           N/A |           CALC  |
+| TAKE          | =TAKE(A1:A3, 0)                                                |          N/A | No such function. |           CALC  |
+| TAKE          | =TAKE(Data!A:A, , 1)                                           | Spills to the source sheet's current height from row 1; returns SPILL below row 1. | No such function. | Spills all 1,048,576 rows from row 1, with blank source cells as 0; returns SPILL below row 1. |
+| DROP          | =DROP(A1:A3, 3)                                                |          N/A | No such function. |           CALC  |
+| DROP          | =DROP(Data!A:A, 1)                                             | Spills to the source sheet's current height minus one row; returns SPILL below row 2. | No such function. | Spills all 1,048,575 remaining rows, with blank source cells as 0; returns SPILL below row 2. |
+| DROP          | =DROP(Data!A:A, B1)                                            | Spills from row 1 only; returns SPILL below row 1, because the count is read after the result size is set. | No such function. | Spills 1,048,576 minus B1 rows when entered in row B1+1 or above; returns SPILL below. |
+| DROP          | =DROP(A1:C3, {1,2})                                            | Uses the first count and drops one row. | No such function. | Returns a 1x2 array of VALUE errors. |
+| DROP          | =ISREF(DROP(Data!A1:C3, 1))                                    | FALSE (returns values, not a reference) | No such function. | TRUE |
+| TOCOL         | =TOCOL(A1:A3, 1)<br>where A1:A3 are empty                      |          N/A | (measure) |           CALC  |
+| TOCOL         | =TOCOL(A1:A5, 1)<br>where A1:A5 = 1, (empty), 3, (empty), 5    | 1, 3, 5, then two blank cells: the source size (5x1) is reserved, because the skipped elements are known only after the array's size is set. | (measure) | 1, 3, 5 |
+| TOCOL         | =TOCOL(A1:C3, 0, {0,1})<br>where A1:C3 = 1, 2, 3; 4, 5, 6; 7, 8, 9 | Uses the first value of the array: 1 to 9 in one column, read by row. | (measure) | Returns a 1x2 array: 1, 1. |
+| TOCOL         | =ROWS(TOCOL(Data!A:A))                                         | The source sheet's current height. `=TOCOL(Data!A:A)` spills from row 1 only and returns SPILL below row 1. | (measure) | 1048576 |
+| TOCOL         | =TOCOL(Data!A:B)                                               |        SPILL | (measure) |             NUM |
+| TOCOL         | =TOCOL(A:A, 1)<br>entered in D5, where A1:A3 = 1, 2, 3       | SPILL. On the formula's own sheet, a whole column spills from row 1 only, and two or more whole columns return SPILL in any row, whatever the `ignore` value, because the result would make the sheet taller. | (measure) | 1, 2, 3 |
+| TOCOL         | =TOCOL(A:A+0, 1)<br>entered in D5, where A1:A3 = 1, 2, 3     | SPILL. A whole column computed by a formula, such as `A:A+0`, `Data!A:A+0` or `DROP(Data!A:A, 1)`, is sized by the `maxRows` setting. On any sheet, it spills from row 1 only, and two or more columns return SPILL in any row, whatever the `ignore` value. | (measure) | (measure) |
+| TOROW         | =TOROW(A1:A3, 1)<br>where A1:A3 are empty                      |          N/A | (measure) |           CALC  |
+| TOROW         | =TOROW(A1:A5, 1)<br>where A1:A5 = 1, (empty), 3, (empty), 5    | 1, 3, 5, then two blank cells: the source size (1x5) is reserved, because the skipped elements are known only after the array's size is set. | (measure) | 1, 3, 5 |
+| TOROW         | =TOROW(A1:C3, 0, {0,1})<br>where A1:C3 = 1, 2, 3; 4, 5, 6; 7, 8, 9 | Uses the first value of the array: 1 to 9 in one row, read by row. | (measure) | Returns a 1x2 array: 1, 1. |
+| TOROW         | =COLUMNS(TOROW(Data!1:1))                                      | The source sheet's current width. `=TOROW(Data!1:1)` spills from column A only and returns SPILL right of column A. | (measure) | 16384 |
+| TOROW         | =COLUMNS(TOROW(Data!A:A))                                      | The source sheet's current height. | (measure) | 1048576 |
+| TOROW         | =COLUMNS(TOROW(Data!A:B))                                      | Twice the source sheet's current height. | (measure) | NUM |
+| TOROW         | =TOROW(1:1, 1)<br>entered in E5, where A1:C1 = 1, 2, 3       | SPILL. On the formula's own sheet, a whole row spills from column A only, and two or more whole rows return SPILL in any column, whatever the `ignore` value, because the result would make the sheet wider. | (measure) | (measure) |
+| TOROW         | =TOROW(1:1+0, 1)<br>entered in E5, where A1:C1 = 1, 2, 3     | SPILL. A whole row computed by a formula, such as `1:1+0`, `Data!1:1+0` or `DROP(Data!1:1, , 1)`, is sized by the `maxColumns` setting. On any sheet, it spills from column A only, and two or more rows return SPILL in any column, whatever the `ignore` value. | (measure) | (measure) |
 | INT           | =INT(-8.9)                                                     |           -8 |            -9 |              -9 |
 | ISEVEN        | =ISEVEN(2.5)                                                   |        FALSE |          TRUE |            TRUE |
 | ISODD         | =ISODD(3.5)                                                    |        FALSE |          TRUE |            TRUE |

src/error-message.ts

@@ -67,6 +67,7 @@ export class ErrorMessage {
   public static IncorrectDateTime = 'String does not represent correct DateTime.'
   public static CharacterCodeBounds = 'Character code out of bounds.'
   public static NonZero = 'Argument cannot be 0.'
+  public static ZeroRowOrColumnCount = 'Row or column count cannot be zero.'
   public static LessThanOne = 'Argument cannot be less than 1.'
   public static WeekendString = 'Incorrect weekend bitmask string.'
   public static InvalidRoman = 'Invalid roman numeral.'

src/i18n/languages/csCZ.ts

@@ -98,6 +98,7 @@ const dictionary: RawTranslationPackage = {
     DELTA: 'DELTA',
     DOLLARDE: 'DOLLARDE',
     DOLLARFR: 'DOLLARFR',
+    DROP: 'ZAHODIT',
     EDATE: 'EDATE',
     EFFECT: "EFFECT",
     EOMONTH: 'EOMONTH',
@@ -225,6 +226,7 @@ const dictionary: RawTranslationPackage = {
     SWITCH: '',
     SYD: 'ODPIS.NELIN',
     T: 'T',
+    TAKE: 'VZÍT',
     TAN: 'TG',
     TANH: 'TGH',
     TBILLEQ: 'TBILLEQ',
@@ -234,7 +236,9 @@ const dictionary: RawTranslationPackage = {
     TEXTJOIN: 'TEXTJOIN',
     TIME: 'ČAS',
     TIMEVALUE: 'ČASHODN',
+    TOCOL: 'DO.SLOUPCE',
     TODAY: 'DNES',
+    TOROW: 'DO.ŘÁDKU',
     TRANSPOSE: 'TRANSPOZICE',
     TRIM: 'PROČISTIT',
     TRUE: 'PRAVDA',

src/i18n/languages/daDK.ts

@@ -98,6 +98,7 @@ const dictionary: RawTranslationPackage = {
     DELTA: 'DELTA',
     DOLLARDE: 'KR.DECIMAL',
     DOLLARFR: 'KR.BRØK',
+    DROP: 'UDELAD',
     EDATE: 'EDATO',
     EFFECT: "EFFEKTIV.RENTE",
     EOMONTH: 'SLUT.PÅ.MÅNED',
@@ -225,6 +226,7 @@ const dictionary: RawTranslationPackage = {
     SWITCH: '',
     SYD: 'ÅRSAFSKRIVNING',
     T: 'T',
+    TAKE: 'TAG',
     TAN: 'TAN',
     TANH: 'TANH',
     TBILLEQ: 'STATSOBLIGATION',
@@ -234,7 +236,9 @@ const dictionary: RawTranslationPackage = {
     TEXTJOIN: 'TEKST.KOMBINER',
     TIME: 'TID',
     TIMEVALUE: 'TIDSVÆRDI',
+    TOCOL: 'TILKOLONNE',
     TODAY: 'IDAG',
+    TOROW: 'TILRÆKKE',
     TRANSPOSE: 'TRANSPONER',
     TRIM: 'FJERN.OVERFLØDIGE.BLANKE',
     TRUE: 'TRUE',

src/i18n/languages/deDE.ts

@@ -98,6 +98,7 @@ const dictionary: RawTranslationPackage = {
     DELTA: 'DELTA',
     DOLLARDE: 'NOTIERUNGDEZ',
     DOLLARFR: 'NOTIERUNGBRU',
+    DROP: 'WEGLASSEN',
     EDATE: 'EDATUM',
     EFFECT: "EFFEKTIV",
     EOMONTH: 'MONATSENDE',
@@ -225,6 +226,7 @@ const dictionary: RawTranslationPackage = {
     SWITCH: '',
     SYD: 'DIA',
     T: 'T',
+    TAKE: 'ÜBERNEHMEN',
     TAN: 'TAN',
     TANH: 'TANHYP',
     TBILLEQ: 'TBILLÄQUIV',
@@ -234,7 +236,9 @@ const dictionary: RawTranslationPackage = {
     TEXTJOIN: 'TEXTVERKETTEN',
     TIME: 'ZEIT',
     TIMEVALUE: 'ZEITWERT',
+    TOCOL: 'ZUSPALTE',
     TODAY: 'HEUTE',
+    TOROW: 'ZUZEILE',
     TRANSPOSE: 'MTRANS',
     TRIM: 'GLÄTTEN',
     TRUE: 'WAHR',

src/i18n/languages/enGB.ts

@@ -99,6 +99,7 @@ const dictionary: RawTranslationPackage = {
     DELTA: 'DELTA',
     DOLLARDE: 'DOLLARDE',
     DOLLARFR: 'DOLLARFR',
+    DROP: 'DROP',
     EDATE: 'EDATE',
     EFFECT: 'EFFECT',
     EOMONTH: 'EOMONTH',
@@ -227,6 +228,7 @@ const dictionary: RawTranslationPackage = {
     SWITCH: 'SWITCH',
     SYD: 'SYD',
     T: 'T',
+    TAKE: 'TAKE',
     TAN: 'TAN',
     TANH: 'TANH',
     TBILLEQ: 'TBILLEQ',
@@ -236,7 +238,9 @@ const dictionary: RawTranslationPackage = {
     TEXTJOIN: 'TEXTJOIN',
     TIME: 'TIME',
     TIMEVALUE: 'TIMEVALUE',
+    TOCOL: 'TOCOL',
     TODAY: 'TODAY',
+    TOROW: 'TOROW',
     TRANSPOSE: 'TRANSPOSE',
     TRIM: 'TRIM',
     TRUE: 'TRUE',

src/i18n/languages/esES.ts

@@ -98,6 +98,7 @@ export const dictionary: RawTranslationPackage = {
     DELTA: 'DELTA',
     DOLLARDE: 'MONEDA.DEC',
     DOLLARFR: 'MONEDA.FRAC',
+    DROP: 'EXCLUIR',
     EDATE: 'FECHA.MES',
     EFFECT: "INT.EFECTIVO",
     EOMONTH: 'FIN.MES',
@@ -225,6 +226,7 @@ export const dictionary: RawTranslationPackage = {
     SWITCH: '',
     SYD: 'SYD',
     T: 'T',
+    TAKE: 'TOMAR',
     TAN: 'TAN',
     TANH: 'TANH',
     TBILLEQ: 'LETRA.DE.TEST.EQV.A.BONO',
@@ -234,7 +236,9 @@ export const dictionary: RawTranslationPackage = {
     TEXTJOIN: 'UNIRCADENAS',
     TIME: 'NSHORA',
     TIMEVALUE: 'HORANUMERO',
+    TOCOL: 'ENCOL',
     TODAY: 'HOY',
+    TOROW: 'ENFILA',
     TRANSPOSE: 'TRANSPONER',
     TRIM: 'ESPACIOS',
     TRUE: 'VERDADERO',

src/i18n/languages/fiFI.ts

@@ -98,6 +98,7 @@ const dictionary: RawTranslationPackage = {
     DELTA: 'SAMA.ARVO',
     DOLLARDE: 'VALUUTTA.DES',
     DOLLARFR: 'VALUUTTA.MURTO',
+    DROP: 'HYLKÄÄ',
     EDATE: 'PÄIVÄ.KUUKAUSI',
     EFFECT: "KORKO.EFEKT",
     EOMONTH: 'KUUKAUSI.LOPPU',
@@ -225,6 +226,7 @@ const dictionary: RawTranslationPackage = {
     SWITCH: '',
     SYD: 'VUOSIPOISTO',
     T: 'T',
+    TAKE: 'OTA',
     TAN: 'TAN',
     TANH: 'TANH',
     TBILLEQ: 'OBLIG.TUOTTOPROS',
@@ -234,7 +236,9 @@ const dictionary: RawTranslationPackage = {
     TEXTJOIN: 'TEKSTI.YHDISTÄ',
     TIME: 'AIKA',
     TIMEVALUE: 'AIKA_ARVO',
+    TOCOL: 'SARAKKEESEEN',
     TODAY: 'TÄMÄ.PÄIVÄ',
+    TOROW: 'RIVIIN',
     TRANSPOSE: 'TRANSPONOI',
     TRIM: 'POISTA.VÄLIT',
     TRUE: 'TOSI',

src/i18n/languages/frFR.ts

@@ -98,6 +98,7 @@ const dictionary: RawTranslationPackage = {
     DELTA: 'DELTA',
     DOLLARDE: 'PRIX.DEC',
     DOLLARFR: 'PRIX.FRAC',
+    DROP: 'EXCLURE',
     EDATE: 'MOIS.DECALER',
     EFFECT: "TAUX.EFFECTIF",
     EOMONTH: 'FIN.MOIS',
@@ -225,6 +226,7 @@ const dictionary: RawTranslationPackage = {
     SWITCH: '',
     SYD: 'SYD',
     T: 'T',
+    TAKE: 'PRENDRE',
     TAN: 'TAN',
     TANH: 'TANH',
     TBILLEQ: 'TAUX.ESCOMPTE.R',
@@ -234,7 +236,9 @@ const dictionary: RawTranslationPackage = {
     TEXTJOIN: 'JOINDRE.TEXTE',
     TIME: 'TEMPS',
     TIMEVALUE: 'TEMPSVAL',
+    TOCOL: 'DANSCOL',
     TODAY: 'AUJOURDHUI',
+    TOROW: 'DANSLIGNE',
     TRANSPOSE: 'TRANSPOSE',
     TRIM: 'SUPPRESPACE',
     TRUE: 'VRAI',

src/i18n/languages/huHU.ts

@@ -98,6 +98,7 @@ const dictionary: RawTranslationPackage = {
     DELTA: 'DELTA',
     DOLLARDE: 'FORINT.DEC',
     DOLLARFR: 'FORINT.TÖRT',
+    DROP: 'ELTÁVOLÍT',
     EDATE: 'KALK.DÁTUM',
     EFFECT: "TÉNYLEGES",
     EOMONTH: 'HÓNAP.UTOLSÓ.NAP',
@@ -225,6 +226,7 @@ const dictionary: RawTranslationPackage = {
     SWITCH: '',
     SYD: 'ÉSZÖ',
     T: 'T',
+    TAKE: 'ÁTHELYEZ',
     TAN: 'TAN',
     TANH: 'TANH',
     TBILLEQ: 'KJEGY.EGYENÉRT',
@@ -234,7 +236,9 @@ const dictionary: RawTranslationPackage = {
     TEXTJOIN: 'SZÖVEGÖSSZEFŰZÉS',
     TIME: 'IDŐ',
     TIMEVALUE: 'IDŐÉRTÉK',
+    TOCOL: 'OSZLOPHOZ',
     TODAY: 'MA',
+    TOROW: 'SORHOZ',
     TRANSPOSE: 'TRANSZPONÁLÁS',
     TRIM: 'KIMETSZ',
     TRUE: 'IGAZ',