Package io.keikai.axyra.sheets

Class Range

java.lang.Object
io.keikai.axyra.sheets.Range
public final class Range extends Object
A rectangular block of cells — the bulk API. A (Sheet, rect) view holding no native resource; every read/write crosses JNI once for the whole rectangle (never once per cell).

Reads come back via the structure-of-arrays codec and are reassembled into CellValue[][] in pure Java; the numeric fast path (numbers()) returns a primitive double[] directly.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    CONTENT_COMMENT
    contentFlags() bit: the cell carries a comment.
    static final int
    CONTENT_HYPERLINK
    contentFlags() bit: the cell carries a hyperlink.
    static final int
    CONTENT_RICH_TEXT
    contentFlags() bit: the cell's text is rich (more than one run).

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addConditionalFormat(ConditionalFormat format)
    Attach a conditional-formatting rule to this rectangle.
    void
    applyNamedStyle(String name)
    Apply a previously registered named cell style to every cell in the rectangle.
    void
    autoFill(Range destination)
    Auto-fill: detect a pattern in this range (linear numeric series, or a cyclic copy for text and mixed content) and extend it across destination — Excel's fill-handle drag.
    int
    autoMerge(boolean horizontal)
    Auto-merge runs of adjacent cells with identical, non-empty content — left-to-right within each row when horizontal is true, otherwise top-to-bottom within each column.
    void
    clear()
    Clear every cell in the rectangle (value and formula).
    int
    clearHyperlinks()
    Remove every hyperlink in the rectangle, keeping the cell values.
    int
    colCount()
    Number of columns in the rectangle.
    byte[]
    contentFlags()
    Row-major per-cell content flags — each entry is a bitwise OR of CONTENT_COMMENT, CONTENT_HYPERLINK and CONTENT_RICH_TEXT (0 = none).
    void
    copyTo(Sheet dstSheet, int dstRow, int dstCol)
    Copy this rectangle to (dstRow, dstCol) on dstSheet (Excel's Copy → Paste).
    void
    copyTo(Sheet dstSheet, int dstRow, int dstCol, String pasteType)
    Copy this rectangle with an Excel Paste-Special mode: "all" / "values" / "formulas" / "formats" / "comments".
    void
    createTable(String name, String... columnNames)
    Create a table (ListObject) over this rectangle.
    void
    deleteCells(Shift shift)
    Delete the rectangle's cells, shifting remaining cells Shift.UP or Shift.LEFT.
    int
    firstColumn()
    First (left) column, 0-based inclusive.
    int
    firstRow()
    First (top) row, 0-based inclusive.
    String[][]
    formulas()
    Read every cell's formula source.
    void
    insertCells(Shift shift)
    Insert blank cells over the rectangle, shifting existing cells Shift.DOWN or Shift.RIGHT.
    int
    lastColumn()
    Last (right) column, 0-based inclusive.
    int
    lastRow()
    Last (bottom) row, 0-based inclusive.
    void
    merge()
    Merge the rectangle into a single cell.
    double[]
    numbers()
    Read the rectangle as a row-major double[].
    int
    removeDuplicates(int[] keyColumns, boolean hasHeader)
    Remove duplicate rows in the rectangle, comparing the given key columns.
    int
    rowCount()
    Number of rows in the rectangle.
    void
    setArrayFormula(String formula)
    Set a CSE (Ctrl+Shift+Enter) array formula over the whole rectangle, anchored at the top-left cell.
    void
    setFormula(String formula)
    Fill the rectangle with one formula, as Excel's Ctrl+Enter does: the formula is written for the top-left cell, and every other cell gets it with its relative references shifted by its offset from there (A1*B1 on C1:C3 becomes A2*B2 in C2 and A3*B3 in C3); $-anchored references stay put.
    void
    setFormulas(String[][] formulas)
    Write per-cell formulas (rowCount() x colCount()).
    void
    setNumbers(double[] data)
    Write the rectangle from a row-major double[] of length rowCount() * colCount().
    void
    setStyle(CellStyle style)
    Apply a style to every cell in the rectangle.
    void
    setValidation(Validation validation)
    Attach a data-validation rule to this rectangle.
    void
    setValues(CellValue[][] values)
    Write every cell from a CellValue[][] (row-major, rowCount() x colCount()).
    int
    sheetIndex()
    The 0-based index of the sheet this range belongs to.
    void
    sort(int column, boolean ascending)
    Sort ascending/descending on a single column.
    void
    sort(SortKey... keys)
    Sort the rectangle by one or more keys (first key is primary).
    void
    sortLeftToRight(SortKey... keys)
    Sort left to right (Excel's Sort Options → "Sort left to right"): reorder whole columns within the rectangle by the values of one or more key rows.
    String
    spillRange()
    The A1 reference of the dynamic-array spill (or legacy CSE array) region containing this range's top-left cell — e.g.
    CellStyle
    style()
    The style of the top-left cell of the rectangle.
    int[]
    styleIds()
    Row-major per-cell style ids (an engine-internal dedup index).
    void
    unmerge()
    Unmerge any merged regions overlapping the rectangle.
    CellValue[][]
    values()
    Read every cell as a CellValue.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

  • Method Details

    • firstRow

      public int firstRow()
      First (top) row, 0-based inclusive.

    • firstColumn

      public int firstColumn()
      First (left) column, 0-based inclusive.

    • lastRow

      public int lastRow()
      Last (bottom) row, 0-based inclusive.

    • lastColumn

      public int lastColumn()
      Last (right) column, 0-based inclusive.

    • sheetIndex

      public int sheetIndex()
      The 0-based index of the sheet this range belongs to.

    • rowCount

      public int rowCount()
      Number of rows in the rectangle.

    • colCount

      public int colCount()
      Number of columns in the rectangle.

    • values

      public CellValue[][] values()
      Read every cell as a CellValue. One JNI crossing; formula cells evaluate lazily on the engine side.

    • numbers

      public double[] numbers()
      Read the rectangle as a row-major double[]. Only numeric cells carry a value; every other cell (blank, text, bool, error) is NaN. One JNI crossing.

    • setNumbers

      public void setNumbers(double[] data)
      Write the rectangle from a row-major double[] of length rowCount() * colCount(). Like setValues(io.keikai.axyra.sheets.CellValue[][]), this replaces values only: each cell keeps its style (number format, font, fill), comment and hyperlink, and a formula there is dropped. One JNI crossing.

    • setValues

      public void setValues(CellValue[][] values)
      Write every cell from a CellValue[][] (row-major, rowCount() x colCount()). Encodes to the SoA codec in pure Java, then one JNI crossing. Each cell's value is replaced and any formula cleared; CellValue.BLANK clears the cell.

    • formulas

      public String[][] formulas()
      Read every cell's formula source. One JNI crossing. Entry is null for a non-formula cell, else the verbatim formula text (no leading "=").

    • setFormula

      public void setFormula(String formula)
      Fill the rectangle with one formula, as Excel's Ctrl+Enter does: the formula is written for the top-left cell, and every other cell gets it with its relative references shifted by its offset from there (A1*B1 on C1:C3 becomes A2*B2 in C2 and A3*B3 in C3); $-anchored references stay put. Use setFormulas(String[][]) to give each cell its own text. One JNI crossing.
      Throws:
      AxyraFormulaException - if the formula is not valid

    • setFormulas

      public void setFormulas(String[][] formulas)
      Write per-cell formulas (rowCount() x colCount()). A null entry leaves the cell unchanged; an empty string clears it. One crossing.

    • setArrayFormula

      public void setArrayFormula(String formula)
      Set a CSE (Ctrl+Shift+Enter) array formula over the whole rectangle, anchored at the top-left cell. The engine spills the result across the range. One JNI crossing.

    • copyTo

      public void copyTo(Sheet dstSheet, int dstRow, int dstCol)
      Copy this rectangle to (dstRow, dstCol) on dstSheet (Excel's Copy → Paste). Values, formulas, styles and comments are copied; relative references in formulas adjust by the paste offset, and dependents of the pasted cells recalculate.

    • copyTo

      public void copyTo(Sheet dstSheet, int dstRow, int dstCol, String pasteType)
      Copy this rectangle with an Excel Paste-Special mode: "all" / "values" / "formulas" / "formats" / "comments".

    • spillRange

      public String spillRange()
      The A1 reference of the dynamic-array spill (or legacy CSE array) region containing this range's top-left cell — e.g. "A1:A3", or a single cell like "A1" for a 1x1 array result. Returns null when the cell is not part of an array region. Dynamic spills exist only after the anchor formula has evaluated (read the value or recalculate first).

    • setStyle

      public void setStyle(CellStyle style)
      Apply a style to every cell in the rectangle. The engine dedups identical styles, so this interns the style (one crossing) then assigns its id (one crossing).

    • applyNamedStyle

      public void applyNamedStyle(String name)
      Apply a previously registered named cell style to every cell in the rectangle. No-op if name is not registered.

    • style

      public CellStyle style()
      The style of the top-left cell of the rectangle. One JNI crossing pair.

    • styleIds

      public int[] styleIds()
      Row-major per-cell style ids (an engine-internal dedup index). One crossing.

    • contentFlags

      public byte[] contentFlags()
      Row-major per-cell content flags — each entry is a bitwise OR of CONTENT_COMMENT, CONTENT_HYPERLINK and CONTENT_RICH_TEXT (0 = none). One JNI crossing: the bulk presence probe matching Cell.comment(), Cell.hyperlink() and Cell.richRunCount(), so callers can locate the few cells carrying sidecar content without one crossing per cell.

    • sort

      public void sort(SortKey... keys)
      Sort the rectangle by one or more keys (first key is primary). Sort-key columns are range-relative (0 = the range's first column). A key carrying a custom order sorts its matching values by list position (Excel's "Custom Lists"); unlisted values sort after all listed ones.

    • sort

      public void sort(int column, boolean ascending)
      Sort ascending/descending on a single column.

    • sortLeftToRight

      public void sortLeftToRight(SortKey... keys)
      Sort left to right (Excel's Sort Options → "Sort left to right"): reorder whole columns within the rectangle by the values of one or more key rows. Each key's SortKey.column() is the range-relative key row (0 = the range's first row); custom orders apply as in sort(SortKey...).

    • autoFill

      public void autoFill(Range destination)
      Auto-fill: detect a pattern in this range (linear numeric series, or a cyclic copy for text and mixed content) and extend it across destination — Excel's fill-handle drag. As in Excel, the destination must be on the same sheet, include this source range, and extend it along exactly one axis (same columns to fill down/up, or same rows to fill right/left). Source cells keep their values.

    • removeDuplicates

      public int removeDuplicates(int[] keyColumns, boolean hasHeader)
      Remove duplicate rows in the rectangle, comparing the given key columns. Key columns are range-relative (0 = the range's first column), as in sort(SortKey...) and Excel's Remove Duplicates. Returns the number of rows removed.
      Throws:
      IllegalArgumentException - if keyColumns is empty or a key column lies outside the range

    • setValidation

      public void setValidation(Validation validation)
      Attach a data-validation rule to this rectangle.

    • addConditionalFormat

      public void addConditionalFormat(ConditionalFormat format)
      Attach a conditional-formatting rule to this rectangle.

    • createTable

      public void createTable(String name, String... columnNames)
      Create a table (ListObject) over this rectangle. With explicit columnNames the header row is set to those names; with none, the column names are read from this rectangle's own header row (row 1 of the range) — Excel's "Format as Table" over a range. Empty or duplicate headers fall back to generated ColumnN names.

    • merge

      public void merge()
      Merge the rectangle into a single cell.

    • unmerge

      public void unmerge()
      Unmerge any merged regions overlapping the rectangle.

    • autoMerge

      public int autoMerge(boolean horizontal)
      Auto-merge runs of adjacent cells with identical, non-empty content — left-to-right within each row when horizontal is true, otherwise top-to-bottom within each column. Returns the number of regions created.

    • insertCells

      public void insertCells(Shift shift)
      Insert blank cells over the rectangle, shifting existing cells Shift.DOWN or Shift.RIGHT.

    • deleteCells

      public void deleteCells(Shift shift)
      Delete the rectangle's cells, shifting remaining cells Shift.UP or Shift.LEFT.

    • clearHyperlinks

      public int clearHyperlinks()
      Remove every hyperlink in the rectangle, keeping the cell values. Returns the number of hyperlinks removed. One JNI crossing.

    • clear

      public void clear()
      Clear every cell in the rectangle (value and formula). One JNI crossing.