Package io.keikai.api

Class A1RefUtil

java.lang.Object
io.keikai.api.A1RefUtil
public final class A1RefUtil extends Object
Utility for parsing and formatting Excel-style A1 cell and area references. Replaces the small subset of POI's org.apache.poi.ss.util.CellReference and AreaReference that the Keikai public API needs, without pulling POI onto the customer-visible classpath.

Reference: ECMA-376 Part 1 §18.17.2.3 (A1-style references).

Since:
7.0.0

  • Method Details

    • columnIndexToString

      public static String columnIndexToString(int col)
      Converts a 0-based column index to its A1-style column letters (e.g. 0 -> "A", 25 -> "Z", 26 -> "AA").

    • columnStringToIndex

      public static int columnStringToIndex(String letters)
      Parses an A1-style column letter sequence to its 0-based column index. Accepts upper or lower case.

    • formatCell

      public static String formatCell(String sheetName, int row, int col, boolean absRow, boolean absCol)
      Formats a single cell reference. sheetName may be null for an unqualified reference; if present, sheet names containing spaces, single quotes, or other punctuation are wrapped in single quotes per Excel's quoting rules. absRow / absCol prepend $ when true.

    • formatCell

      public static String formatCell(int row, int col)
      Convenience: relative cell reference without sheet name.

    • formatArea

      public static String formatArea(String sheetName, int row1, int col1, int row2, int col2, boolean absRow, boolean absCol)
      Formats an area (range) reference. Collapses to a single-cell reference when both corners are equal. Sheet name (if non-null) is rendered once, on the leading cell.

    • formatArea

      public static String formatArea(int row1, int col1, int row2, int col2)
      Convenience: relative area reference without sheet name.

    • formatAreaKeepColon

      public static String formatAreaKeepColon(String sheetName, int row1, int col1, int row2, int col2, boolean absRow, boolean absCol)
      Same as formatArea(String, int, int, int, int, boolean, boolean) but never collapses a degenerate single-cell area to the bare cell form — a single-cell area is always rendered as A1:A1 (with the colon), matching POI's AreaReference.formatAsString() behavior.

      Used by the API Range.asString() path so that an AREA-typed precedent that happens to be a single cell still round-trips as A1:A1. Callers that want the collapsing behavior (e.g. CellRegion.getReferenceString) should keep using formatArea(java.lang.String, int, int, int, int, boolean, boolean).

    • parseArea

      public static int[] parseArea(String ref)
      Parses an A1-style area reference into a 4-int array [row1, col1, row2, col2], all 0-based. Accepts:
      • "A1" — single cell
      • "A1:B5" — area
      • "Sheet1!A1:B5" — qualified
      • "'Sheet 1'!A1:B5" — quoted sheet name
      Absolute markers $ are accepted and ignored. Sheet name (if any) is discarded — the returned 4-int has only coordinates.
      Throws:
      IllegalArgumentException - if the reference is malformed.

    • isSingleCell

      public static boolean isSingleCell(String ref)
      Returns:
      true if the parsed area is a single cell.

    • parseAreaLenient

      public static int[] parseAreaLenient(String ref)
      Lenient variant of parseArea(String) that accepts row-only and column-only references in addition to the standard cell-anchor forms:
      • "1:2" — rows 1-2, all columns. Returns {0, -1, 1, -1}.
      • "A:C" — columns A-C, all rows. Returns {-1, 0, -1, 2}.
      • "A1:B5" — full cell range, same as parseArea(String).
      Sheet prefix is stripped; absolute markers are accepted and ignored. -1 sentinels let callers substitute sheet-default boundaries.

    • extractSheetName

      public static String extractSheetName(String ref)
      Returns the sheet name from a qualified reference, or null if the reference has no sheet prefix. Quoted sheet names are unquoted (and embedded '' unescaped to ').

    • unquoteSheetName

      public static String unquoteSheetName(String name)
      Strips Excel-style sheet-name quoting from name when present. 'My Sheet' -> My Sheet; 'It''s' -> It's; bare names returned as-is. Replaces POI's SheetNameFormatter.unformat.

    • quoteSheetName

      public static String quoteSheetName(String name)
      Quotes a sheet name if it contains characters that require it (anything other than letters/digits/underscore). Embedded apostrophes are doubled. Returns the name as-is if no quoting is needed. Replaces POI's SheetNameFormatter.format.