Merge pull request #1443 from Subhajitdas298/master

AddRow/s and InsertRow/s now returning the newly added rows

README.md

@@ -714,6 +714,9 @@ worksheet.spliceColumns(3, 1, newCol3Values, newCol4Values);
 // Get a row object. If it doesn't already exist, a new empty one will be returned
 const row = worksheet.getRow(5);
 
+// Get multiple row objects. If it doesn't already exist, new empty ones will be returned
+const rows = worksheet.getRows(5, 2); // start, length (>0, else undefined is returned)
+
 // Get the last editable row in a worksheet (or undefined if there are none)
 const row = worksheet.lastRow;
 
@@ -813,23 +816,26 @@ worksheet.addRow(rowValues);
 
 // Add a row with inherited style
 // This new row will have same style as last row
-worksheet.addRow(rowValues, 'i');
+// And return as row object
+const newRow = worksheet.addRow(rowValues, 'i');
 
 // Add an array of rows
 const rows = [
   [5,'Bob',new Date()], // row by array
   {id:6, name: 'Barbara', dob: new Date()}
 ];
-worksheet.addRows(rows);
+// add new rows and return them as array of row objects
+const newRows = worksheet.addRows(rows);
 
 // Add an array of rows with inherited style
 // These new rows will have same styles as last row
-worksheet.addRows(rows, 'i');
+// and return them as array of row objects
+const newRowsStyled = worksheet.addRows(rows, 'i');
 ```
 | Parameter | Description | Default Value |
 | -------------- | ----------------- | -------- |
 | value/s    | The new row/s values |  |
-| styleOption            | 'i' for inherit from row above, 'n' for none | *'n'* |
+| style            | 'i' for inherit from row above, 'i+' to include empty cells, 'n' for none | *'n'* |
 
 ## Handling Individual Cells[⬆](#contents)<!-- Link generated with jump2header -->
 
@@ -881,8 +887,8 @@ worksheet.mergeCells(10,11,12,13);
 ## Insert Rows[⬆](#contents)<!-- Link generated with jump2header -->
 
 ```javascript
-insertRow(pos, value, styleOption = 'n')
-insertRows(pos, values, styleOption = 'n')
+insertRow(pos, value, style = 'n')
+insertRows(pos, values, style = 'n')
 
 // Insert a couple of Rows by key-value, shifting down rows every time
 worksheet.insertRow(1, {id: 1, name: 'John Doe', dob: new Date(1970,1,1)});
@@ -896,37 +902,42 @@ var rowValues = [];
 rowValues[1] = 4;
 rowValues[5] = 'Kyle';
 rowValues[9] = new Date();
-worksheet.insertRow(1, rowValues);
+// insert new row and return as row object
+const insertedRow = worksheet.insertRow(1, rowValues);
 
 // Insert a row, with inherited style
 // This new row will have same style as row on top of it
-worksheet.insertRow(1, rowValues, 'i');
+// And return as row object
+const insertedRowInherited = worksheet.insertRow(1, rowValues, 'i');
 
 // Insert a row, keeping original style
 // This new row will have same style as it was previously
-worksheet.insertRow(1, rowValues, 'o');
+// And return as row object
+const insertedRowOriginal = worksheet.insertRow(1, rowValues, 'o');
 
 // Insert an array of rows, in position 1, shifting down current position 1 and later rows by 2 rows
 var rows = [
   [5,'Bob',new Date()], // row by array
   {id:6, name: 'Barbara', dob: new Date()}
 ];
-worksheet.insertRows(1, rows);
+// insert new rows and return them as array of row objects
+const insertedRows = worksheet.insertRows(1, rows);
 
 // Insert an array of rows, with inherited style
 // These new rows will have same style as row on top of it
-worksheet.insertRows(1, rows, 'i');
+// And return them as array of row objects
+const insertedRowsInherited = worksheet.insertRows(1, rows, 'i');
 
 // Insert an array of rows, keeping original style
 // These new rows will have same style as it was previously in 'pos' position
-worksheet.insertRows(1, rows, 'o');
+const insertedRowsOriginal = worksheet.insertRows(1, rows, 'o');
 
 ```
 | Parameter | Description | Default Value |
 | -------------- | ----------------- | -------- |
 | pos          | Row number where you want to insert, pushing down all rows from there |  |
 | value/s    | The new row/s values |  |
-| styleOption            | 'i' for inherit from row above, 'o' for original style, 'n' for none | *'n'* |
+| style            | 'i' for inherit from row above, , 'i+' to include empty cells, 'o' for original style, 'o+' to include empty cells, 'n' for none | *'n'* |
 
 ## Splice[⬆](#contents)<!-- Link generated with jump2header -->
 

README_zh.md

@@ -696,6 +696,9 @@ worksheet.spliceColumns(3, 1, newCol3Values, newCol4Values);
 // 获取一个行对象。如果尚不存在，则将返回一个新的空对象
 const row = worksheet.getRow(5);
 
+// Get multiple row objects. If it doesn't already exist, new empty ones will be returned
+const rows = worksheet.getRows(5, 2); // start, length (>0, else undefined is returned)
+
 // 获取工作表中的最后一个可编辑行（如果没有，则为 `undefined`）
 const row = worksheet.lastRow;
 
@@ -795,23 +798,26 @@ worksheet.addRow(rowValues);
 
 // Add a row with inherited style
 // This new row will have same style as last row
-worksheet.addRow(rowValues, 'i');
+// And return as row object
+const newRow = worksheet.addRow(rowValues, 'i');
 
 // Add an array of rows
 const rows = [
   [5,'Bob',new Date()], // row by array
   {id:6, name: 'Barbara', dob: new Date()}
 ];
-worksheet.addRows(rows);
+// add new rows and return them as array of row objects
+const newRows = worksheet.addRows(rows);
 
 // Add an array of rows with inherited style
 // These new rows will have same styles as last row
-worksheet.addRows(rows, 'i');
+// and return them as array of row objects
+const newRowsStyled = worksheet.addRows(rows, 'i');
 ```
 | Parameter | Description | Default Value |
 | -------------- | ----------------- | -------- |
 | value/s    | The new row/s values |  |
-| styleOption            | 'i' for inherit from row above, 'n' for none | *'n'* |
+| style            | 'i' for inherit from row above, 'i+' to include empty cells, 'n' for none | *'n'* |
 
 ## 处理单个单元格[⬆](#目录)<!-- Link generated with jump2header -->
 
@@ -863,8 +869,8 @@ worksheet.mergeCells(10,11,12,13);
 ## Insert Rows[⬆](#目录)<!-- Link generated with jump2header -->
 
 ```javascript
-insertRow(pos, value, styleOption = 'n')
-insertRows(pos, values, styleOption = 'n')
+insertRow(pos, value, style = 'n')
+insertRows(pos, values, style = 'n')
 
 // Insert a couple of Rows by key-value, shifting down rows every time
 worksheet.insertRow(1, {id: 1, name: 'John Doe', dob: new Date(1970,1,1)});
@@ -878,37 +884,42 @@ var rowValues = [];
 rowValues[1] = 4;
 rowValues[5] = 'Kyle';
 rowValues[9] = new Date();
-worksheet.insertRow(1, rowValues);
+// insert new row and return as row object
+const insertedRow = worksheet.insertRow(1, rowValues);
 
 // Insert a row, with inherited style
 // This new row will have same style as row on top of it
-worksheet.insertRow(1, rowValues, 'i');
+// And return as row object
+const insertedRowInherited = worksheet.insertRow(1, rowValues, 'i');
 
 // Insert a row, keeping original style
 // This new row will have same style as it was previously
-worksheet.insertRow(1, rowValues, 'o');
+// And return as row object
+const insertedRowOriginal = worksheet.insertRow(1, rowValues, 'o');
 
 // Insert an array of rows, in position 1, shifting down current position 1 and later rows by 2 rows
 var rows = [
   [5,'Bob',new Date()], // row by array
   {id:6, name: 'Barbara', dob: new Date()}
 ];
-worksheet.insertRows(1, rows);
+// insert new rows and return them as array of row objects
+const insertedRows = worksheet.insertRows(1, rows);
 
 // Insert an array of rows, with inherited style
 // These new rows will have same style as row on top of it
-worksheet.insertRows(1, rows, 'i');
+// And return them as array of row objects
+const insertedRowsInherited = worksheet.insertRows(1, rows, 'i');
 
 // Insert an array of rows, keeping original style
 // These new rows will have same style as it was previously in 'pos' position
-worksheet.insertRows(1, rows, 'o');
+const insertedRowsOriginal = worksheet.insertRows(1, rows, 'o');
 
 ```
 | Parameter | Description | Default Value |
 | -------------- | ----------------- | -------- |
 | pos          | Row number where you want to insert, pushing down all rows from there |  |
 | value/s    | The new row/s values |  |
-| styleOption            | 'i' for inherit from row above, 'o' for original style, 'n' for none | *'n'* |
+| style            | 'i' for inherit from row above, , 'i+' to include empty cells, 'o' for original style, 'o+' to include empty cells, 'n' for none | *'n'* |
 
 ## Splice[⬆](#contents)<!-- Link generated with jump2header -->
 

index.d.ts

@@ -1178,8 +1178,21 @@ export interface Worksheet {
 	 */
 	readonly lastRow: Row | undefined;
 
+	/**
+	 * Tries to find and return row for row no, else undefined
+	 * 
+	 * @param row The 1-index row number
+	 */
 	findRow(row: number): Row | undefined;
 
+	/**
+	 * Tries to find and return rows for row no start and length, else undefined
+	 * 
+	 * @param start The 1-index starting row number
+	 * @param length The length of the expected array
+	 */
+	findRows(start: number, length: number): Row[] | undefined;
+
 	/**
 	 * Cut one or more rows (rows below are shifted up)
 	 * and optionally insert more
@@ -1192,24 +1205,24 @@ export interface Worksheet {
 	 * Add a couple of Rows by key-value, after the last current row, using the column keys,
 	 * or add a row by contiguous Array (assign to columns A, B & C)
 	 */
-	addRow(data: any[] | any, styleOption?: string): Row;
+	addRow(data: any[] | any, style?: string): Row;
 
 	/**
 	 * Add multiple rows by providing an array of arrays or key-value pairs
 	 */
-	addRows(rows: any[], styleOption?: string): void;
+	addRows(rows: any[], style?: string): Row[];
 
 	/**
 	 * Insert a Row by key-value, at the pos (shifiting down all rows from pos),
 	 * using the column keys, or add a row by contiguous Array (assign to columns A, B & C)
 	 */
-	insertRow(pos: number, value: any[] | any, styleOption?: string): Row;
+	insertRow(pos: number, value: any[] | any, style?: string): Row;
 
 	/**
 	 * Insert multiple rows at pos (shifiting down all rows from pos)
 	 * by providing an array of arrays or key-value pairs
 	 */
-	insertRows(pos: number, values: any[], styleOption?: string): void;
+	insertRows(pos: number, values: any[], style?: string): Row[];
 
 	/**
 	 * Duplicate rows and insert new rows
@@ -1221,6 +1234,11 @@ export interface Worksheet {
 	 */
 	getRow(index: number): Row;
 
+	/**
+	 * Get or create rows by 1-based index
+	 */
+	getRows(start: number, length: number): Row[];
+
 	/**
 	 * Iterate over all rows that have values in a worksheet
 	 */

lib/doc/worksheet.js

@@ -312,6 +312,11 @@ class Worksheet {
     return this._rows[r - 1];
   }
 
+  // find multiple rows (if exists) by row number
+  findRows(start, length) {
+    return this._rows.slice(start - 1, start - 1 + length);
+  }
+
   get rowCount() {
     return this._lastRowNumber;
   }
@@ -334,55 +339,68 @@ class Worksheet {
     return row;
   }
 
-  addRow(value, styleOption = 'n') {
+  // get multiple rows by row number.
+  getRows(start, length) {
+    if (length < 1) return undefined;
+    const rows = [];
+    for (let i = start; i < start + length; i++) {
+      rows.push(this.getRow(i));
+    }
+    return rows;
+  }
+
+  addRow(value, style = 'n') {
     const rowNo = this._nextRow;
     const row = this.getRow(rowNo);
     row.values = value;
-    this._setStyleOption(rowNo, styleOption === 'i' ? styleOption : 'n');
+    this._setStyleOption(rowNo, style[0] === 'i' ? style : 'n');
     return row;
   }
 
-  addRows(value, styleOption = 'n') {
+  addRows(value, style = 'n') {
+    const rows = [];
     value.forEach(row => {
-      this.addRow(row, styleOption);
+      rows.push(this.addRow(row, style));
     });
+    return rows;
   }
 
-  insertRow(pos, value, styleOption = 'n') {
+  insertRow(pos, value, style = 'n') {
     this.spliceRows(pos, 0, value);
-    this._setStyleOption(pos, styleOption);
+    this._setStyleOption(pos, style);
     return this.getRow(pos);
   }
 
-  insertRows(pos, values, styleOption = 'n') {
+  insertRows(pos, values, style = 'n') {
     this.spliceRows(pos, 0, ...values);
-    if (styleOption !== 'n') {
+    if (style !== 'n') {
       // copy over the styles
       for (let i = 0; i < values.length; i++) {
-        if (styleOption === 'o' && this.findRow(values.length + pos + i) !== undefined) {
-          this._copyStyle(values.length + pos + i, pos + i);
-        } else if (styleOption === 'i' && this.findRow(pos - 1) !== undefined) {
-          this._copyStyle(pos - 1, pos + i);
+        if (style[0] === 'o' && this.findRow(values.length + pos + i) !== undefined) {
+          this._copyStyle(values.length + pos + i, pos + i, style[1] === '+');
+        } else if (style[0] === 'i' && this.findRow(pos - 1) !== undefined) {
+          this._copyStyle(pos - 1, pos + i, style[1] === '+');
         }
       }
     }
+    return this.getRows(pos, values.length);
   }
 
   // set row at position to same style as of either pervious row (option 'i') or next row (option 'o')
-  _setStyleOption(pos, styleOption = 'n') {
-    if (styleOption === 'o' && this.findRow(pos + 1) !== undefined) {
-      this._copyStyle(pos + 1, pos);
-    } else if (styleOption === 'i' && this.findRow(pos - 1) !== undefined) {
-      this._copyStyle(pos - 1, pos);
+  _setStyleOption(pos, style = 'n') {
+    if (style[0] === 'o' && this.findRow(pos + 1) !== undefined) {
+      this._copyStyle(pos + 1, pos, style[1] === '+');
+    } else if (style[0] === 'i' && this.findRow(pos - 1) !== undefined) {
+      this._copyStyle(pos - 1, pos, style[1] === '+');
     }
   }
 
-  _copyStyle(src, dest) {
+  _copyStyle(src, dest, styleEmpty = false) {
     const rSrc = this.getRow(src);
     const rDst = this.getRow(dest);
     rDst.style = Object.freeze({...rSrc.style});
     // eslint-disable-next-line no-loop-func
-    rSrc.eachCell({includeEmpty: true}, (cell, colNumber) => {
+    rSrc.eachCell({includeEmpty: styleEmpty}, (cell, colNumber) => {
       rDst.getCell(colNumber).style = Object.freeze({...cell.style});
     });
     rDst.height = rSrc.height;