Add doc about faster functions

Author: Alkarex

README.md

@@ -86,11 +86,11 @@ try {
 
 	// Methods for rows
 	$rowNumber = $row->number();
+	$cell = $row->getCellOrNull('D2');
+	$cell = $row->getCellOrNull('D');
 
 	// Navigation methods for existing cells
 	$cell = $row->getFirstCell();
-	$cell = $row->getCellOrNull('D2');
-	$cell = $row->getCellOrNull('D');
 	$cell = $cell->getPreviousCell();
 	$cell = $cell->getNextCell();
 	$cell = $row->getLastCell();
@@ -125,6 +125,10 @@ try {
 }
 ```
 
+## Tips
+
+* ℹ️ Iterators (`rowsIterator()`, `cellsIterator()`) and navigation methods (`getNextCell()`, etc.) are faster than accessing a cell by name (`getCellOrNull()`) or a row by number (`getRow()`).
+
 ## Requirements
 
 PHP 7.4+ with ZIP and XML extensions.

composer.json

@@ -40,7 +40,7 @@
 		"php-lint": "find . -type d -name 'vendor' -prune -o -name '*.php' -print0 | xargs -0 -n1 -P4 php -l 1>/dev/null",
 		"phpcs": "phpcs . -s",
 		"phpcbf": "phpcbf . -p -s",
-		"phpstan": "phpstan analyse --memory-limit 512M .",
+		"phpstan": "phpstan analyse .",
 		"asserts": "php -d zend.assertions tests/test.php",
 		"test": [
 			"@php-lint",

src/XlsxFastEditor.php

@@ -576,6 +576,10 @@ public static function cellOrderCompare(string $ref1, string $ref2): int
 	 * Access the specified cell in the specified worksheet. Can create it automatically if asked to.
 	 * The corresponding row can also be automatically created if it does not exist already, but the worksheet cannot be automatically created.
 	 *
+	 * ℹ️ Instead of calling multiple times this function, consider the faster navigation methods
+	 * `XlsxFastEditor::rowsIterator()`, `XlsxFastEditor::getFirstRow()`, `XlsxFastEditorRow::cellsIterator()`,
+	 * `XlsxFastEditorRow::getNextRow()`, `XlsxFastEditorRow::getFirstCell()`, `XlsxFastEditorCell::getNextCell()`, etc.
+	 *
 	 * @param int $sheetNumber Worksheet number (base 1)
 	 * @param string $cellName Cell name such as `B4`
 	 * @param int $accessMode To control the behaviour when the cell does not exist:
@@ -631,6 +635,11 @@ public function getCell(int $sheetNumber, string $cellName, int $accessMode = Xl
 
 	/**
 	 * Access the specified cell in the specified worksheet, or null if if does not exist.
+	 *
+	 * ℹ️ Instead of calling multiple times this function, consider the faster navigation methods
+	 * `XlsxFastEditor::rowsIterator()`, `XlsxFastEditor::getFirstRow()`, `XlsxFastEditorRow::cellsIterator()`,
+	 * `XlsxFastEditorRow::getNextRow()`, `XlsxFastEditorRow::getFirstCell()`, `XlsxFastEditorCell::getNextCell()`, etc.
+	 *
 	 * @param int $sheetNumber Worksheet number (base 1)
 	 * @param string $cellName Cell name such as `B4`
 	 * @return XlsxFastEditorCell|null A cell, potentially `null` if the cell does not exist

src/XlsxFastEditorCell.php

@@ -62,6 +62,7 @@ public function column(): string
 
 	/**
 	 * Access the previous existing cell, if any, `null` otherwise.
+	 * ℹ️ This is a faster method than `XlsxFastEditorRow::getCellOrNull()`
 	 */
 	public function getPreviousCell(): ?XlsxFastEditorCell
 	{
@@ -77,6 +78,7 @@ public function getPreviousCell(): ?XlsxFastEditorCell
 
 	/**
 	 * Access the next existing cell, if any, `null` otherwise.
+	 * ℹ️ This is a faster method than `XlsxFastEditorRow::getCellOrNull()`
 	 */
 	public function getNextCell(): ?XlsxFastEditorCell
 	{

src/XlsxFastEditorRow.php

@@ -50,6 +50,7 @@ private function getXPath(): \DOMXPath
 
 	/**
 	 * Access the previous existing row, if any, `null` otherwise.
+	 * ℹ️ This is a faster method than `XlsxFastEditor::getRow()`
 	 */
 	public function getPreviousRow(): ?XlsxFastEditorRow
 	{
@@ -65,6 +66,7 @@ public function getPreviousRow(): ?XlsxFastEditorRow
 
 	/**
 	 * Access the next existing row, if any, `null` otherwise.
+	 * ℹ️ This is a faster method than `XlsxFastEditor::getRow()`
 	 */
 	public function getNextRow(): ?XlsxFastEditorRow
 	{
@@ -80,6 +82,7 @@ public function getNextRow(): ?XlsxFastEditorRow
 
 	/**
 	 * To iterate over all the existing cells of the row.
+	 * ℹ️ This is a faster method than `XlsxFastEditorRow::getCellOrNull()`
 	 * @return \Traversable<XlsxFastEditorCell>
 	 */
 	public function cellsIterator(): \Traversable
@@ -95,6 +98,7 @@ public function cellsIterator(): \Traversable
 
 	/**
 	 * Get the first existing cell for a given line.
+	 * ℹ️ This is a faster method than `XlsxFastEditorRow::getCellOrNull()`
 	 * @return XlsxFastEditorCell|null The first cell of the given line if it exists, `null` otherwise.
 	 */
 	public function getFirstCell(): ?XlsxFastEditorCell
@@ -111,6 +115,10 @@ public function getFirstCell(): ?XlsxFastEditorCell
 
 	/**
 	 * Get the cell of the given name if it exists.
+	 *
+	 * ℹ️ Instead of calling multiple times this function, consider the faster navigation methods
+	 * `XlsxFastEditorRow::cellsIterator()`, `XlsxFastEditorRow::getFirstCell()`, `XlsxFastEditorCell::getNextCell()`, etc.
+	 *
 	 * @param string $cellName Column name such as `'B'` or full cell name such as `'B4'`
 	 * @param int $accessMode To control the behaviour when the cell does not exist:
 	 * set to `XlsxFastEditor::ACCESS_MODE_NULL` to return `null` (default),
@@ -180,6 +188,10 @@ public function getCell(string $cellName, int $accessMode = XlsxFastEditor::ACCE
 
 	/**
 	 * Get the cell of the given name, or null if if does not exist.
+	 *
+	 * ℹ️ Instead of calling multiple times this function, consider the faster navigation methods
+	 * `XlsxFastEditorRow::cellsIterator()`, `XlsxFastEditorRow::getFirstCell()`, `XlsxFastEditorCell::getNextCell()`, etc.
+	 *
 	 * @param string $cellName Column name such as `'B'` or full cell name such as `'B4'`
 	 * @return XlsxFastEditorCell|null A cell, potentially `null` if the cell does not exist
 	 * @throws \InvalidArgumentException if `$cellName` has an invalid format

tests/test.php

@@ -157,7 +157,7 @@
 
 	// Verify by hand that the resulting file opens without warning in Microsoft Excel.
 	// Verify by hand that the cell Sheet1!E4 has its formula recalculated (to -999) when opening in Excel.
-	// unlink(__DIR__ . '/copy.xlsx');
+	// unlink(__DIR__ . '/_copy.xlsx');
 } catch (XlsxFastEditorException $xlsxe) {
 	die($xlsxe);
 }