Skip to content

Commit

Permalink
Improve the description of the array of changes (#1343)
Browse files Browse the repository at this point in the history 
* Add more specific unit tests to make sure the return value of addRows() is correct

* Add links to the section about the changes array to the descriptions of basic operations in the doc guide

* Add links to the section about the changes array to the named-expressions guide

* Add references to the description of the array of changes to the API reference of all the methods that return ExportedChange[]
  • Loading branch information
@sequba
sequba authored Dec 19, 2023
1 parent 642506b commit afbdfe5
Show file tree
Hide file tree
Showing 4 changed files with 163 additions and 62 deletions.
100 changes: 59 additions & 41 deletions docs/guide/basic-operations.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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

Expand Down
19 changes: 7 additions & 12 deletions docs/guide/named-expressions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -85,10 +85,8 @@ You can add a named expression by using the `addNamedExpression` method. It
accepts name for the expression, the expression as a raw cell content, and
optionally the scope. If you do not define the scope it will be set to global,
meaning the expression name will be valid for the whole workbook. If you want to
add many of them, it is advised to do so in a [batch](batch-operations.md). This
method returns a list of cells whose values were affected by this operation,
their absolute addresses, and new values. See the "changes" section in
[basic operations](basic-operations) for more info.
add many of them, it is advised to do so in a [batch](batch-operations.md).
This method returns [an array of changed cells](basic-operations.md#changes-array).

```javascript
// add 'prettyName' expression to the local scope of 'Sheet1' (sheetId = 0)
Expand All @@ -106,10 +104,8 @@ Select the name of an expression to change and pass it as the first parameter,
then define the new expression as raw cell content and optionally add the scope.
If you do not define the scope it will be set to global, meaning the expression
will be valid for the whole workbook. If you want to change many of them, it is
advised to do so in a [batch](batch-operations.md). This method returns a list
of cells whose values were affected by this operation, their absolute addresses,
and new values. See the "changes" section in
[basic operations](basic-operations) for more info.
advised to do so in a [batch](batch-operations.md).
This method returns [an array of changed cells](basic-operations.md#changes-array).

```javascript
// change the named expression
Expand All @@ -124,9 +120,8 @@ const changes = hfInstance.changeNamedExpression(
You can remove a named expression by using the `removeNamedExpression` method.
Select the name of an expression to remove and pass it as the first parameter
and optionally define the scope. If you do not define the scope it will be
understood as global, meaning, the whole workbook. This method returns a list of
[cells whose values were affected by this operation](basic-operations.md#what-are-the-changes),
their absolute addresses, and new values.
understood as global, meaning, the whole workbook.
This method returns [an array of changed cells](basic-operations.md#changes-array).

```javascript
// remove 'prettyName' expression from 'Sheet1' (sheetId=0)
Expand All @@ -150,7 +145,7 @@ Operations on named expressions throw errors when something goes wrong. These
errors can be [handled](basic-operations.md#handling-an-error) to provide a good
user experience in the application. It is also possible to check the
availability of operations using `isItPossibleTo*` methods, which are also
described in [that section](basic-operations#isitpossibleto-methods).
described in [that section](basic-operations.md#isitpossibleto-methods).

## Demo

Expand Down
Loading

0 comments on commit afbdfe5

Please sign in to comment.