@ex-grid/sheet-engine 0.2.0-beta.3 → 0.2.0-rc.2

package/dist/index.d.ts

@@ -1391,6 +1391,21 @@ declare class MissingNode extends NodeBase {
     static isEmpty(argument: Node_2): boolean;
 }
 
+/**
+ * The Reference `reference` rewritten to name `range`, written as `reference` was (ADR-0480, section 1): what a
+ * Reference Outline dragged by its edge or its corner square leaves in the Formula. Each part keeps its `$`; a
+ * Sheet qualifier is kept as typed; a one-cell Reference made a range writes both ends in its form, and a range
+ * made one cell writes it once, in its first end's form. Whole columns (rows) that still span every row (column) of
+ * `size` stay whole columns (rows), each end keeping its `$`; resized so that they no longer do, they are written as
+ * the cells they name, the columns' (rows') `$` kept. Column letters are written in upper case. Throws a RangeError
+ * when `reference` is not one Reference over the whole of it, or `range` does not lie inside `size`.
+ *
+ * @param reference - The Reference's text as it stands in the Formula: `$A$1`, `Sheet1!B2:C3`, `A:A`.
+ * @param range - The cells it is to name.
+ * @param size - The Sheet's size (ADR-0460), against which "every row" and "every column" are read.
+ */
+export declare function moveReference(reference: string, range: CellRange, size?: SheetSize): string;
+
 /**
  * A name that is not a function call, a Reference or a boolean. ExSheet defines no names of its own, so it is
  * `#NAME?` — unless a `LET` around it binds it (ADR-0181).

package/dist/index.js

@@ -11397,6 +11397,52 @@ function dateTimeText(serial, culture) {
   return hasTime ? `${date} ${time2.format(Value.fromNumber(serial), culture).text}` : date;
 }
 
+// src/sheet-size.ts
+var SheetSize = class _SheetSize {
+  /** Excel's full size, 1,048,576 rows by 16,384 columns (`A1` to `XFD1048576`): what a Sheet holds unless given another. */
+  static excel = new _SheetSize(rowCount, columnCount);
+  /** How many rows, from 1 to 1,048,576. */
+  rows;
+  /** How many columns, from 1 to 16,384. */
+  columns;
+  /** A size of `rows` by `columns`; one of no rows or no columns, or larger than Excel's, is refused with a `RangeError`. */
+  constructor(rows, columns) {
+    if (!Number.isInteger(rows) || rows < 1 || rows > rowCount) {
+      throw new RangeError(`A Sheet holds from 1 to 1,048,576 rows; ${String(rows)} is not that.`);
+    }
+    if (!Number.isInteger(columns) || columns < 1 || columns > columnCount) {
+      throw new RangeError(`A Sheet holds from 1 to 16,384 columns; ${String(columns)} is not that.`);
+    }
+    this.rows = rows;
+    this.columns = columns;
+  }
+  /** The last cell inside the size: `XFD1048576` for Excel's, `J10` for ten by ten. */
+  get lastCell() {
+    return new CellAddress(this.rows - 1, this.columns - 1);
+  }
+  /** Whether `address` lies inside the size. */
+  contains(address) {
+    return address.row < this.rows && address.column < this.columns;
+  }
+  /** Whether a block of `rows` × `columns` with its top-left cell at `origin` lies wholly inside the size. */
+  holds(origin, rows, columns) {
+    return origin.row + rows <= this.rows && origin.column + columns <= this.columns;
+  }
+  /**
+   * `range` as it stands inside the size, or `undefined` when it runs past it. Whole columns and whole rows are
+   * Excel's lines, inside when their columns or rows are, and are answered as long as the size's: `B:B` of ten rows
+   * is `B1:B10`.
+   */
+  fit(range) {
+    const last = new CellAddress(range.isWholeColumns ? this.rows - 1 : range.last.row, range.isWholeRows ? this.columns - 1 : range.last.column);
+    return this.contains(last) && this.contains(range.first) ? new CellRange(range.first, last) : void 0;
+  }
+  /** Whether the two are the same size. */
+  equals(other) {
+    return this.rows === other.rows && this.columns === other.columns;
+  }
+};
+
 // src/formula-entry.ts
 var LinkedTableColumn = class {
   /** The table's name, as written. */
@@ -11460,6 +11506,36 @@ function referenceText(range, sheet) {
   if (sheet.length === 0) throw new RangeError("The Sheet name is empty.");
   return `${quoteSheetName(sheet)}!${range.toString()}`;
 }
+function moveReference(reference, range, size = SheetSize.excel) {
+  const match = reference.length === 0 ? void 0 : matchReference(reference, 0);
+  if (match?.index !== 0 || match.length !== reference.length) {
+    throw new RangeError(`'${reference}' is not one Reference over the whole of it.`);
+  }
+  if (!size.contains(range.last)) throw new RangeError(`${range.toString()} does not lie inside the Sheet's ${String(size.rows)} rows by ${String(size.columns)} columns.`);
+  const group3 = (name) => match.groups[name];
+  const absolute = (name) => group3(name)?.value.startsWith("$") === true;
+  const firstPart = group3("c1") ?? group3("cc1") ?? group3("rr1");
+  if (firstPart === void 0) throw new Error("Internal: a Reference matched without a column or a row.");
+  const qualifier = reference.slice(0, firstPart.index);
+  const everyRow = range.first.row === 0 && range.last.row === size.rows - 1;
+  const everyColumn = range.first.column === 0 && range.last.column === size.columns - 1;
+  if (group3("cc1") !== void 0 && everyRow) {
+    return `${qualifier}${columnPart(range.first.column, absolute("cc1"))}:${columnPart(range.last.column, absolute("cc2"))}`;
+  }
+  if (group3("rr1") !== void 0 && everyColumn) {
+    return `${qualifier}${rowPart(range.first.row, absolute("rr1"))}:${rowPart(range.last.row, absolute("rr2"))}`;
+  }
+  const [first, second] = group3("cc1") !== void 0 ? [{ column: absolute("cc1"), row: false }, { column: absolute("cc2"), row: false }] : group3("rr1") !== void 0 ? [{ column: false, row: absolute("rr1") }, { column: false, row: absolute("rr2") }] : [{ column: absolute("c1"), row: absolute("r1") }, group3("c2") === void 0 ? { column: absolute("c1"), row: absolute("r1") } : { column: absolute("c2"), row: absolute("r2") }];
+  const start = columnPart(range.first.column, first.column) + rowPart(range.first.row, first.row);
+  if (range.cellCount === 1) return qualifier + start;
+  return `${qualifier}${start}:${columnPart(range.last.column, second.column)}${rowPart(range.last.row, second.row)}`;
+}
+function columnPart(index, absolute) {
+  return (absolute ? "$" : "") + CellAddress.columnName(index);
+}
+function rowPart(index, absolute) {
+  return `${absolute ? "$" : ""}${String(index + 1)}`;
+}
 function structuredReferenceText2(table2, column2) {
   if (table2.length === 0) throw new RangeError("The table name is empty.");
   if (column2.length === 0) throw new RangeError("The column name is empty.");
@@ -15892,52 +15968,6 @@ function recorded(cell) {
   return text2;
 }
 
-// src/sheet-size.ts
-var SheetSize = class _SheetSize {
-  /** Excel's full size, 1,048,576 rows by 16,384 columns (`A1` to `XFD1048576`): what a Sheet holds unless given another. */
-  static excel = new _SheetSize(rowCount, columnCount);
-  /** How many rows, from 1 to 1,048,576. */
-  rows;
-  /** How many columns, from 1 to 16,384. */
-  columns;
-  /** A size of `rows` by `columns`; one of no rows or no columns, or larger than Excel's, is refused with a `RangeError`. */
-  constructor(rows, columns) {
-    if (!Number.isInteger(rows) || rows < 1 || rows > rowCount) {
-      throw new RangeError(`A Sheet holds from 1 to 1,048,576 rows; ${String(rows)} is not that.`);
-    }
-    if (!Number.isInteger(columns) || columns < 1 || columns > columnCount) {
-      throw new RangeError(`A Sheet holds from 1 to 16,384 columns; ${String(columns)} is not that.`);
-    }
-    this.rows = rows;
-    this.columns = columns;
-  }
-  /** The last cell inside the size: `XFD1048576` for Excel's, `J10` for ten by ten. */
-  get lastCell() {
-    return new CellAddress(this.rows - 1, this.columns - 1);
-  }
-  /** Whether `address` lies inside the size. */
-  contains(address) {
-    return address.row < this.rows && address.column < this.columns;
-  }
-  /** Whether a block of `rows` × `columns` with its top-left cell at `origin` lies wholly inside the size. */
-  holds(origin, rows, columns) {
-    return origin.row + rows <= this.rows && origin.column + columns <= this.columns;
-  }
-  /**
-   * `range` as it stands inside the size, or `undefined` when it runs past it. Whole columns and whole rows are
-   * Excel's lines, inside when their columns or rows are, and are answered as long as the size's: `B:B` of ten rows
-   * is `B1:B10`.
-   */
-  fit(range) {
-    const last = new CellAddress(range.isWholeColumns ? this.rows - 1 : range.last.row, range.isWholeRows ? this.columns - 1 : range.last.column);
-    return this.contains(last) && this.contains(range.first) ? new CellRange(range.first, last) : void 0;
-  }
-  /** Whether the two are the same size. */
-  equals(other) {
-    return this.rows === other.rows && this.columns === other.columns;
-  }
-};
-
 // src/sheet-edit.ts
 var alignments = ["general", "left", "center", "right"];
 var fillDirections = ["down", "right", "up", "left"];
@@ -17761,6 +17791,7 @@ export {
   formulaReferences,
   lookupFinds,
   lookupText,
+  moveReference,
   numberFormatColourRgb,
   readCellFormatChange,
   readLinkedRows,