github-55: document that CellReference#isRowWithinRange(String rowNum, SpreadsheetVersion ss) expects rowNum to be parseable as an integer

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1795681 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/poi/ss/util/CellReference.java

@@ -132,6 +132,7 @@ public class CellReference {
         if (rowRef.length() == 0) {
             _rowIndex = -1;
         } else {
+            // throws NumberFormatException if rowRef is not convertable to an int
             _rowIndex = Integer.parseInt(rowRef)-1; // -1 to convert 1-based to zero-based
         }
     }
@@ -342,8 +343,24 @@ public class CellReference {
         return true;
     }
 
+    /**
+     * Determines whether {@code rowStr} is a valid row number for a given SpreadsheetVersion.
+     * @param rowStr  the numeric portion of an A1-style cell reference (1-based index)
+     * @param ssVersion  the spreadsheet version
+     * @throws NumberFormatException if rowStr is not parseable as an integer
+     */
     public static boolean isRowWithinRange(String rowStr, SpreadsheetVersion ssVersion) {
-        int rowNum = Integer.parseInt(rowStr) - 1;
+        final int rowNum = Integer.parseInt(rowStr) - 1;
+        return isRowWithinRange(rowNum, ssVersion);
+    }
+
+    /**
+     * Determines whether {@code row} is a valid row number for a given SpreadsheetVersion.
+     * @param rowNum  the row number (0-based index)
+     * @param ssVersion  the spreadsheet version
+     * @since 3.17 beta 1
+     */
+    public static boolean isRowWithinRange(int rowNum, SpreadsheetVersion ssVersion) {
         return 0 <= rowNum && rowNum <= ssVersion.getLastRowIndex();
     }
 

src/testcases/org/apache/poi/ss/util/TestCellReference.java

@@ -353,8 +353,26 @@ public final class TestCellReference {
         assertTrue("first row", CellReference.isRowWithinRange("1", ss));
         assertTrue("last row", CellReference.isRowWithinRange("1048576", ss));
         assertFalse("1 beyond last row", CellReference.isRowWithinRange("1048577", ss));
+
+        // int versions of above, using 0-based indices
+        assertFalse("1 before first row", CellReference.isRowWithinRange(-1, ss));
+        assertTrue("first row", CellReference.isRowWithinRange(0, ss));
+        assertTrue("last row", CellReference.isRowWithinRange(1048575, ss));
+        assertFalse("1 beyond last row", CellReference.isRowWithinRange(1048576, ss));
+    }
+
+    @Test(expected=NumberFormatException.class)
+    public void isRowWithinRangeNonInteger_BigNumber() {
+        String rowNum = "4000000000";
+        CellReference.isRowWithinRange(rowNum, SpreadsheetVersion.EXCEL2007);
     }
     
+    @Test(expected=NumberFormatException.class)
+    public void isRowWithinRangeNonInteger_Alpha() {
+        String rowNum = "NotANumber";
+        CellReference.isRowWithinRange(rowNum, SpreadsheetVersion.EXCEL2007);
+    }
+
     @Test
     public void isColWithinRange() {
         SpreadsheetVersion ss = SpreadsheetVersion.EXCEL2007;