Add some methods

* `XlsxFastEditor::readArray()`
* `XlsxFastEditor::cellOrderCompare()`
* `XlsxFastEditorCell::column()`

Author: Alkarex

README.md

@@ -66,6 +66,13 @@ try {
 	$xlsxFastEditor->writeString($worksheetId1, 'D4', 'Hello');
 	$xlsxFastEditor->writeHyperlink($sheet1, 'B4', 'https://example.net/');	// Only for cells with an existing hyperlink
 
+	// Read as array
+	$table = $xlsxFastEditor->readArray($sheet1);
+	$s = $table['B'][2];
+
+	$table = $xlsxFastEditor->readArrayWithHeaders($sheet1);
+	$s = $table['columnName'][2];
+
 	// Regex search & replace operating globally on all the worksheets:
 	$xlsxFastEditor->textReplace('/Hello/i', 'World');
 
@@ -88,6 +95,7 @@ try {
 
 	// Methods for cells
 	$cellName = $cell->name();
+	$columnName = $cell->column();
 	$fx = $cell->readFormula();
 	$f = $cell->readFloat();
 	$i = $cell->readInt();

src/XlsxFastEditor.php

@@ -380,21 +380,71 @@ public function rowsIterator(int $sheetNumber): \Traversable
 	}
 
 	/**
-	 * Sort cells within the same line, such as B3, AA3. Compare only the column part.
-	 * @param $ref1 A cell reference such as B3
-	 * @param $ref1 A cell reference such as AA3
+	 * Produce an array from a worksheet, indexed by column name (like `AB`) first, then line (like `12`).
+	 * Only the existing lines and cells are included.
+	 * @return array<string,array<int,null|string>> An array that can be access like `$array['AB'][12]`
+	 */
+	public function readArray(int $sheetNumber): array
+	{
+		$table = [];
+		foreach ($this->rowsIterator($sheetNumber) as $row) {
+			foreach ($row->cellsIterator() as $cell) {
+				$table[$cell->column()][$row->number()] = $cell->readString();
+			}
+		}
+		return $table;
+	}
+
+	/**
+	 * Produce an array from a worksheet, indexed by column header (like `columnName`) first, then line (like `12`),
+	 * having the column header defined in the first existing line of the spreadsheet.
+	 * Only the existing lines and cells are included.
+	 * @return array<string,array<int,null|string>> An array that can be access like `$array['columnName'][12]`
+	 */
+	public function readArrayWithHeaders(int $sheetNumber): array
+	{
+		$table = [];
+		$headers = [];
+		$firstRow = true;
+		foreach ($this->rowsIterator($sheetNumber) as $row) {
+			if ($firstRow) {
+				foreach ($row->cellsIterator() as $cell) {
+					$headers[$cell->column()] = $cell->readString();
+				}
+				$firstRow = false;
+				continue;
+			}
+			foreach ($row->cellsIterator() as $cell) {
+				$header = $headers[$cell->column()] ?? $cell->column();
+				$table[$header][$row->number()] = $cell->readString();
+			}
+		}
+		return $table;
+	}
+
+	/**
+	 * Sort cells (such as `B3`, `AA23`) on column first (such as `B`, `AA`) and then line (such as `3`, `23`).
+	 * @param $ref1 A cell reference such as `B3`
+	 * @param $ref1 A cell reference such as `AA23`
 	 * @return int -1 if $ref1 is before $ref2; 1 if $ref1 is greater than $ref2, and 0 if they are equal.
-	 * @internal
 	 */
-	public static function _columnOrderCompare(string $ref1, string $ref2): int
+	public static function cellOrderCompare(string $ref1, string $ref2): int
 	{
-		$pattern = '/[^A-Z]+/';
-		$column1 = preg_replace($pattern, '', $ref1) ?? '';
-		$column2 = preg_replace($pattern, '', $ref2) ?? '';
-		$length1 = strlen($column1);
-		$length2 = strlen($column2);
-		if ($length1 !== $length2) {
-			return $length1 <=> $length2;
+		if (preg_match('/^([A-Z]+)(\d+)$/', $ref1, $matches1) === 1 && preg_match('/^([A-Z]+)(\d+)$/', $ref2, $matches2) === 1) {
+			$column1 = $matches1[1];
+			$column2 = $matches2[1];
+			$length1 = strlen($column1);
+			$length2 = strlen($column2);
+			if ($length1 !== $length2) {
+				return $length1 <=> $length2;
+			}
+			$cmp = strcmp($column1, $column2);
+			if ($cmp !== 0) {
+				return $cmp;
+			}
+			$line1 = (int)$matches1[2];
+			$line2 = (int)$matches2[2];
+			return $line1 <=> $line2;
 		}
 		return strcmp($ref1, $ref2);
 	}

src/XlsxFastEditorCell.php

@@ -45,6 +45,17 @@ public function name(): string
 		return $this->c->getAttribute('r');
 	}
 
+	/**
+	 * Column name (e.g., `'D'`).
+	 */
+	public function column(): string
+	{
+		if (preg_match('/^([A-Z]+)/', $this->name(), $matches) == 0 || empty($matches[1])) {
+			throw new XlsxFastEditorXmlException("Error querying column name for cell {$this->name()}!");
+		}
+		return $matches[1];
+	}
+
 	/**
 	 * Access the previous existing cell, if any, null otherwise.
 	 */
@@ -153,7 +164,6 @@ public function readString(): ?string
 
 		if ($this->c->getAttribute('t') === 's') {
 			// Shared string
-
 			if (!ctype_digit($value)) {
 				throw new XlsxFastEditorXmlException("Error querying XML fragment for shared string in cell {$this->name()}!");
 			}

src/XlsxFastEditorRow.php

@@ -139,7 +139,7 @@ public function getCell(string $cellName, int $accessMode = XlsxFastEditor::ACCE
 
 			// Excel expects the cells to be sorted
 			$sibling = $this->r->firstElementChild;
-			while ($sibling !== null && XlsxFastEditor::_columnOrderCompare($sibling->getAttribute('r'), $cellName) < 0) {
+			while ($sibling !== null && XlsxFastEditor::cellOrderCompare($sibling->getAttribute('r'), $cellName) < 0) {
 				$sibling = $sibling->nextElementSibling;
 			}
 			$this->r->insertBefore($c, $sibling);

tests/test.php

@@ -42,6 +42,9 @@
 	assert($xlsxFastEditor->readInt($sheet2, 'c3') === -5 * 2);
 	assert($xlsxFastEditor->readString($sheet2, 'B3') === 'déjà-vu');
 
+	assert($xlsxFastEditor->readArray($sheet1)['B'][2] === 'Hello');
+	assert($xlsxFastEditor->readArrayWithHeaders($sheet1)['Strings'][2] === 'Hello');
+
 	// Navigation
 	assert($xlsxFastEditor->getFirstRow($sheet1)?->number() === 1);
 	assert($xlsxFastEditor->getRow($sheet1, 1)?->getFirstCell()?->name() === 'A1');
@@ -50,6 +53,14 @@
 	assert($xlsxFastEditor->getRow($sheet1, 4)?->getCell('D4')?->name() === 'D4');
 	assert($xlsxFastEditor->getLastRow($sheet1)?->number() === 4);
 
+	assert(XlsxFastEditor::cellOrderCompare('B3', 'AA23') < 0);
+	assert(XlsxFastEditor::cellOrderCompare('AA23', 'AB23') < 0);
+	assert(XlsxFastEditor::cellOrderCompare('BB22', 'BB123') < 0);
+	assert(XlsxFastEditor::cellOrderCompare('AA23', 'AA23') === 0);
+	assert(XlsxFastEditor::cellOrderCompare('AA23', 'B3') > 0);
+	assert(XlsxFastEditor::cellOrderCompare('AB23', 'AA23') > 0);
+	assert(XlsxFastEditor::cellOrderCompare('BB123', 'BB22') > 0);
+
 	// Iterators
 	$nb = 0;
 	foreach ($xlsxFastEditor->rowsIterator($sheet1) as $row) {