Add TRIMRANGE function (HF-391)

CHANGELOG.md

@@ -10,6 +10,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ### Added
 
 - Added a message after `npm i hyperformula` that points AI assistants to the SKILLS file. The message needs `--foreground-scripts` to be visible in npm, and pnpm 10 needs the `postinstall` script to be approved first. [#1829](https://github.com/handsontable/hyperformula/pull/1829)
+- 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 `TRIMRANGE` dynamic-array function. [#1842](https://github.com/handsontable/hyperformula/pull/1842)
 
 ### Fixed
 

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**                                                                                      |
@@ -117,6 +119,18 @@ 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 |
+| TRIMRANGE     | =TRIMRANGE(A1:C10)                                             | Reserves the whole range (10x3): the trimmed values fill its top-left corner, the other cells stay blank, and a value in one of them makes the formula return SPILL. | No such function. | Spills only the trimmed rows and columns, and follows the data. |
+| TRIMRANGE     | =TRIMRANGE(Data!A:A)                                           | Spills to the source sheet's current height from row 1; returns SPILL below row 1. | No such function. | Spills the trimmed rows from any row. |
+| TRIMRANGE     | =TRIMRANGE(A1:C3, {0,3})                                       |        VALUE | No such function. | Returns a 1x2 array of VALUE errors. |
+| TRIMRANGE     | =ISREF(TRIMRANGE(A1:C3))                                       | FALSE (returns values, not a reference) | No such function. | TRUE |
+| TRIMRANGE     | =A1:.C10                                                       | ERROR: the trim reference operators (`.:`, `:.`, `.:.`) are not supported. | ERROR: formula parse error. | Same as =TRIMRANGE(A1:C10, 2, 2). |
 | INT           | =INT(-8.9)                                                     |           -8 |            -9 |              -9 |
 | ISEVEN        | =ISEVEN(2.5)                                                   |        FALSE |          TRUE |            TRUE |
 | ISODD         | =ISODD(3.5)                                                    |        FALSE |          TRUE |            TRUE |

hyperformula/src/error-message.ts

@@ -68,6 +68,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.'

hyperformula/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',
@@ -237,6 +239,7 @@ const dictionary: RawTranslationPackage = {
     TODAY: 'DNES',
     TRANSPOSE: 'TRANSPOZICE',
     TRIM: 'PROČISTIT',
+    TRIMRANGE: 'OŘÍZNOUTOBLAST',
     TRUE: 'PRAVDA',
     TRUNC: 'USEKNOUT',
     UNICHAR: 'UNICHAR',

hyperformula/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',
@@ -237,6 +239,7 @@ const dictionary: RawTranslationPackage = {
     TODAY: 'IDAG',
     TRANSPOSE: 'TRANSPONER',
     TRIM: 'FJERN.OVERFLØDIGE.BLANKE',
+    TRIMRANGE: 'TRIMOMRÅDE',
     TRUE: 'TRUE',
     TRUNC: 'AFKORT',
     UNICHAR: 'UNICHAR',

hyperformula/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',
@@ -237,6 +239,7 @@ const dictionary: RawTranslationPackage = {
     TODAY: 'HEUTE',
     TRANSPOSE: 'MTRANS',
     TRIM: 'GLÄTTEN',
+    TRIMRANGE: 'ABSCHNBEREICH',
     TRUE: 'WAHR',
     TRUNC: 'KÜRZEN',
     UNICHAR: 'UNIZEICHEN',

hyperformula/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',
@@ -239,6 +241,7 @@ const dictionary: RawTranslationPackage = {
     TODAY: 'TODAY',
     TRANSPOSE: 'TRANSPOSE',
     TRIM: 'TRIM',
+    TRIMRANGE: 'TRIMRANGE',
     TRUE: 'TRUE',
     TRUNC: 'TRUNC',
     UNICHAR: 'UNICHAR',

hyperformula/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',
@@ -237,6 +239,7 @@ export const dictionary: RawTranslationPackage = {
     TODAY: 'HOY',
     TRANSPOSE: 'TRANSPONER',
     TRIM: 'ESPACIOS',
+    TRIMRANGE: 'RECORTAR.RANGO',
     TRUE: 'VERDADERO',
     TRUNC: 'TRUNCAR',
     UNICHAR: 'UNICHAR',

hyperformula/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',
@@ -237,6 +239,7 @@ const dictionary: RawTranslationPackage = {
     TODAY: 'TÄMÄ.PÄIVÄ',
     TRANSPOSE: 'TRANSPONOI',
     TRIM: 'POISTA.VÄLIT',
+    TRIMRANGE: 'RAJAAALUE',
     TRUE: 'TOSI',
     TRUNC: 'KATKAISE',
     UNICHAR: 'UNICODEMERKKI',

hyperformula/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',
@@ -237,6 +239,7 @@ const dictionary: RawTranslationPackage = {
     TODAY: 'AUJOURDHUI',
     TRANSPOSE: 'TRANSPOSE',
     TRIM: 'SUPPRESPACE',
+    TRIMRANGE: 'SUPPR.PLAGE',
     TRUE: 'VRAI',
     TRUNC: 'TRONQUE',
     UNICHAR: 'UNICAR',

hyperformula/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',
@@ -237,6 +239,7 @@ const dictionary: RawTranslationPackage = {
     TODAY: 'MA',
     TRANSPOSE: 'TRANSZPONÁLÁS',
     TRIM: 'KIMETSZ',
+    TRIMRANGE: 'KIMETSZÉSITARTOMÁNY',
     TRUE: 'IGAZ',
     TRUNC: 'CSONK',
     UNICHAR: 'UNIKARAKTER',

hyperformula/src/i18n/languages/idID.ts

@@ -99,6 +99,7 @@ const dictionary: RawTranslationPackage = {
     DELTA: 'DELTA',
     DOLLARDE: 'DOLAR.DES',
     DOLLARFR: 'DOLAR.PEC',
+    DROP: 'DROP',
     EDATE: 'EDATE',
     EFFECT: 'EFEKTIF',
     EOMONTH: 'AKHIR.BULAN',
@@ -227,6 +228,7 @@ const dictionary: RawTranslationPackage = {
     SWITCH: 'BERALIH',
     SYD: 'SYD',
     T: 'T',
+    TAKE: 'TAKE',
     TAN: 'TAN',
     TANH: 'TANH',
     TBILLEQ: 'TBILL.SAMA',
@@ -239,6 +241,7 @@ const dictionary: RawTranslationPackage = {
     TODAY: 'HARI.INI',
     TRANSPOSE: 'TRANSPOS',
     TRIM: 'HAPUS.SPASI',
+    TRIMRANGE: 'TRIMRANGE',
     TRUE: 'BENAR',
     TRUNC: 'POTONG',
     UNICHAR: 'UNIKARAKTER',

hyperformula/src/i18n/languages/itIT.ts

@@ -98,6 +98,7 @@ const dictionary: RawTranslationPackage = {
     DELTA: 'DELTA',
     DOLLARDE: 'VALUTA.DEC',
     DOLLARFR: 'VALUTA.FRAZ',
+    DROP: 'ESCLUDI',
     EDATE: 'DATA.MESE',
     EFFECT: "EFFETTIVO",
     EOMONTH: 'FINE.MESE',
@@ -225,6 +226,7 @@ const dictionary: RawTranslationPackage = {
     SWITCH: '',
     SYD: 'AMMORT.ANNUO',
     T: 'T',
+    TAKE: 'INCLUDI',
     TAN: 'TAN',
     TANH: 'TANH',
     TBILLEQ: 'BOT.EQUIV',
@@ -237,6 +239,7 @@ const dictionary: RawTranslationPackage = {
     TODAY: 'OGGI',
     TRANSPOSE: 'MATR.TRASPOSTA',
     TRIM: 'ANNULLA.SPAZI',
+    TRIMRANGE: 'ESCLUDI.VUOTE',
     TRUE: 'VERO',
     TRUNC: 'TRONCA',
     UNICHAR: 'CARATT.UNI',

hyperformula/src/i18n/languages/nbNO.ts

@@ -98,6 +98,7 @@ const dictionary: RawTranslationPackage = {
     DELTA: 'DELTA',
     DOLLARDE: 'DOLLARDE',
     DOLLARFR: 'DOLLARBR',
+    DROP: 'UTELAT',
     EDATE: 'DAG.ETTER',
     EFFECT: "EFFEKTIV.RENTE",
     EOMONTH: 'MÅNEDSSLUTT',
@@ -225,6 +226,7 @@ const dictionary: RawTranslationPackage = {
     SWITCH: '',
     SYD: 'ÅRSAVS',
     T: 'T',
+    TAKE: 'TA',
     TAN: 'TAN',
     TANH: 'TANH',
     TBILLEQ: 'TBILLEKV',
@@ -237,6 +239,7 @@ const dictionary: RawTranslationPackage = {
     TODAY: 'IDAG',
     TRANSPOSE: 'TRANSPONER',
     TRIM: 'TRIMME',
+    TRIMRANGE: 'TRIMMEOMRÅDE',
     TRUE: 'SANN',
     TRUNC: 'AVKORT',
     UNICHAR: 'UNICODETEGN',

hyperformula/src/i18n/languages/nlNL.ts

@@ -98,6 +98,7 @@ const dictionary: RawTranslationPackage = {
     DELTA: 'DELTA',
     DOLLARDE: 'EURO.DE',
     DOLLARFR: 'EURO.BR',
+    DROP: 'WEGLATEN',
     EDATE: 'ZELFDE.DAG',
     EFFECT: "EFFECT.RENTE",
     EOMONTH: 'LAATSTE.DAG',
@@ -225,6 +226,7 @@ const dictionary: RawTranslationPackage = {
     SWITCH: '',
     SYD: 'SYD',
     T: 'T',
+    TAKE: 'NEMEN',
     TAN: 'TAN',
     TANH: 'TANH',
     TBILLEQ: 'SCHATK.OBL',
@@ -237,6 +239,7 @@ const dictionary: RawTranslationPackage = {
     TODAY: 'VANDAAG',
     TRANSPOSE: 'TRANSPONEREN',
     TRIM: 'SPATIES.WISSEN',
+    TRIMRANGE: 'TRIMBEREIK',
     TRUE: 'WAAR',
     TRUNC: 'GEHEEL',
     UNICHAR: 'UNITEKEN',

hyperformula/src/i18n/languages/plPL.ts

@@ -98,6 +98,7 @@ const dictionary: RawTranslationPackage = {
     DELTA: 'DELTA',
     DOLLARDE: 'CENA.DZIES',
     DOLLARFR: 'CENA.UŁAM',
+    DROP: 'POMIŃ',
     EDATE: 'NR.SER.DATY',
     EFFECT: "EFEKTYWNA",
     EOMONTH: 'NR.SER.OST.DN.MIEŚ',
@@ -225,6 +226,7 @@ const dictionary: RawTranslationPackage = {
     SWITCH: 'PRZEŁĄCZ',
     SYD: 'SYD',
     T: 'T',
+    TAKE: 'WYCINEK',
     TAN: 'TAN',
     TANH: 'TANH',
     TBILLEQ: 'RENT.EKW.BS',
@@ -237,6 +239,7 @@ const dictionary: RawTranslationPackage = {
     TODAY: 'DZIŚ',
     TRANSPOSE: 'TRANSPONUJ',
     TRIM: 'USUŃ.ZBĘDNE.ODSTĘPY',
+    TRIMRANGE: 'PRZYTNIJZAKRES',
     TRUE: 'PRAWDA',
     TRUNC: 'LICZBA.CAŁK',
     UNICHAR: 'ZNAK.UNICODE',