Merge branch 'release/2.6.1'

Author: sequba

CHANGELOG.md

@@ -7,6 +7,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+## [2.6.1] - 2023-12-27
+
+### Fixed
+
+- Fixed an issue where operating on ranges of incompatible sizes resulted in a runtime exception. [#1267](https://github.com/handsontable/hyperformula/issues/1267)
+- Fixed an issue where the `simpleCellAddressFromString()` method was crashing when called with a non-ASCII character in an unquoted sheet name. [#1312](https://github.com/handsontable/hyperformula/issues/1312)
+- Fixed an issue where adding a row to a very large spreadsheet resulted in the `Maximum call stack size exceeded` error. [#1332](https://github.com/handsontable/hyperformula/issues/1332)
+- Fixed an issue where using a column-range reference to an empty sheet as a function argument resulted in the `Incorrect array size` error. [#1147](https://github.com/handsontable/hyperformula/issues/1147)
+- Fixed an issue where the SUBSTITUTE function wasn't working correctly with regex special characters. [#1289](https://github.com/handsontable/hyperformula/issues/1289)
+- Fixed a typo in the JSDoc comment of the `HyperFormula` class. [#1323](https://github.com/handsontable/hyperformula/issues/1323)
+
 ## [2.6.0] - 2023-09-19
 
 ### Added
@@ -277,7 +288,7 @@ For more information on this release, see:
 - **Breaking change**: Changed config options [#747](https://github.com/handsontable/hyperformula/issues/747):
 
 | before                | after                |
-| --------------------- | -------------------- |
+|-----------------------|----------------------|
 | matrixColumnSeparator | arrayColumnSeparator |
 | matrixRowSeparator    | arrayRowSeparator    |
 
@@ -286,14 +297,14 @@ For more information on this release, see:
 - **Breaking change**: Changed API methods [#747](https://github.com/handsontable/hyperformula/issues/747):
 
 | before             | after             |
-| ------------------ | ----------------- |
+|--------------------|-------------------|
 | matrixMapping      | arrrayMapping     |
 | isCellPartOfMatrix | isCellPartOfArray |
 
 - **Breaking change**: Changed Exceptions [#747](https://github.com/handsontable/hyperformula/issues/747):
 
 | before                       | after                       |
-| ---------------------------- | --------------------------- |
+|------------------------------|-----------------------------|
 | SourceLocationHasMatrixError | SourceLocationHasArrayError |
 | TargetLocationHasMatrixError | TargetLocationHasArrayError |
 

docs/.vuepress/config.js

@@ -132,13 +132,6 @@ module.exports = {
           alias: '/api/events',
           collapsable: true,
         },
-        {
-          title: 'Error Types',
-          collapsable: true,
-          children: fs.readdirSync(path.join(__dirname, '../api/classes'))
-            .filter((n) => n.match(/.*error\.md$/))
-            .map(f => `/api/classes/${f}`)
-        },
       ],
       '/': [
         {
@@ -178,6 +171,7 @@ module.exports = {
             ['/guide/integration-with-react', 'Integration with React'],
             ['/guide/integration-with-vue', 'Integration with Vue'],
             ['/guide/integration-with-angular', 'Integration with Angular'],
+            ['/guide/integration-with-svelte', 'Integration with Svelte'],
           ]
         },
         {

docs/api-template.md

@@ -51,29 +51,3 @@ hfInstance.on('sheetAdded', handler);
 
 const nameProvided = hfInstance.addSheet('MySheet3');
 ```
-
-#### Error Types
-This page is a list of errors thrown by the HyperFormula instance that may be thrown depending on the method used.
-
-An example of how you can handle an error: adding a sheet which name is already taken:
-```javascript
-// variable used to carry the message for the user
-let messageUsedInUI;
-
-// attempt to add a sheet
-try {
-  hfInstance.addSheet('MySheet1');
-
-// whoops! there is already a sheet named 'MySheet1'
-} catch (e) {
-
-  // notify the user that a sheet with an ID of 5 does not exist
-  if (e instanceof SheetNameAlreadyTakenError) {
-     messageUsedInUI = 'Sheet name already taken';
-  }
-  // a generic error message, just in case
-  else {
-     messageUsedInUI = 'Something went wrong';
-  }
-}
-```

docs/guide/advanced-usage.md

@@ -122,9 +122,9 @@ console.log(winningTeam)
 ## Demo
 
 <iframe
-     src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.6.x/advanced-usage?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
-     style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
-     title="handsontable/hyperformula-demos: advanced-usage"
-     allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
-     sandbox="allow-autoplay allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
-   ></iframe>
+  src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.6.x/advanced-usage?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
+  style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
+  title="handsontable/hyperformula-demos: advanced-usage"
+  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
+  sandbox="allow-autoplay allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts">
+</iframe>

docs/guide/arrays.md

@@ -5,10 +5,10 @@ Use array formulas to perform an operation (or call a function) on multiple cell
 ## About arrays
 
 In HyperFormula, an array can be:
-* A range of cell addresses (e.g. `A1:A10`)
-* A result of an arithmetic operation (e.g. `5*A1:B5`)
-* A result of a function (e.g. `=ARRAYFORMULA(ARRAY_CONSTRAIN(A2:E5, 2, 2))`)
-* An **inline array**: an ad-hoc array that doesn't refer to any range of cells (e.g. `{1, 3, 5}`)
+* A range of cell addresses (e.g., `A1:A10`)
+* A result of an arithmetic operation (e.g., `5*A1:B5`)
+* A result of a function (e.g., `=ARRAYFORMULA(ARRAY_CONSTRAIN(A2:E5, 2, 2))`)
+* An **inline array**: an ad-hoc array that doesn't reference any range of cells (e.g., `{1, 3, 5}`)
 
 An array is inherently a two-dimensional object.
 
@@ -150,7 +150,7 @@ 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](#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).
+* 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.

docs/guide/basic-operations.md

@@ -49,8 +49,8 @@ const sheetsCount = hfInstance.countSheets();
 
 A sheet can be removed by using the `removeSheet` method. To do that
 you need to pass a mandatory parameter: the ID of a sheet to be
-removed. This method returns a list of cells whose values were affected
-by this operation together with their absolute addresses and new values.
+removed.
+This method returns [an array of changed cells](#changes-array).
 
 ```javascript
 // track the changes triggered by removing the sheet 0
@@ -78,9 +78,8 @@ hfInstance.renameSheet(sheetID, 'AnotherNewName');
 ### Clearing a sheet
 
 A sheet's content can be cleared with the `clearSheet` method. You need
-to provide the ID of a sheet whose content you want to clear. This
-method returns a list of cells whose values were affected by this
-operation together with their absolute addresses and new values.
+to provide the ID of a sheet whose content you want to clear.
+This method returns [an array of changed cells](#changes-array).
 
 ```javascript
 // clear the content of sheet 0
@@ -91,9 +90,8 @@ const changes = hfInstance.clearSheet(0);
 
 Instead of removing and adding the content of a sheet you can replace
 it right away. To do so use `setSheetContent`, in which you can pass
-the sheet ID and its new values. This method returns a list of cells
-whose values were affected by this operation together with their
-absolute addresses and new values.
+the sheet ID and its new values.
+This method returns [an array of changed cells](#changes-array).
 
 ```javascript
 // set new values for sheet 0
@@ -107,8 +105,7 @@ const changes = hfInstance.setSheetContent(0, [['50'], ['60']]);
 You can add one or more rows by using the `addRows` method. The first
 parameter you need to pass is a sheet ID, and the second parameter
 represents the position and the size of a block of rows to be added.
-This method returns a list of cells whose values were affected by this
-operation together with their absolute addresses and new values.
+This method returns [an array of changed cells](#changes-array).
 
 ```javascript
 // track the changes triggered by adding
@@ -121,9 +118,8 @@ const changes = hfInstance.addRows(0, [0, 2]);
 You can remove one or more rows by using the `removeRows` method. The
 first parameter you need to pass is a sheet ID, and the second
 parameter represents the position and the size of a block of rows to
-be removed. This method returns a list of cells whose values were
-affected by this operation together with their absolute addresses
-and new values.
+be removed.
+This method returns [an array of changed cells](#changes-array).
 
 ```javascript
 // track the changes triggered by removing
@@ -141,8 +137,7 @@ to pass the following parameters:
 * Number of rows to be moved
 * Target row
 
-This method returns a list of cells whose values were affected by
-this operation, together with their absolute addresses and new values.
+This method returns [an array of changed cells](#changes-array).
 
 ```javascript
 // track the changes triggered by moving
@@ -156,8 +151,7 @@ You can change the order of rows by using the `setRowOrder` method. You need to
 * Sheet ID
 * New row order
 
-This method returns a list of cells whose values were affected by
-this operation, together with their absolute addresses and new values.
+This method returns [an array of changed cells](#changes-array).
 
 ```javascript
 // row 0 and row 2 swap places
@@ -171,9 +165,8 @@ const changes = hfInstance.setRowOrder(0, [2, 1, 0]);
 You can add one or more columns by using the `addColumns` method.
 The first parameter you need to pass is a sheet ID, and the second
 parameter represents the position and the size of a block of columns
-to be added. This method returns a list of cells whose values were
-affected by this operation together with their absolute addresses
-and new values.
+to be added.
+This method returns [an array of changed cells](#changes-array).
 
 ```javascript
 // track the changes triggered by adding
@@ -186,9 +179,8 @@ const changes = hfInstance.addColumns(0, [0, 2]);
 You can remove one or more columns by using the `removeColumns` method.
 The first parameter you need to pass is a sheet ID, and the second
 parameter represents the position and the size of a block of columns
-to be removed. This method returns a list of cells which values were
-affected by this operation together with their absolute addresses
-and new values.
+to be removed.
+This method returns [an array of changed cells](#changes-array).
 
 ```javascript
 // track the changes triggered by removing
@@ -206,8 +198,7 @@ You need to pass the following parameters:
 * Number of columns to be moved
 * Target column
 
-This method returns a list of cells whose values were affected by
-this operation together with their absolute addresses and new values.
+This method returns [an array of changed cells](#changes-array).
 
 ```javascript
 // track the changes triggered by moving
@@ -221,8 +212,7 @@ You can change the order of columns by using the `setColumnOrder` method. You ne
 * Sheet ID
 * New column order
 
-This method returns a list of cells whose values were affected by
-this operation, together with their absolute addresses and new values.
+This method returns [an array of changed cells](#changes-array).
 
 ```javascript
 // column 0 and column 2 swap places
@@ -250,8 +240,7 @@ to pass the following parameters:
 * Source range ([SimpleCellRange](../api/interfaces/simplecellrange))
 * Top left corner of the destination range ([SimpleCellAddress](../api/interfaces/simplecelladdress))
 
-This method returns a list of cells whose values were affected by
-this operation together with their absolute addresses and new values.
+This method returns [an array of changed cells](#changes-array).
 
 ```javascript
 // choose the source cells
@@ -270,8 +259,7 @@ You can set the content of a block of cells by using the
 `setCellContents` method. You need to pass the top left corner address
 of a block as a simple cell address, along with the content to be set.
 It can be content for either a single cell or a set of cells in an array.
-This method returns a list of cells whose values were affected by this
-operation together with their absolute addresses and new values.
+This method returns [an array of changed cells](#changes-array).
 
 ```javascript
 // track the changes triggered by setting
@@ -365,23 +353,53 @@ if (!isRemovable) {
 }
 ```
 
-## What are the "changes"?
+## Changes array
 
-Several methods return the "changes". This is a list of cells
-whose values were affected by an operation, together with their
-absolute addresses and new values.
+All data modification methods return an array of `ExportedChange`.
+This is a collection of cells whose **values** were affected by an operation,
+together with their absolute addresses and new values.
 
 ```javascript
- [{
-   address: { sheet: 0, col: 0, row: 0 },
-   newValue: { error: [CellError], value: '#REF!' },
- }]
+[{
+  address: { sheet: 0, col: 0, row: 0 },
+  newValue: { error: [CellError], value: '#REF!' },
+}]
 ```
 
 This gives you information about where the change happened, what the
 new value of a cell is, and even what type it is - in this case, an
-error. The change shows only those parts where calculations were made;
-it will return an empty array if there were none.
+error.
+
+The array of changes includes only cells that have different **values** after performing the operation. See the example:
+
+```js
+const hf = HyperFormula.buildFromArray([
+  [0],
+  [1],
+  ['=SUM(A1:A2)'],
+  ['=COUNTBLANK(A1:A3)'],
+]);
+
+// insert an empty row between the row 0 and the row 1
+const changes = hf.addRows(0, [1, 1]);
+
+console.log(hf.getSheetSerialized(0));
+// sheet after adding the row:
+// [
+//   [0],
+//   [],
+//   [1],
+//   ['=SUM(A1:A3)'],
+//   ['=COUNTBLANK(A1:A4)'],
+// ]
+
+console.log(changes);
+// changes include only the COUNTBLANK cell:
+// [{
+//   address: { sheet: 0, row: 4, col: 0 },
+//   newValue: 1,
+// }]
+```
 
 ## Demo