docs: clarify setRowOrder/setColumnOrder permutation semantics

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

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

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,65 +74,67 @@ 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',
 // }]
 ```
 
 ## Sorting columns
 
 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',
 // }]
 ```
 

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]);
    * ```
    *