diff --git a/DEV_DOCS.md b/DEV_DOCS.md index 24461cf36..9e97545de 100644 --- a/DEV_DOCS.md +++ b/DEV_DOCS.md @@ -90,7 +90,7 @@ Each change to the production code (bugfix, new feature, or improvement) must in - Updates to documentation related to the change - for breaking changes: a section in the migration guide - Technical documentation in the form of JSDoc comments (high-level description of the concepts used in more complex code fragments) -- Changelog entry +- Changelog entry (not required for documentation-only changes (guides, JSDoc, README, etc.) - Pull request description ## Internationalization and function translations diff --git a/docs/guide/basic-operations.md b/docs/guide/basic-operations.md index 20a4b1edc..f6c25fd7c 100644 --- a/docs/guide/basic-operations.md +++ b/docs/guide/basic-operations.md @@ -151,11 +151,13 @@ You can change the order of rows by using the [`setRowOrder`](../api/classes/hyp * Sheet ID * [New row order](../api/classes/hyperformula.md#setroworder) +The new row order is a permutation of the form `[ newPositionForRow0, newPositionForRow1, newPositionForRow2, ... ]`. The value at index `i` is the new position for the row that is currently at index `i`. See the [Sorting data](sorting-data.md) guide for details. + This method returns [an array of changed cells](#changes-array). ```javascript -// row 0 and row 2 swap places -const changes = hfInstance.setRowOrder(0, [2, 1, 0]); +// move row 0 to position 1, row 1 to position 2, and row 2 to position 0 +const changes = hfInstance.setRowOrder(0, [1, 2, 0]); ``` ## Columns @@ -212,11 +214,13 @@ You can change the order of columns by using the [`setColumnOrder`](../api/class * Sheet ID * [New column order](../api/classes/hyperformula.md#setcolumnorder) +The new column order is a permutation of the form `[ newPositionForColumn0, newPositionForColumn1, newPositionForColumn2, ... ]`. The value at index `i` is the new position for the column that is currently at index `i`. See the [Sorting data](sorting-data.md) guide for details. + This method returns [an array of changed cells](#changes-array). ```javascript -// column 0 and column 2 swap places -const changes = hfInstance.setColumnOrder(0, [2, 1, 0]); +// move column 0 to position 1, column 1 to position 2, and column 2 to position 0 +const changes = hfInstance.setColumnOrder(0, [1, 2, 0]); ``` ## Cells diff --git a/docs/guide/sorting-data.md b/docs/guide/sorting-data.md index 8faedd3ca..e9920cd41 100644 --- a/docs/guide/sorting-data.md +++ b/docs/guide/sorting-data.md @@ -6,32 +6,41 @@ In HyperFormula, you can sort data by reordering rows and columns. To sort data in HyperFormula, you reorder rows (or columns), by providing your preferred permutation of row (or column) indexes. -You can implement any sorting algorithm that returns an array of row or column indexes. +The permutation array has the form `[ newPositionForRow0, newPositionForRow1, newPositionForRow2, ... ]`. The value at index `i` is the new position for the row that is currently at index `i`. + +You can implement any sorting algorithm that returns such an array of row or column indexes. ## Sorting rows To sort rows, use the [`isItPossibleToSetRowOrder`](../api/classes/hyperformula.md#isitpossibletosetroworder) and [`setRowOrder`](../api/classes/hyperformula.md#setroworder) methods. ### Step 1: Choose a new row order -Choose your required permutation of row indexes. +Choose your required permutation of row indexes. -For example, if you want to swap the first row with the third row, set the order to `[2, 1, 0]` instead of `[0, 1, 2]`: +For example, if you want to move the bottom row to the top of a 3-row sheet, set the order to `[1, 2, 0]` instead of `[0, 1, 2]`. This moves the row at index 0 to position 1, the row at index 1 to position 2, and the row at index 2 to position 0: ```js // a HyperFormula instance with example data const hfInstance = HyperFormula.buildFromArray([ - [1], - [2], - [4, 5], + ['A'], + ['B'], + ['C'], ]); -// we'll set the row order to [2, 1, 0] in the next steps +// we'll set the row order to [1, 2, 0] in the next steps +// the resulting sheet will be: [['C'], ['A'], ['B']] ``` ::: tip The [`setRowOrder`](../api/classes/hyperformula.md#setroworder) method accepts an array of numbers, so you can implement any function that returns an array with your required row order. ::: +::: warning +The permutation array maps **current positions** to **new positions**, not the other way around. The value at index `i` tells HyperFormula where to move the row currently at index `i`, *not* which row should end up at index `i`. + +For example, `[1, 2, 0]` means "move row 0 to position 1, row 1 to position 2, row 2 to position 0". It does **not** mean "the new row 0 comes from position 1, the new row 1 comes from position 2, ...". +::: + ### Step 2: Check if the new row order can be applied Before you change the row order, check if your specified row number permutation can actually be applied. @@ -42,16 +51,16 @@ Use the [`isItPossibleToSetRowOrder`](../api/classes/hyperformula.md#isitpossibl ```js const hfInstance = HyperFormula.buildFromArray([ - [1], - [2], - [4, 5], + ['A'], + ['B'], + ['C'], ]); // a variable to carry the user message let messageUsedInUI; // check if your permutation can be applied -const isRowOrderOk = hfInstance.isItPossibleToSetRowOrder(0, [2, 1, 0]); +const isRowOrderOk = hfInstance.isItPossibleToSetRowOrder(0, [1, 2, 0]); // display an error message if (!isRowOrderOk) { @@ -65,39 +74,35 @@ If your specified row number permutation is valid, change the row order: ```js const hfInstance = HyperFormula.buildFromArray([ - [1], - [2], - [4, 5], + ['A'], + ['B'], + ['C'], ]); let messageUsedInUI; -const isRowOrderOk = hfInstance.isItPossibleToSetRowOrder(0, [2, 1, 0]); +const isRowOrderOk = hfInstance.isItPossibleToSetRowOrder(0, [1, 2, 0]); if (!isRowOrderOk) { messageUsedInUI = 'Sorry, you cannot sort rows in this way.' } else { // set the new row order - setRowOrder(0, [2, 1, 0]); + hfInstance.setRowOrder(0, [1, 2, 0]); } -// rows 0 and 2 swap places +// the resulting sheet is: [['C'], ['A'], ['B']] -// returns: +// the method returns an array of cells whose values changed: // [{ -// address: { sheet: 0, col: 0, row: 2 }, -// newValue: 1, +// address: { sheet: 0, col: 0, row: 1 }, +// newValue: 'A', // }, // { -// address: { sheet: 0, col: 1, row: 2 }, -// newValue: null, +// address: { sheet: 0, col: 0, row: 2 }, +// newValue: 'B', // }, // { // address: { sheet: 0, col: 0, row: 0 }, -// newValue: 4, -// }, -// { -// address: { sheet: 0, col: 1, row: 0 }, -// newValue: 5, +// newValue: 'C', // }] ``` @@ -105,25 +110,31 @@ if (!isRowOrderOk) { To sort columns, use the [`isItPossibleToSetColumnOrder`](../api/classes/hyperformula.md#isitpossibletosetcolumnorder) and [`setColumnOrder`](../api/classes/hyperformula.md#setcolumnorder) methods. +The permutation array has the same shape as for rows: `[ newPositionForColumn0, newPositionForColumn1, newPositionForColumn2, ... ]`. The value at index `i` is the new position for the column that is currently at index `i`. + ### Step 1: Choose a new column order Choose your required permutation of column indexes. -For example, if you want to swap the first column with the third column, set the order to `[2, 1, 0]` instead of `[0, 1, 2]`: +For example, if you want to move the last column to the front of a 3-column sheet, set the order to `[1, 2, 0]` instead of `[0, 1, 2]`. This moves the column at index 0 to position 1, the column at index 1 to position 2, and the column at index 2 to position 0: ```js // a HyperFormula instance with example data const hfInstance = HyperFormula.buildFromArray([ - [1, 2, 4], - [5] + ['A', 'B', 'C'] ]); -// we'll set the column order to [2, 1, 0] in the next steps +// we'll set the column order to [1, 2, 0] in the next steps +// the resulting sheet will be: [['C', 'A', 'B']] ``` ::: tip The [`setColumnOrder`](../api/classes/hyperformula.md#setcolumnorder) method accepts an array of numbers, so you can implement any function that returns an array with your required column order. ::: +::: warning +The permutation array maps **current positions** to **new positions**, not the other way around. The value at index `i` tells HyperFormula where to move the column currently at index `i`, *not* which column should end up at index `i`. +::: + ### Step 2: Check if the new column order can be applied Before you change the column order, check if your specified column number permutation can actually be applied. @@ -134,15 +145,14 @@ Use the [`isItPossibleToSetColumnOrder`](../api/classes/hyperformula.md#isitposs ```js const hfInstance = HyperFormula.buildFromArray([ - [1, 2, 4], - [5] + ['A', 'B', 'C'] ]); // a variable to carry the user message let messageUsedInUI; // check if your permutation can be applied -const isColumnOrderOk = hfInstance.isItPossibleToSetColumnOrder(0, [2, 1, 0]); +const isColumnOrderOk = hfInstance.isItPossibleToSetColumnOrder(0, [1, 2, 0]); // display an error message if (!isColumnOrderOk) { @@ -156,38 +166,33 @@ If your specified column number permutation is valid, change the column order: ```js const hfInstance = HyperFormula.buildFromArray([ - [1, 2, 4], - [5] + ['A', 'B', 'C'] ]); let messageUsedInUI; -const isColumnOrderOk = hfInstance.isItPossibleToSetColumnOrder(0, [2, 1, 0]); +const isColumnOrderOk = hfInstance.isItPossibleToSetColumnOrder(0, [1, 2, 0]); if (!isColumnOrderOk) { messageUsedInUI = 'Sorry, you cannot sort columns in this way.' } else { // set the new column order - setColumnOrder(0, [2, 1, 0]); + hfInstance.setColumnOrder(0, [1, 2, 0]); } -// columns 0 and 2 swap places +// the resulting sheet is: [['C', 'A', 'B']] -//returns: +// the method returns an array of cells whose values changed: // [{ -// address: { sheet: 0, col: 2, row: 0 }, -// newValue: 1, +// address: { sheet: 0, col: 1, row: 0 }, +// newValue: 'A', // }, // { -// address: { sheet: 0, col: 2, row: 1 }, -// newValue: 5, +// address: { sheet: 0, col: 2, row: 0 }, +// newValue: 'B', // }, // { // address: { sheet: 0, col: 0, row: 0 }, -// newValue: 4, -// }, -// { -// address: { sheet: 0, col: 0, row: 1 }, -// newValue: null, +// newValue: 'C', // }] ``` diff --git a/src/HyperFormula.ts b/src/HyperFormula.ts index 566957270..f91f02505 100644 --- a/src/HyperFormula.ts +++ b/src/HyperFormula.ts @@ -1385,7 +1385,11 @@ export class HyperFormula implements TypedEmitter { /** * Reorders rows of a sheet according to a permutation of 0-based indexes. - * Parameter `newRowOrder` should have a form `[ newPositionForRow0, newPositionForRow1, newPositionForRow2, ... ]`. + * + * Parameter `newRowOrder` should have the form `[ newPositionForRow0, newPositionForRow1, newPositionForRow2, ... ]`. + * In other words, the value at index `i` is the new position for the row that is currently at index `i`. + * Note that this is the opposite of `[ previousPositionForRow0, previousPositionForRow1, ... ]`. + * * This method might be used to [sort the rows of a sheet](../../guide/sorting-data.md). * * Returns [an array of cells whose values changed as a result of this operation](/guide/basic-operations.md#changes-array). @@ -1407,15 +1411,15 @@ export class HyperFormula implements TypedEmitter { * const hfInstance = HyperFormula.buildFromArray([ * ['A'], * ['B'], - * ['C'], - * ['D'] + * ['C'] * ]); * - * const newRowOrder = [0, 3, 2, 1]; // [ newPosForA, newPosForB, newPosForC, newPosForD ] + * // Move 'A' to index 1, 'B' to index 2, and 'C' to index 0. + * const newRowOrder = [1, 2, 0]; // [ newPosForA, newPosForB, newPosForC ] * * const changes = hfInstance.setRowOrder(0, newRowOrder); * - * // Sheet after this operation: [['A'], ['D'], ['C'], ['B']] + * // Sheet after this operation: [['C'], ['A'], ['B']] * ``` * * @category Rows @@ -1429,6 +1433,10 @@ export class HyperFormula implements TypedEmitter { /** * Checks if it is possible to reorder rows of a sheet according to a permutation. * + * Parameter `newRowOrder` should have the form `[ newPositionForRow0, newPositionForRow1, newPositionForRow2, ... ]`, + * i.e. the value at index `i` is the new position for the row that is currently at index `i`. + * See [[setRowOrder]] for details. + * * @param {number} sheetId - ID of a sheet to operate on * @param {number[]} newRowOrder - permutation of rows * @@ -1437,15 +1445,15 @@ export class HyperFormula implements TypedEmitter { * @example * ```js * const hfInstance = HyperFormula.buildFromArray([ - * [1], - * [2], - * [4, 5], + * ['A'], + * ['B'], + * ['C'] * ]); * * // returns true - * hfInstance.isItPossibleToSetRowOrder(0, [2, 1, 0]); + * hfInstance.isItPossibleToSetRowOrder(0, [1, 2, 0]); * - * // returns false + * // returns false (array length must match the number of rows) * hfInstance.isItPossibleToSetRowOrder(0, [2]); * ``` * @@ -1550,7 +1558,11 @@ export class HyperFormula implements TypedEmitter { /** * Reorders columns of a sheet according to a permutation of 0-based indexes. - * Parameter `newColumnOrder` should have a form `[ newPositionForColumn0, newPositionForColumn1, newPositionForColumn2, ... ]`. + * + * Parameter `newColumnOrder` should have the form `[ newPositionForColumn0, newPositionForColumn1, newPositionForColumn2, ... ]`. + * In other words, the value at index `i` is the new position for the column that is currently at index `i`. + * Note that this is the opposite of `[ previousPositionForColumn0, previousPositionForColumn1, ... ]`. + * * This method might be used to [sort the columns of a sheet](../../guide/sorting-data.md). * * Returns [an array of cells whose values changed as a result of this operation](/guide/basic-operations.md#changes-array). @@ -1570,14 +1582,15 @@ export class HyperFormula implements TypedEmitter { * @example * ```js * const hfInstance = HyperFormula.buildFromArray([ - * ['A', 'B', 'C', 'D'] + * ['A', 'B', 'C'] * ]); * - * const newColumnOrder = [0, 3, 2, 1]; // [ newPosForA, newPosForB, newPosForC, newPosForD ] + * // Move 'A' to index 1, 'B' to index 2, and 'C' to index 0. + * const newColumnOrder = [1, 2, 0]; // [ newPosForA, newPosForB, newPosForC ] * * const changes = hfInstance.setColumnOrder(0, newColumnOrder); * - * // Sheet after this operation: [['A', 'D', 'C', 'B']] + * // Sheet after this operation: [['C', 'A', 'B']] * ``` * * @category Columns @@ -1591,6 +1604,10 @@ export class HyperFormula implements TypedEmitter { /** * Checks if it is possible to reorder columns of a sheet according to a permutation. * + * Parameter `newColumnOrder` should have the form `[ newPositionForColumn0, newPositionForColumn1, newPositionForColumn2, ... ]`, + * i.e. the value at index `i` is the new position for the column that is currently at index `i`. + * See [[setColumnOrder]] for details. + * * @param {number} sheetId - ID of a sheet to operate on * @param {number[]} newColumnOrder - permutation of columns * @@ -1599,14 +1616,13 @@ export class HyperFormula implements TypedEmitter { * @example * ```js * const hfInstance = HyperFormula.buildFromArray([ - * [1, 2, 4], - * [5] + * ['A', 'B', 'C'] * ]); * * // returns true - * hfInstance.isItPossibleToSetColumnOrder(0, [2, 1, 0]); + * hfInstance.isItPossibleToSetColumnOrder(0, [1, 2, 0]); * - * // returns false + * // returns false (array length must match the number of columns) * hfInstance.isItPossibleToSetColumnOrder(0, [1]); * ``` *